The Microsoft Dynamics CRM Team Blog
News and views from the Microsoft Dynamics CRM Team
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.
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
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.1Host: serviceapp.comAuthorization: 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 UnauthorizedWWW-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 UnauthorizedWWW-Authenticate: Bearer redirect_uri=https://STSInstance1
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 UnauthorizedWWW-Authenticate: Bearer authorization_uri=URI, Params=string
Next client goes thru the following steps:
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:
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 FoundLocation: 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.
Given authorization code, client app interacts with Authorization’s server Token Endpoint to obtain refresh and access token.
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:
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.
Access token is used to authenticate client to CRM Server. Token is passed in Authorization header as shown earlier:
Hope this helps. Mahesh HariharanMicrosoft Dynamics CRM