Scenario –  Client app talking to CRM cloud service which needs to authenticate the user behind the app. OAuth 2.0 will serve as the authentication protocol for this scenario.

The client app will acquire authentication token from Security Token Service (STS) which will be passed to the CRM Server as proof of authentication.

Actors and Terminology

Security Token Service (STS) – service issuing authentication tokens meant to be consumed by Server Applications based on some “proofs” presented by the requesting Client Application. OAuth 2.0 standard refers to it as Authorization Server, but semantics is the same. OAuth2.0 authorization service http://tools.ietf.org/html/draft-ietf-oauth-v2-28 exposes 2 endpoints:

Authorization Endpoint  – Performs user authentication and consent in browser context

Token Endpoint – Token issuance endpoint. Optionally authenticates client application

Client– Application requesting authorization token on user behalf

Client ID – an identifier unique within STS realm representing the Client App

Resource Server (CRM Server ) – Application consuming authentication token

Resource Server Protocol – protocol between client and server app. The protocol must provide provision for transporting authentication token. Apps discussed in this doc use HTTP as transport and HTTP headers to carry protocol authentication payload.

Bearer Token – Token than can be used without additional proof. Tokens discussed in this document are of this type

Authentication Process

The authentication process involves client app acquiring token from the STS and sending it to CRM Server over SSL. Authentication tokens are carried to the CRM Server in well-defined transport protocol element. Mechanism is described in OAuth bearer token specification: http://self-issued.info/docs/draft-ietf-oauth-v2-bearer.html

As described in the document above, authentication token is carried in Authorization HTTP header:

GET /tenant/app HTTP/1.1 Host: serviceapp.com Authorization: Bearer b64token

The CRM Server will crack open the token, check for integrity, verify signing identity and authorize the identities carried in the token against the resource authorization policy. The security token sent over authenticates the user and optionally the client app to the CRM Server.

If the client request does not carry authentication token or token validation fails, the server MUST respond with authentication challenge as described in bearer doc:

HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer redirect_uri=<URI>, Params=<string>

Where redirect_uri is a string identifying one of the STS instances the client application trusts. For the CRM Server discussed in this section an example challenge can be:

HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer redirect_uri=https://STSInstance1

Client App

The flow starts with the client initiating connection to the CRM Server. In the absence of previous communication and cached data the client does HTTP GET request without providing Authorization data. Response contains challenge as described earlier:

HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer authorization_uri=URI, Params=string

Next client goes thru the following steps:

1. Validate authorization_uri and, if needed, transform it to authorization endpoint URL.
2. Initiate Authorize request in browser control
3. If successful, receive Authorize Code and exchange it for Refresh and Access Tokens
4. Store refresh token for future use and use Access Token to communicate to server app

Step b – Initiate Authorize request in Browser control

Different computing platforms will offer different means to accomplish the above. Windows 8 provides Metro apps Web Authentication broker API that takes Authorize URL and redirect_uri as parameters:

http://msdn.microsoft.com/en-us/library/windows/apps/hh750287.aspx

Step c – Authorization Code Response

Following successful authentication and consent experience Authorization endpoint redirects browser agent to the redirect_uri with authorization code on the query string. The client app intercepts redirect and extracts the authorization code from the query string.

For example redirect will look like this:

HTTP/1.1 302 Found Location: https://clientid/?code=<authorization code>

Authorization code is string that can fit on most browsers query string. This specification requires that authorization code is no longer than 1024 UTF8 characters.

Step d – Obtain Refresh and Access Tokens

Given authorization code, client app interacts with Authorization’s server Token Endpoint to obtain refresh and access token.

Parameters:

grant_type – “authorization_code”

code – code obtained in previous step

redirect_uri – redirect uri specified in previous step

client_id – client id specified in previous step.

Since client is not capable to keep secret, authenticating the client ID is not possible. However, the platform can use additional mechanisms such as device identifiers to authenticate the client. This specification does not prescribe additional steps for applications redeeming authorization codes for access and refresh tokens.

Successful response as described in OAuth spec returns access and refresh tokens to the client in the body of 200 HTTP response in application/json media type:

{
“access_token”:b64token,
“token_type”:”bearer”,
“expires_in”:3600,
“refresh_token”:b64token
}

Using Refresh Token

Refresh token obtained as described in previous section can be used to obtain additional access tokens. The request format is as described in OAuth20 RFC.

Communication to CRM Server

Access token is used to authenticate client to CRM Server. Token is passed in Authorization header as shown earlier:

GET /tenant/app HTTP/1.1 Host: serviceapp.com Authorization: Bearer b64token

Hope this helps.

Normal
0

false
false
false

EN-US
X-NONE
HE