Oauth 2.0 Implementation for Stores Redemption

Oauth 2.0 Implementation for stores/redemption: Xoxoday Client

Xoxoday implemented standard Oauth 2.0 protocol for its clients to access relevant resources. PFB.

Let’s go through the steps of implementing the Oauth Client side.

STEP 1 - Client Registration

First, you need to register your app as a client on the Xoxoday side. For registration, you have to give your redirect_uri and scope which is required for the app with the explanation.

After approval Client will be given with client_id and client_secret.

(As of now these details are to be shared over an email to our Xoxoday Support Team. After registration client_id and client_secret are shared with the client by Xoxoday Support Team)

Xoxoday supports the following scopes for Such Clients.

Company Scopes

• user_session (Used only for the case of Company access_token generation)

PLEASE NOTE

OAUTH_URL value for

Development - https://stagingaccount.xoxoday.com/chef

Production - https://accounts.xoxoday.com/chef

STEP 2 - Authorization Request

This is the first request in Oauth process when client requests for authorization code by redirecting to following url {OAUTH_URL}/v1/oauth/authorize?client_id=07d60911ce2a37239becf5d90811324a&response_type=code&redirect_uri={client_redirect_url}&scope={requested_scopes}&state={client_state}

client_id* (required) - This is the client_id value which you got after registration.

response_type* (required) - Although Oauth supports different response_type values. The only value supported by Xoxoday is code

redirect_uri* (required) - The URL domain must match to URL which you have shared in the registration STEP 1.

scope* (required) - The scope values must be the values mentioned in STEP 1. If there are multiple scopes send them separated by commas. For eg. profile_read,points_read,feed_manage. If the authorization request is for company session generation then user_session scope is compulsory.

state (optional, Recommended) - As per OAuth protocol, this value is optional. This value is generated by the client. When the authorization request is completed the same value is passed to the client in the redirected URL so that client can verify the request.

If all the above parameters are validated successfully and the user is already authenticated, then the user is redirected to the following authorization consent page.

If the user is not authenticated, then the user will be redirected to the following login/signup page

After authentication, the user will again be redirected to the authorization consent(allow/deny) page.

If the user is denied access, then the browser will be redirected to the following URL

{client_redirect_url}?error=access_denied&error_description=The+user+denied+the+request&state={client_state}

If the user allowed the request then the browser will be redirected to the following URL

{client_redirect_url}?code=exxxx69660xxxxa6413c17d897xxxxx99&state={client_state}

In the above-redirected URL, code is a temporary token created on account of client allowed access which is valid for 5 min duration. Later this code is exchanged for access_token which is used for accessing Xoxoday resources granted based on the scopes allowed by the user.

STEP 3 - Token Exchange

In this step as per Oauth protocol the code received by the client in STEP 2, will be exchanged to get the access_token which is used for accessing Xoxoday resources granted based on the scopes allowed by the user.

The client-server (As this request involves sensitive information i.e, client_secret) must make the following POST request to get the access_token

curl -X POST {OAUTH_URL}/v1/oauth/token/{token_type}
-d '{
 "grant_type":"authorization_code",
 "code":"exxxx69660xxxxa6413c17d897xxxxx99",
 "redirect_uri":"{client_redirect_url}",
 "client_id":"{client_id}",
 "client_secret":"{client_secret}"
}'

Let's discuss the variables which are involved in the above request

token_type* (required) - token_type can be two values. They can either be a company or a user. If the Authorization request in STEP 2 was for the company session creation then the token_type value is the company or if the Authorization request in STEP 2 was for user session creation then token_type value is the user.

grant_type* (required) - Although Oauth supports different grant_type values. The values supported by Xoxoday is authorization_code, refresh_token

code* (required) - This is the temporary code value that client has obtained after STEP 2.

redirect_uri* (required) - The URL must match to url which you have shared in the registration STEP 2.

client_id* (required) - This is the client_id value that you got after registration in the STEP 1.

client_secret* (required) - This is the client_secret value that you got after registration in STEP 1.

After validation of these parameters by the Xoxoday server the successful response will be

{
    "access_token": "eyJ0b2tlbkNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1NTAxMzYsImV4cGlyZXNBdCI6IjIwMTktMDctMDZUMDc6MDI6MzAuMTM2WiIsInRva2VuX3R5cGUiOiJDT01QQU5ZIn0sImFfdCI6ImY3ZWM1MWMyYmE0ZGNmNzY2ZWE0ZDExMTI3ZjEzZjQzZjAwZmNhN2EifQ==",
    "token_type": "bearer",
    "expires_in": 2592000,
    "refresh_token": "064be187f42e9238122ef9d7a985c8800dff3752",
    "email":"
[e-mail]
" //This is the email of the user who allowed access
}

In the above response

access_token is the bearer token that can be used by the client to access the API of Xoxoday.

token_type is the bearer which must be passed in the Authorization header.

expires_in is the duration (in seconds) for which access_token is valid. The default user session lasts for 15 days. The default company session lasts for 30 days.

refresh_token is the value with which the client can regenerate expired access_token. This refresh token for the user session lasts for 30 days and the refresh token for company session lasts for 60 days.

Diagram for STEP 2 and STEP 3

Redirection to Xoxoday Stores Page

The client has to generate a temporary token for SSO and redirect the user to Xoxoday with this temporary token. Let’s discuss the steps. There are two methods for this.

ssoToken from Company Session

Make the following request with the Company Bearer Authorization access token and get the temporary SSO token. In this, the user is registered automatically if not already registered.

curl -X POST {OAUTH_URL}/v1/oauth/sso/stores/company
-H 'Authorization: Bearer eyJ0b2tlbkNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk5MTk4ODE2MDEsImV4cGlyZXNBdCI6IjIwMTktMDYtMjJUMTU6MDQ6NDEuNjAxWiIsInRva2VuX3R5cGUi'
-d '{
  "user_input": "[e-mail]",
  "tpd":{//this is third party session data to be sent by the client (eg. Darwin) with which xoxoday calls api for fetching and redeeming points.This is still under development. 
   "auth_header":"Bearer asdgfjhbsdlkjbasdlkjbadslkbdakasdhfjhfdb==",
   "employee_id":"4356XC90",
   "Uid":"TTEO32S99ERCL"
  }
}
'

The response for the above request will be of the following format

{
    "data": {
        "ssoToken": "0d793dc64230b71376308aacf582e7f835ff01b3"
    }
}

After this, the user must be redirected to the Xoxoday to the following URL with the ssoToken value obtained in the above response.

{OAUTH_URL}/v1/oauth/redirect/stores/{ssoToken}

Access Token generation from Refresh Token

curl -X POST {OAUTH_URL}/v1/oauth/token/{token_type}
  -d '{
  "grant_type":"refresh_token",
  "refresh_token":"064be187f42e9238122ef9d7a985c8800dff3752",
  "client_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

Let's discuss the variables which are involved in the above request

token_type* (required) - token_type can be two values. They are either the company or the user. If the Authorization request in STEP 2 was for the company session creation, then token_type value is the company, or if the Authorization request in STEP 2 was for the user session creation, then token_type value is the user.

grant_type* (required) - refresh_token. The value refresh_token must be sent because of the action by the client for refreshing the token.

code* (required) - This is the temporary code value that the client has obtained after STEP 2.

redirect_uri* (required) - The URL must match to URL which you have shared in the registration STEP 2.

client_id* (required) - This is the client_id value that you got after registration in STEP 1.

client_secret* (required) - This is the client_secret value that you got after registration in STEP 1.

The response for the above request will be of the same format of STEP 3 or STEP 4

{
    "access_token": "eysdkhsdbjbdfsNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1NTAxMzYsImV4cGlyZXNBdCI6IjIwMTktMDctMDZUMDc6MDI6MzAuMTM2WiIsInRva2VuX3R5cGUiOiJDT01QQU5ZIn0sImFfdCI6ImY3ZWM1MWMyYmE0ZGNmNzY2ZWE0ZDExMTI3ZjEzZjQzZjAwZmNhsdjhfbsfdjblfs",
    "token_type": "bearer",
    "expires_in": 2592000,
    "refresh_token": "sdff064be187f42e9238122ef9d7a985c8800dff3752"
}

Note In the above response refresh_token is newly generated again. So the client server must replace the old refresh token with this new refresh token.

Step 6 Diagram

Access Token Validation

For verifying at any point in the app if the token is valid/not, call below endpoint

curl -X GET {OAUTH_URL}/v1/oauth/token
-H 'Authorization: Bearer 
eyJ0b2tlbkNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1Nzg1ODIsImV4cGlyZXNBdCI6IjIwMTktMDYtMjFUMDc6MDI6NTguNTgyWiIsInRva2VuX3R5cGUiOiJ'

Here you pass the bearer token (user/company) in header. The response of the request will be following in the case of success:

{
    "access_token": "eyJ0b2tlbkNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1Nzg1ODIsImV4cGlyZXNBdCI6IjIwMTktMDYtMjFUMDc6MDI6NTguNTgyWiIsInRva2VuX3R5cGUiOiJ",
    "token_type": "bearer",
    "expires_in": 1291911023
}

In case of token expiry

{
    "error": "invalid_token",
    "error_description": "invalid/expired token"
}