Leverage the Mobile Device Extension for ad rms

Understanding how the service endpoints are located

Unlike with the cloud RMS service (Azure RMS) there is no universal location a client must go to deal with an AD RMS server deployed on-premises, so a service discovery mechanism is required. Windows clients can use the Service Connection Point (SCP) in Active Directory or, alternatively, registry-based overrides, to locate the RMS server in their environment. Mobile devices typically do not support being members of an Active Directory domain, nor can support registry-based configurations, so a different mechanism is used.

As mentioned before, the Mobile Device Extension provides a service discovery mechanism based on DNS SRV records in order to enable mobile devices to locate the necessary service endpoints. Such mechanism works in two steps:

1. 
   The RMS client performs a DNS lookup for a SRV record corresponding to the user’s email domain (for authoring or template acquisition operations) or the content source server’s FDQN (for consumption operations), and processes the response from the DNS service to build the service discovery URL to call.
   
2. 
   The client then contacts the URL obtained in the previous step and obtains the final REST APIs endpoints to call.
   

This two-step process allows mobile clients to identify the organization’s infrastructure in the first step and then locate the exact server desired for the user in the second step. This allows for very flexible configurations in which different users are directed to different servers, or in which clients are directed to servers that replace the ones used in the past to protect the content. Similar capabilities are provided in Windows clients through the use of registry values.

The second operation is implemented as an HTTP GET call to the REST APIs in MDE as follows:

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

Where <ClusterURL> is the FQDN of an AD RMS cluster built by the RMS client based on the DNS SRV lookup response.

The response body will then contain the list of the aforementioned service endpoints and corresponding URLs in JSON format in the context of the request. The following JSON example illustrates a sample response body:

[{

"Name": "enduserlicenses",

"Uri": "https://adrms.contoso.com/my/v1/enduserlicenses"

},

{

"Name": "templates",

"Uri": "https://adrms.contoso.com/my/v1/templates"

},

{

"Name": "publishinglicenses",

"Uri": "https://adrms.contoso.com/my/v1/publishinglicenses"

}]

Since the first step of the endpoint discovery uses DNS and relies for that purposes on specific SRV service discovery records, the Service Connection Point (SCP) declared in the Active Directory is not used by the Mobile Device Extension.

Note The SCP is an object in the Active Directory configuration partition that holds the Web address of the AD RMS cluster. RMS-enlightened applications built with RMS SDKs whose version is prior to 3.0 use the SCP to discover the AD RMS service; it is the first connection point for users to discover the AD RMS SOAP-based web service endpoints. Only one SCP can exist in your Active Directory forest.

A SCP can be viewed using ADSI Edit for instance. To view the SCP, connect to the configuration container in ADSI Edit and navigate the following nodes: CN=Configuration [server name], CN=Services, CN=RightsManagementServices, CN=SCP.

From a practical standpoint, the RMS client uses DNS SRV records to find the right location for the services used for:

1. 
   Authoring, i.e. protecting a file.
   
2. 
   The consumption of a protected file.
   

Different DNS SRV records must be consequently created in the authoritative DNS for the organization’s domain(s) to support these processes. The next sections cover the DNS SRV records required for a fully functional RMS service discovery mechanism for mobile devices.

Understanding the DNS SRV service discovery records to create

To operate and enable the aforementioned scenarios, the Mobile Device Extension requires the creation in the DNS service one or more DNS SRV service discovery records in the organization’s domain(s) as per RFC 6763 DNS-Based Service Discovery¹⁹:

• 
  One record for each email domain suffix that users will use.
  
• 
  One record for every FQDN used by the AD RMS clusters in place to protect content.
  

Service discovery record for the email domain suffix

During first use of the mobile applications to protect content, users will be asked for their email address. The domain part of this address will be used to locate the right RMS infrastructure to handle the user’s operations.

The service discovery record that relates to the email domain suffix for the user has the following format:

_rmsdisco._http._tcp.<email suffix><port number>RMS cluster FQDN>

Where:

• 
  suffix> is the email domain suffix that users will use,
  
• 
  <port number>is the port number used by an on-premises AD RMS cluster,
  
• 
  <AD RMS cluster FQDN> is the FQDN used by an on-premises AD RMS cluster.
  

When users supply their email address from their mobile device, the domain suffix is used to identify whether they should use an on-premises AD RMS cluster or Azure RMS. When the SRV record is found, the RMS client redirects to the RMS service that responds to this record (see below).

Important note If all the users of the organization use child domains from a single parent domain, and all users from this contiguous namespace use the same AD RMS cluster, only one SRV record in the parent domain is needed, and the RMS client will find the appropriate DNS records (see below).

For example, if an organization has users with the following email addresses:

• 
  <user alias>@contoso.com
  
• 
  <user alias>@europe.contoso.com
  
• 
  <user alias>@fabrikam.com
  

And if there are no other child domain(s) for contoso.com and no other parent domain(s) that use a different AD RMS cluster than the one named adrms.contoso.com, the following two DNS SRV records must be created in DNS:

_rmsdisco._http._tcp.contoso.com 443 adrms.contoso.com

_rmsdisco._http._tcp.fabrikam.com 443 adrms.contoso.com

Service discovery record for the FQDN used by the AD RMS clusters in place

When consuming protected content, the mobile apps will use the URL in the Publishing License in the content to identify the right server to reach out to. Since it is possible that the original server has been replaced by another server with a different URL, a DNS-based service discovery call is performed based on the URL in the PL. The service discovery record that relates to the FQDN used by an AD RMS cluster in place to protect content has the following format:

_rmsdisco._http._tcp.< AD RMS cluster FQDN><port number>RMS cluster FQDN>

Where:

• 
  <AD RMS cluster FQDN> is the FQDN used by an on-premises AD RMS cluster,
  
• 
  <port number>is the port number used by an on-premises AD RMS cluster.
  

For example, if an AD RMS cluster deployed on-premises is adrms.contoso.com and it is desired that the same cluster, which has MDE installed, is used to consume content with mobile devices, a DNS SRV record that has the following value must be created in DNS:

_rmsdisco._http._tcp.adrms.contoso.com 443 adrms.contoso.com

Note that since this organization also has users using the same domain in their email addresses, this DNS entry is already included in those used for email domain-based service discovery. Thus, the organization used in this example would only need two DNS SRV records for RMS service discovery.

The next sections depict how these SRV records are queried by mobile devices to dynamically discover the endpoints for authoring and consuming content thanks to the above service discovery mechanism.

Understanding the basic flow for authoring content

The process for a mobile RMS-enlightened app to author content is as follows. The app uses the RMS SDK 4.0 and thus the related RMS client:

1. 
   For the initial domain resolution, the user specifies their email address in the app. The RMS client calls the DNS service and queries for the service discovery record which corresponds to the user’s email domain suffix.
   

If not found, the RMS client repeats the call for the user’s email address domain’s parent and iterates the process until a match is found or it reaches the second level domain.

As previously noted, this allows to use only one DNS SRV record in the parent domain if all of all the users of the organization use child domains from a single parent domain, and all users from this contiguous namespace use the same AD RMS cluster.

2. 
   This record points to the on-premises AD RMS cluster.
   

The response from the DNS service is processed by the RMS client to build the service discovery URL to call.

3. 
   The RMS client then makes a service discovery call to the endpoint URL discovered previously.
   
4. 
   On initial access the call to this endpoint will return a 401 error code and will redirect the client to the environment’s federation server where the authentication process will be performed as described in section § Understanding how authentication works with the service endpoints below in this document. Steps 5-8 of the authentication process are explained in that section.
   
5. 
   Once the client has obtained an access token, it passes the token to the service discovery URL to which it tried to authenticate
   
6. 
   Upon acceptance of the token received from the service the URL of the RMS cluster is used by this user. The service discovery endpoint returns a list of rights management services (publish license, end user license, and templates) and corresponding endpoint URLs. These endpoints may be in the same RMS cluster (i.e. under the same FQDN) or in a different cluster if RMS is configured to direct the calling user to a different server. This may be done in the case where Licensing-Only clusters are deployed in the environment to handle different groups of users.
   

Note that in this example, this is the same RMS cluster.

7. 
   The client contacts the URLs obtained in the previous step in order to obtain from the service the templates, and then the publishing license (PL).
   
8. 
   The app can finally protect the content.
   

As illustrated above, the publishing licenses (PL) are built by the AD RMS server and embedded by the RMS client, and all the transactions are atomic:

• 
  The client trusts the service endpoint URLs, and SSL/TLS is mandatory. There is no Server Licensor Certificate (SLC). The SLC is issued to licensing servers and grants them the right to issue PL, end use licenses (UL), client licensor certificates (CLC), and rights policy templates.
  
• 
  The client authenticates and acquires PL in one operation. There is no Rights Account Certificate (RAC). The RAC identifies a user in the context of a specific computer or device.) Consequently, there is no machine certificate either.
  
• 
  The client builds the policy and gets the PL from the server. There is no CLC. The CLC grants a user the right to publish (offline) AD RMS-protected content.
  

Note For introduction on the AD RMS certificates and licenses, see the post Licenses and Certificates, and how AD RMS protects and consumes documents²⁰ on the AD RMS Team Blog.

The Mobile Device Extensions do not support offline publishing from mobile devices at the time of publishing of this document.

Understanding the basic flow for consuming content

When a user consumes protected content with a mobile device, the process for the mobile RMS-enlightened app to activate is as follows. The app uses the RMS SDK 4.0 and thus the related RMS client:

1. 
   For the initial domain resolution, the RMS client looks in DNS for a service discovery record that matches the FQDN in the URL of the RMS service that protected the content. This URL is specified in the publishing license.
   
2. 
   The response from the DNS service is processed by the RMS client to build the discovery service URL to call.
   
3. 
   The RMS client then makes a call to the service discovery endpoint in the URL discovered previously.
   
4. 
   On initial access the call to this endpoint will return a 401 error code and will redirect the client to the environment’s federation server where the authentication process will be performed as described in section § Understanding how authentication works with the service endpoints below in this document. Steps 4-7 in this authentication process are explained in that section. Once the client has obtained an access token it passes the token to the service discovery URL to which it tried to authenticate.
   
5. 
   Upon acceptance of the token received from the service the URL of the RMS cluster is used by this user.
   
6. 
   The service discovery endpoint returns the list of rights management services (publish license, end use license, and templates) and corresponding endpoint URLs is provided to the client in the response (as described before). These endpoints may be in the same RMS cluster (i.e. under the same FQDN) or in a different cluster if RMS is configured to direct the calling user to a different server. This may be done in the case where Trusted Publishing Domains are exchanged between RMS clusters to have one cluster handle the load for some or all users for content protected in another cluster.
   
7. 
   The RMS client then makes a call to the endpoint discovered previously passing the access token in order to acquire an end use license (EUL) to open the content.
   
8. 
   Once a EUL has been issued the mobile RMS-enlightened app finally renders the content.
   

As illustrated above, the EULs are delivered by the AD RMS server to the RMS client every time and, likewise the previous flow, all the transactions are atomic. As previously outlined:

• 
  The client trusts the service endpoint URLs, and SSL/TLS is mandatory. There is no SLC.
  
• 
  The client authenticates and acquires EUL in one operation. There is neither RAC nor machine certificate.