Loyalty Lab Guide to Single Sign On Integration

Last Updated: May 11, 2007 Version 2.00.7.2

Loyalty Lab, Inc. May, 2007. All contents proprietary and confidential. This document is for information only. No warranties or liability for information in this document are expressed or implied.

Table of Contents
Overview ...................................................................................................... 3 Secure Data Transfer .................................................................................. 3 Summary: How Single Sign On Works............................................................... 4 Single Sign On Process Flow Diagram................................................................ 5 Implementation Details................................................................................... 6 Appendix A: Return codes from SSO authentication ............................................ 7

Proprietary and Confidential

Page 2

5/11/2007

Overview
Loyalty Lab has created a complete solution that enables multi-channel retailers to attract and retain customers. Loyalty Lab helps you build customer loyalty by deploying a multi-channel retention marketing system that is highly effective, low cost and low-maintenance. Loyalty Lab's System as a Service (SaaS) approach has been designed to minimize integration and deployment effort. Loyalty Labs Single Sign On (SSO) feature provides shoppers with access to loyaltybuilding presentations and offers, such as your ecommerce sites and our seamlessly integrated loyalty sites, without requiring them to log in twice. To implement this feature, your development staff must provide some coding and work with Loyalty Lab's integration team to perform integration testing. The resulting Single Sign On technology provides you with a secure means of giving your shoppers convenient and secure access to loyalty program information. To use SSO, you must implement the following functions: When a shopper logs in, use a Loyalty Lab real time API call to obtain an Authentication Ticket for that shopper. When a shopper opts into the loyalty program, use a Loyalty Lab real time API to create a new shopper record, if one does not already exist. When a shopper clicks on a link to the loyalty program pages hosted by Loyalty Lab, retrieve the Authentication Ticket from the Loyalty Lab API Call and pass it with the URL as a query string. Provide a logout and error handling page. When shoppers need information other than their password, use the Loyalty Lab Real Time API to update the shopper information. The Loyalty Lab Real Time API can also be used to mark a shopper as Inactive.

Secure Data Transfer

Loyalty Lab is Visa CISP (Cardholder Information Security Program) compliant. This means that all data with sensitive information transferred between Loyalty Lab and the retailer must be transmitted using an encrypted protocol. Single Sign On uses 128-bit SSL for all connections and encrypts and encodes authentication tokens to ensure they are reasonably impervious to attack. This includes both the API call and the link to the shopper application.

Proprietary and Confidential

Page 3

5/11/2007

Summary: How Single Sign On Works

Loyalty Lab (LL) provides a secure mechanism to pass shopper credentials to the Loyalty Lab system and authenticate the shopper on the Loyalty Lab shopper-facing web site without requiring the shopper to perform a second login. Single Sign On must handle the following five basic scenarios: 1. Shopper opts into the loyalty program When your shopper is on your web site and agrees to join (opt in), you must create a shopper record in the Loyalty Lab database using the Real Time API that we provide. The interface provides for exception handling in the case where the shopper already has a record in the database. 2. Shopper requests access to his or her loyalty program information When the shopper clicks on a link on your site to review personal loyalty program information, your web site must retrieve the shoppers email address and pass it to the Loyalty Lab API. The Loyalty Lab API will respond with an Authentication ticket for that shopper, which is good for 30 minutes. Encode this ticket as a query string parameter named auth_t and add it to the URL of the Loyalty Lab hosted loyalty program pages. Loyalty Lab parses and decrypts the query string information, and then validates the authentication of the shopper before redirecting the shopper to the loyalty program information. 3. Shoppers credentials are not accepted When a shoppers credentials are not accepted by Loyalty Lab for any reason, Loyalty Lab will return an HTTP redirect response to a web page that you host. This response contains the error type so that you can provide appropriate messaging to your shopper about the problem, or take other programmatic action to resolve the problem (like retrieve a new public key to replace one that has been rotated). Error codes are documented in Appendix A: Return codes from SSO authentication. 4. Shopper logs out of the loyalty program pages When the shopper clicks the logout link on our site, we will return an HTTP redirect response to the same URL that you host with a return code of 2 on the querystring that implies that the shopper logged out of our system. Again, this is documented in Appendix A: Return codes from SSO authentication. 5. Shopper makes changes to their information When the shopper makes changes to the same information that we store about your shopper (email address, mailing address, etc.), you must use the Real Time API we provide to update the information in the Loyalty Lab database. It is particularly important to keep the shopper email up to date so that the shopper can always access their loyalty information.

Proprietary and Confidential

Page 4

5/11/2007

Single Sign On Process Flow Diagram

Customer creates account on Client.com Client sends request for the customer (email address) to access the loyalty program LL receives request No Match LL finds no match, sends response Client uses API to create new customer in LL

Match

LL finds a match, sends an authentication ticket

Client sends request for the customer (email address) to access the loyalty program

LL acknowledges customer creation

Client receives ticket in response

Client passes authentication request with ticket

Customer is passed on to LL hosted Loyalty Program

Proprietary and Confidential

Page 5

5/11/2007

Implementation Details
Loyalty Lab API Call This is a REST style call Basic authentication using your REST User is required. (Note: The REST User is created using Loyalty Lab's CRMS application.) This call must be done over SSL If the shopper is not found, then a HTTP 404 response code will be issued, and the HTTP Response Body will contain the XML described below. API Call Syntax HTTP Method: GET from https://api.instorecard.com/xml/shopper/authenticate/?ShopperEMail=<shopper email> Query String Parameters ShopperEMail: Email of the shopper to get the authentication ticket for. Sample Response
<ISCAuthentication xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.loyaltylab.com/schema/v2.1/RetailIntegration/"> <ShopperLoginToken>32-64-35-37-79-69-69-30-71-72-2F-57-66-4E-70-35-59-30-73-39-4D44-73-2F-70-70-67-6B-34-30-56-4F-35-46-72-56-61-58-50-53-55-48-73-3D</ShopperLoginToken> </ISCAuthentication>

Variations If a shopper with the supplied email address does not exist, the API call returns a HTTP 404 Not Found with the following response body:
<ISCError xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.loyaltylab.com/schema/v2.1/RetailIntegration/"> <ErrorCode>4040</ErrorCode> <Description>The supplied email address does not match a registered customer</Description> </ISCError>

Query String Login Parameters The value of the ShopperLoginToken should then be passed in as the auth_t parameter to the requested Loyalty Pages. Example /../..?auth_t=-64-35-37-79-69-69-30-71-72-2F-57-66-4E-70-35-59-30-73-39-4D-44-73-2F-70-70-67-6B-34-

30-56-4F-35-46-72-56-61-58-50-53-55-48-73-3D

Proprietary and Confidential

Page 6

5/11/2007

Appendix A: Return codes from SSO authentication

The SSO functions can fail to authenticate a shoppers credentials for several reasons. When that happens, the software directs the users browser to a URL that you code and host with an rc= query string parameter containing one of the following values: (-1) Decryption of Shopper Credentials failed (the most probable cause is it is an invalid ticket) (-4) Client GUID is missing from the query string and the cookies sent to the server (-5) Email address is invalid (-6) Shopper record was not found (-7) Shopper account is disabled (-8) Shopper account is deleted (-9) Authentication failed Ticket expired (1) Redirect to the signup page. The signup page was requested with a missing authentication cookie this implies that the shopper needs to be directed to the initial signup page on your site to complete the first couple of steps of signup and then be transferred to Loyalty Lab shopper pages using SSO. (2) Redirect to logout page. Shopper logged out of Loyalty Lab pages. (3) Redirect to Shopper Account page. Shopper chose to edit account preferences, which must be done on your site.

When the rc parameter is contains a negative value, the URL redirect will also contain a ru= query string parameter that will contain the URL that the shopper was trying to reach when the SSO process failed, so that you have an opportunity to correct the problem and retry the request.

Proprietary and Confidential

Page 7

5/11/2007