The customer will implement server-side SSO with Cheetah. This is necessary in order to supply the SSO credentials mentioned in the web page hosted by the customer.
Overview
- A user visits the customer website, and either signs up or logs in.
- The customer web server implements SSO (see below) and emits a stellar_member_state javascript variable in the next web page.
- The Cheetah JS SDK reads stellar_member_state and authenticates the member.
How SSO Works
The Integration ID is the customer.com user ID. The first time an SSO API call is made for a member, Cheetah creates the member and stores the Integration ID; this enables the member to be looked up by Integration ID. During the first SSO call the user first name, last name, and email address are also stored on the member.
On subsequent SSO API calls, Cheetah looks up the member by Integration ID. Member fields such as first name, last name, and email address are also updated on subsequent SSO API calls.
The SSO API has options for whether to use Integration ID, Email, or both when matching a member.
Calling the SSO API ensures that there is a corresponding member in Cheetah. This is important in many integrations where the customer web server needs to count on the existence of a member in Cheetah.
How to Implement SSO
The customer web server needs to connect to the Cheetah API to initialize the member, obtain the member access token, and then put it in the page as a javascript variable. Please see below for Acquiring Integration Access Token and Initializing Member by access_token or client_id and client_secret.
- Find or initialize a member using /console/api/sso API endpoint
-
This call must be made via the Integration Oauth App credentials
- Tip: The Client ID and Secret Key for the Integration Oauth App can be found in the Cheetah admin console under Program > Oauth Apps. Look for the item named “integration” and use the Client ID and Secret Key on that page.
- The integration_id parameters is the unique ID of the member in the customer’s database, possibly called the “user id”. This is typically a number, username, or an email address. Cheetah stores this id on the member record.
- The API response contains the Cheetah member id and member access token.
-
-
Emit member access token in the web page in the stellar_member_state javascript variable. The format must match the code snippet below in order for the Cheetah JS SDK to find and use the member access token.
-
Ideally the member access token should be cached in a user session, if possible
- If there is an error encountered during SSO, then the stellar_member_state.sso_error attribute must be set to a non-empty string to indicate an error has occured. This allows the JS SDK to properly handle this condition.
var stellar_member_state = {
access_token: "0fad7f6fd5571813956a8e51c0a71730d54051ccce3aa",
refresh_token: "884efd7a551a964103856b62586a4c22f618ccfe2811",
sso_error: "", // non-empty value indicates an error
short_name: "Susan",
full_name: "Susan Sample"
}
Note: If customer is stripping out the deeplink params appended to querystring during signin, stl_params_hash inside stellar_member_state can be added so we can preserved the deeplinks e.g. stellar_member_state[stl_params_hash] = <encrypted_value>
Acquire Integration Access Token
Login to Cheetah Marketing Console and go to Program > Oauth Applications. Get the client_id and client_secret of the ‘integration’ app. Then use those credentials to get integration access token. To sign-in via command line, invoke the following cURL command:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F 'grant_type=client_credentials'
-F 'client_id=<client_id>'
-F 'client_secret=<client_secret>'
<base url>/oauth/token
If successful, the response should look like below. The access_token here is your integration_access_token
{
"access_token": "40e4726e5263ce266058c04494d4385f36530d233ef0bc363e92b2c969ff57a9",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "5d0c438a28d62466ef70154bf15a6cc185e0e884b06d76fbf176ff86a55860c5",
"created_at": 1444027150
}
User client_credentials as grant_type value when requesting integration access token.
Find or Initialize a Member either by access_token or client_id and client_secret
To find or initialize a member via SSO using access_token, invoke the following cURL command:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F 'access_token=<integration_access_token>'
-F 'integration_id=<integration_id>'
-F 'first_name=<first_name>'
-F 'last_name=<last_name>'
-F 'email=<email>'
<base_url>/program/api/sso
To find or initialize a member via SSO using client_id and client_secret, invoke the following cURL command:
curl -X POST
-H 'Accept: application/vnd.stellar-v1+json'
-F 'client_id=<integration.client_id>'
-F 'client_secret=<integration.client_secret>'
-F 'integration_id=<integration.integration_id>'
-F 'first_name=<first_name>'
-F 'last_name=<last_name>'
-F 'email=<email>'
<base_url>/program/api/sso
NOTE TO Developers:
integration_access_token is different from access_token. See Aquire Integration Access Token. If successful, response should look like below. This access_token can now be used on Member APIs, i.e. Member Profile.
{
"member_id": "A-000000001",
"integration_id": "34567893039",
"access_token": "5d0c438a28d62466ef70154bf15a6cc185e0e884b06d76fbf176ff86a55860c5",
"refresh_token": "40e4726e5263ce266058c04494d4385f36530d233ef0bc363e92b2c969ff57a9"
}
This endpoint works either by using access_token or client_id and client_secret pair. Make sure to use the same client_id and client_secret from Acquire Integration Access Token.