Leverage the Mobile Device Extension for ad rms

Prerequisites for the Mobile Device Extension

The Mobile Device Extension supports the following RMS clients:

• 
  Android phones and tablets. Minimum version of Android 4.0.3
  
• 
  iPhone and iPad. Minimum version of iOS 7.0
  
• 
  Mac OS X. Versions 10.8 and 10.9
  
• 
  Windows Phone. Minimum version of Windows Phone 8.1
  
• 
  Windows RT tablets. Windows 8 RT, Windows 8.1 RT
  

Note The availability of the RMS client and SDK on an operating system does not necessarily imply the availability of the RMS Sharing app on that platform. In particular, the RMS Sharing app has not yet been released for Windows RT devices at the time of this writing.

These clients must use the latest version of the RMS sharing app for the devices as available for download at the Microsoft Rights Management page¹⁷.

Beyond an existing on-premises AD RMS deployment on Windows Server 2012 or Windows Server 2012 R2, the following dependencies must be in place before using the Mobile Device Extension for AD RMS:

• 
  DNS SRV records to help locate the service endpoints provided by the Mobile Device Extension.
  
• 
  Both AD RMS internal (e.g., intranet) and external (e.g., extranet) FQDN URLs populated. (In a split brain DNS configuration, only the Intranet URLs are populated.)
  
• 
  Use of SSL/TLS with a trusted X.509 certificate for the AD RMS internal and external URLs.
  
• 
  AD FS deployed on Windows Server 2012 R2 to sustain the authentication required by the service endpoints.
  

Note For information on AD FS in Windows Server 2012 R2, see the Microsoft TechNet article Windows Server 2012 R2 AD FS Deployment Guide¹⁸.

• 
  Some secure publishing mechanism such as the Web Application Proxy (WAP) deployed on Windows Server 2012 R2 to publish the service endpoints on the Internet.
  
• 
  If the AD RMS server is deployed behind a firewall or published by using a reverse proxy, in addition to publishing the service endpoints on the Internet, you must also publish the /my folder, for example https://adrms.litware369.com/my.
  

The next sections provide additional information on the service endpoints and depict how the above dependencies are being used by the Mobile Device Extension for AD RMS.

How mobile apps use the new service endpoints

Note This section discusses how the Mobile Device Extension works under the hood to support mobile apps based on the RMS SDK 4.x. This section is included here for a deeper understanding of the technology, but this level of knowledge is not essential to be able to deploy the AD RMS Mobile Device Extension. If you are not interested in the details of how this technology works, you can skip directly to the section Building an evaluation environment below.

The Mobile Device Extension exposes the following endpoints in the form of REST APIs:

In addition to the above REST service endpoints, the Mobile Device Extension provides a DNS-based service discovery mechanism in order to enable mobile devices to discover these endpoints based on the identity of the user or the source of the protected content. This will be further discussed below.

Publishing License request

When a mobile client has to protect content it calls the service to obtain the Publishing License to use for the document. This differs from Windows clients, where protection can be performed offline by the client by using keys contained in the Client Licensor certificate and other artifacts obtained during activation. In mobile devices such activation process does not exist, and all calls performed to the service are handled independently.

The Publishing License request takes either a template ID or a custom policy and returns a serialized Publishing License (PL) that is generated from the template or policy.

HTTP Method		Request URL	HTTP Version
POST	https://<ClusterURL>/my/v1/publishinglicenses		HTTP 1.1

Where <ClusterURL> is the FQDN of an AD RMS cluster on top of which the Mobile Device Extension has been installed. This value will be obtained by calling the service discovery so that mobile devices can discover the endpoints based on the identity of the user.

The request body includes a JSON-encoded template ID that corresponds to one of the templates that are configured for the tenant or custom (ad-hoc) policy. A successful request returns HTTP 200 OK with a body that contains the Publishing License (in base64 encoded form) in a JSON object.

End User License request

The End User License request takes the publishing license of the protected content as a parameter and returns the end user license (EUL) for the calling user.

HTTP Method		Request URL	HTTP Version
POST	https://<ClusterURL>/my/v1/enduserlicenses		HTTP 1.1

Where <ClusterURL> is the FQDN of an AD RMS cluster on top of which the Mobile Device Extension has been installed. This value will be obtained by calling the service discovery so that mobile devices can discover the endpoints based on the identity of the user and the URL of the server that was used to protect the content.

The request body is a JSON object that contains the serialized publishing license (PL) (in base64 encoded form) that applies to the protected content. A successful request returns HTTP 200 OK with a body that contains the end user license (EUL).

Templates request

The Templates request returns the list of templates that are available for the user in the server.

HTTP Method		Request URL	HTTP Version
GET	https://<ClusterURL>/my/v1/templates		HTTP 1.1

Where <ClusterURL> is the FQDN of an AD RMS cluster on top of which the Mobile Device Extension has been installed.

There is no body for this request. A successful request returns HTTP 200 OK with a body that contains the list of templates that are available.

REST API errors

This section describes the errors that can be returned by the aforementioned REST APIs and their format.

The following table shows the HTTP error codes that the REST APIs can return.

HTTP Error Code		Description
200 OK	Standard response for successful HTTP requests.
400 Bad Request	The request cannot be fulfilled because of bad syntax or set of parameters.
401 Unauthorized	Returned when authentication is required and has failed or has not yet been provided.
500 Internal Server Error	Returned when something happened on the server and the client is not at fault.

When the REST API explicitly returns HTTP 400 and 500 errors (but not HTTP 401 errors), it also returns a message body that contains information about the error. The response body contains the following fields:

• 
  code. The fully qualified name of the exception that caused the error.
  
• 
  message. A descriptive message that explains the error.