Leverage the Mobile Device Extension for ad rms

Understanding how authentication works with the service endpoints

As discussed above, the Mobile Device Extension for AD RMS enables to expose rights management service endpoints on top of the RMS service for consumption of protected content and for authoring of new content. Most mobile devices do not support the NTLM or Kerberos protocols for authentication and thus need to use a different mechanism to authenticate to the different interfaces in the RMS server, including connecting to the service discovery endpoint.

For that purpose, the Mobile Device Extension for AD RMS leverages the OAuth 2.0²¹ open standard protocol for authentication and authorization.

The above step 3 more specifically uses the OAuth 2.0 authorization code grant flow: a public client (e.g. the RMS-enlightened app) receives consent (in the form of an authorization code) from a resource owner (e.g. the user) to access a protected resource (e.g. the RMS service) on their behalf. The client then redeems the authorization code for an access token and a refresh token, to access the protected resource.

ADFS in Windows Server 2012 R2 exposes the following two endpoints in order to sustain the above OAuth 2.0 grant flow:

1. 
   Authorization endpoint: https://<ServerURL>/adfs/oauth2/authorize
   

The authorization endpoint is used to interact with the RMS client and obtain an authorization code which will be issued to the app. AD FS authenticates the user before granting the authorization code. This authorization code will be exchanged by the app for an access token.

2. 
   Token endpoint: https://<ServerURL>/adfs/oauth2/token
   

The token endpoint is used by the app to obtain an access token by presenting its authorization code.

Where <ServerURL> is the FQDN of the ADFS server/farm specified during the installation of the Mobile Device Extension for AD RMS.

The overall flow to obtain an access token is as follows:

1. 
   The RMS client makes a call to a service endpoint to perform an operation on the RMS service by making a call to the URL obtained thanks to one of the created DNS SRV records.
   
2. 
   The RMS service finds out that the authentication has not happened yet. It returns back an OAuth 2.0 challenge. More specifically, it returns back a HTTP 401 with two fields in the HTTP body. One is the resource name that identifies the service endpoint, and the other is the URL to the local AD FS server/farm to interact with to obtain an access token. This URL is set during the installation of the Mobile Device Extension for AD RMS.
   
3. 
   The RMS client takes this response and goes to the URL identified in the response from the RMS service.
   
   1. 
      In accordance to the OAuth 2.0 authorization code grant flow, it makes an authorization request to AD FS for the resource (again in the response from the RMS service) to get an authorization code. This call comprises the service endpoint the app wants to access, an app client identifier, and an app redirection URI in accordance with RFC 6749.
      

Note In order to allow access from OAuth 2.0 clients to REST resources secured by AD FS, the app has to be registered beforehand with AD FS by using the cmdlet Add-AdfsClient²². AD FS will not allow access to a REST resource to clients that specify a client identifier or redirection URI that is not registered with AD FS. For additional information, see Microsoft MDSN article Developing Modern Applications using OAuth and Active Directory Federation Services²³. 

1. 
   AD FS authenticates the user and issues an authorization code.
   
2. 
   The app gets the authorization code, and then does a post to the AD FS token endpoint to get an access token, passing the app client identifier, the redirection URI (this just has to match up with what was sent previously and isn’t used as a redirect), and the authorization code received in the previous step. 
   
1. 
   AD FS issues an access token for the user.
   
2. 
   The RMS client gets the access token and makes the request again but this time with the access token it got from AD FS. The RMS service validates the access token and if authorized responds to the request appropriately.
   

The follow diagram synthetizes the OAuth 2.0 authorization code grant flow in the above step 3:



Note The Active Directory Authentication Library (ADAL) library offers a simple programming model in client applications for AD FS in Windows Server 2012 R2 and for Azure Active Directory (AAD). Its main purpose is to help developers easily obtain access tokens from AD FS in Windows Server 2012 R2 or from AAD, which can then be used for requesting access to protected resources like the Mobile Device Extension for AD RMS REST APIs in the context of this document.

ADAL provides supports in mobile devices (Android²⁴, iOS²⁵, Windows Phone, and Windows RT), and Mac OS X²⁶. ADAL is available as Open Source code on GitHub so that you can participate in the development process. A full suite of sample applications and documentation is provided on GitHub²⁷ to help you get started. This includes tutorials for the above mobile devices and full walkthroughs for authentication flows such as OAuth2 in the context of this paper.

The RMS service expects that ADFS provides the following claims in the access token:

• 
  Primary email address of the user,
  
• 
  User principal name (UPN) of the user,
  
• 
  Proxy email addresses of the user if present.
  

The format used for the access token is JSON Web Token (JWT)²⁸, a compact JSON-encoded security token bearing claims. As such, JWT is especially apt for REST-based development. JWT use is growing, and products supporting the format are increasingly common in the industry.