Your Guide to Integrations with Digital River

Transcription

1 Digital River, Inc Your Guide to Integrations with Digital River Single Sign-On 8/3/2010 Document Version 1.2

2 Contents Introduction... 3 Terms, Shapes, and Definitions... 4 Typical High Level Work Flows... 5 Customer Authenticates on Client s Site... 5 Customer Authenticates on Digital River Hosted Shopping Site... 7 Elements of Single Sign-On Integrations... 8 Remote Session Validation... 8 Remote User Fetch Remote Login Remote Create User User Key Flow

3 Introduction Single Sign-On provides a seamless shopping experience for the customer who navigates from the client site to the Digital River hosted shopping site. In order to keep a customer from signing on multiple times, DR allows the customer sign-on information to be propagated through a remote user management api. This guide intends to give the client an overview of the steps involved in the integration process. The details of the api have been intentionally left out, and may be found online in the Digital River Integration Service Guide ( When browsing the Integration Service Guide please refer to the Remote User Management (SSO) section found at: Integration Processes User Account. When planning a Single Sign-On integration with Digital River, it is important to keep the following pieces of information in mind: The client maintains the master record for user information The client must maintain a unique, immutable id for each master user record Digital River acts as a secondary and updates user information from the master as needed Digital River can create new users, but will send the user s information to the client for validation In order to optimize the single sign-on process for the highest close ratios possible, Digital River will allow unauthenticated customers to browse and add items to the cart at any time Updates to user information through the My Account section will be redirected to a page hosted on a client site. This can be a pop-up page or a direct link with a return url Forgot Password links point to the client s site (typically this is a pop-up window) Order and Subscription Management and Billing Options will occur on the Digital River hosted site 3

4 Terms, Shapes, and Definitions DR Client Customer/Shopper gc ISG Digital River Partner/Customer of Digital River Individual Shopper Global Commerce Digital River s ecommerce Technology Platform Digital River s Integration Service Guide Digital River Controlled System Client Controlled System Customer/Shopper Message Request or Message Response from Digital River Message Request or Message Response from the Client 4

5 Typical High Level Work Flows Customer Authenticates on Client s Site Figure 1 depicts the combined use of Remote Session Validation and Remote User Fetch which occurs when a customer first arrives at Digital River from a client s site. Details for each of these integrations may be found later in this document (Remote Session Validation and Remote User Fetch). Figure 1 The following steps walk through what typically happens when an unauthenticated customer visits and logs in. The authenticated customer then visits Digital River and is authenticated through SSO. 1. Unauthenticated customer visits 2. Unauthenticated customer attempts to login 3. Client s system authenticates customer credentials 4. Client s system establishes unique session token and writes value to predetermined cookie under domain.clientsite.com 5. Client stores unique session token and its association to the customer s unique user id 6. Authenticated customer clicks on a shopping link which points to shop.clientsite.com 7. Digital River looks for and reads predetermined cookie under domain.clientsite.com 8. Digital River sends ValidateSessionRequest to client s end point with the contents of the predetermined cookie 9. The client receives the message, validates token, and returns ValidateSessionResponse with a UserKey element consisting of the externalreferenceid (the unique, immutable, master user id for the customer associated with the session token) 10. Digital River receives message and looks up externalreferenceid. If there already is a Digital River user id associated with the externalreferenceid, Digital River will use that user record. If not, Digital River will create a new user and associate it with the externalreferenceid 11. Digital River immediately sends GetUserProfileRequest to the client s endpoint to pull the latest information about the customer 5

6 12. The client responds with GetUserProfileResponse 13. Digital River s record of the user is updated with current information 14. Authenticated Digital River customer shops and purchases many, many items 6

7 Customer Authenticates on Digital River Hosted Shopping Site Figure 2 represents either of two processes whereby a customer can authenticate on the Digital River hosted shopping site. Details for each of these integrations may be found later in this document (Remote Login and Remote Create User). Figure 2 The following steps walk through what typically happens when an unauthenticated customer visits shop.clientsite.com (hosted by Digital River) and logs in or purchases and is forced to create an account. This customer would be unauthenticated at the client site as well. Once the customer finishes the shopping experience he may navigate to 1. Unauthenticated customer browses shop.clientsite.com and attempts to: a. Login Digital River sends LoginRequest with loginid ( address), and password. Client validates login, creates unique session token and associates it with the customer id, and returns LoginResponse containing the externalreferenceid to Digital River b. Checkout Digital River gathers customer information and sends CreateUserProfileRequest with loginid ( address), password, and customer information to client. Client validates and creates user, creates unique session token and associates it with the customer id, and returns CreateUserProfileResponse containing the externalreferenceid 2. In both cases Digital River receives the message and updates the Digital River customer information 3. Digital River creates predetermined cookie under domain.clientsite.com and fills with the sessiontoken received in either message 4. Authenticated Digital River customer purchases many, many items and concludes shopping experience. Customer may navigate to 5. Client looks for and reads predetermined cookie under domain.clientsite.com and determines customer user id based on previous association 6. Client proceeds as required 7

8 Elements of Single Sign-On Integrations Remote Session Validation An important element of a seamless single sign-on process is validating a remotely authenticated user. DR initiates this process by searching the http header for a predetermined cookie. This cookie is a remote session token which will allow DR to contact the client and validate the user. Once DR has validated the token and received a corresponding authenticated user id from the client, it instantiates an authenticated user session. Figure 3 Success Checklist Client establishes infrastructure to create and validate unique authenticated user session token Client determines session token cookie name Client creates process to ensure cookie is present when the customer browses to the Digital River hosted site Digital River adds process to look for client session token and generate and post ValidateSessionRequest Client creates test and production Http endpoints to service the ValidateSessionRequest message Client creates process to respond to ValidateSessionRequest with ValidateSessionResponse which contains user key 8

9 Digital River adds process to receive ValidateSessionResponse and establish authenticated user session Digital River adds process to find user key in its user management system or, if not found, creates new user Digital River and Client agree on validation error codes and their meaning Digital River and Client agree on any extended attributes present in the request/response and their meaning 9

10 Remote User Fetch To ensure that current customer information is present during the Digital River shopping experience, DR will request customer information from the client. This request occurs once an authenticated user session has been established and will be used to update DR s profile of the customer. Figure 4 Success Checklist Client establishes infrastructure to validate unique authenticated user session token Digital River adds process to generate and post GetUserProfileRequest Client creates test and production Http endpoints to service the GetUserProfileRequest message Client creates process to respond to GetUserProfileRequest with GetUserProfileResponse Digital River adds process to receive GetUserProfileResponse and update user information Digital River and Client agree on fetch error codes and their meaning Digital River and Client agree on any extended attributes present in the request/response and their meaning 10

11 Remote Login To enable a customer to begin their shopping experience at the Digital River storefront, DR offers a remote login API. Typically an unauthenticated customer visits the storefront and at some point in the shopping process requests to login. At that point, Digital River will validate the customer with the client. Figure 5 Success Checklist Digital River adds process to generate and post LoginRequest Client creates test and production Http endpoints to service the LoginRequest message Client establishes infrastructure to generate unique authenticated user session token Client creates process to respond to LoginRequest with LoginResponse Digital River adds process to receive LoginResponse and, if successful, establishes authenticated user session. If not successful, show error to user Digital River adds process to find user key in its user management system or, if not found, creates new user Digital River and Client agree on login error codes and their meaning Digital River and Client agree on any extended attributes present in the request/response and their meaning Digital River creates Forgot Password link which redirects customer to the client s Forgot Password page Client creates Forgot Password page and corresponding process 11

12 Remote Create User In the case where a customer never logs in and creates a new account during the checkout process, Digital River will forward information about that customer to the client and then create a local user for that customer as well. Figure 6 Success Checklist Digital River adds process to generate and post CreateUserProfileRequest Client creates test and production Http endpoints to service the CreateUserProfileRequest message Client establishes infrastructure to generate unique authenticated user session token Client creates process to respond to CreateUserProfileRequest with CreateUserProfileResponse Digital River adds process to receive CreateUserProfileResponse and, if successful, establishes authenticated user session. If not successful, show error to user Digital River adds process to create new user Digital River and Client agree on creation error codes and their meaning Digital River and Client agree on any extended attributes present in the request/response and their meaning 12

13 User Key Flow The User Key is an important element contained in each Request message and most Response messages. This key allows Digital River to uniquely identify each customer. However, from a schema perspective, the key is made up of several optional elements. The following list captures the ways the Global Commerce platform establishes uniqueness: Digital River User Id - Unique Id Assigned to the Customer in Global Commerce Customer Login Id and Client s Site Id As a customer may use the same login with many of Digital River s clients, the client s site id ensures the login id is unique Client s User Id and Client s Site Id The client must maintain a unique, immutable id for each master user record. That Id coupled with the client s site Id ensures uniqueness Client s User Id and Client s Company Id Much like the previous, this combination allows the use of the client company id instead of the site id In the case of the Single Sign-On Integrations, the required User Key elements are predetermined and not optional. Please use the following chart to better understand the requirements for the User Key in each Single Sign-On Message: Message ValidateSessionRequest ValidateSessionResponse Required UserKey Elements None externalreferenceid, loginid Notes Since the client system has already authenticated the customer, return the immutable, client id plus loginid GetUserProfileRequest externalreferenceid Please use the externalreferenceid to identify the customer in your system GetUserProfileResponse externalreferenceid, loginid LoginRequest loginid Password will also be sent as another element in the message LoginResponse externalreferenceid CreateUserProfileRequest loginid Password will also be sent as another element in the message CreateUserProfileResponse externalreferenceid 13