Microsoft Azure Rights Management Service

The Microsoft Rights Management Service (RMS) classifies and optionally encrypts documents. This service forms the rights management part of Microsoft Azure Information Protection (AIP).

For many of the files that Azure RMS can classify and encrypt, File Content Extraction can identify whether they have been encrypted with RMS encryption. It can also extract metadata (including the RMS classification) and XrML associated with the document.

To decrypt and access the content of protected files, you must provide some credentials. For information about credentials, see RMS Credentials.

When you use Azure RMS decryption, consider the following notes:

Azure RMS decryption is licensed as an additional product.
If your license does not allow for Azure RMS decryption, fpConfigureRMS() returns the error code KVError_ReaderUsageDenied.
To access the protected content, File Content Extraction must make an HTTP request. The time required to do so means that protected files take longer to process than unprotected files.
By default, File Content Extraction uses the system proxy when it makes HTTP requests to obtain the key. You can also specify the proxy manually in the configuration file. See Configure the Proxy for RMS.
This function is supported only on certain platforms, see RMS Decryption in the platform differences section.

CAUTION: When Filter or File Extraction API functions access the protected contents of Azure RMS-protected files, File Content Extraction may place decrypted contents into the temporary directory. If you want to manage the security of such files, you might want to change the temporary directory. For information about how to configure the location of the temporary directory, see Protect the Temporary Directory.

RMS Credentials

To access the protected contents of Microsoft Azure Rights Management System (RMS) protected files, your end-user must register an application on the relevant Azure domain. For more information about how to register an app, refer to the Microsoft documentation.

After they register an application, they can find their client and tenant IDs in the Azure Portal, in the Overview section. They must then add a client secret, in the Certificates & Secrets section.

CAUTION: This information is linked to the domain itself, rather than to a specific user. Providing this information allows File Content Extraction to access the contents of all files protected by this domain. Therefore you must handle these three pieces of information securely.

You can provide the credentials required to access protected files by calling fpConfigureRMS(). This allows File Content Extraction to operate on the protected data of the file.

Resolve MSIP Label Names

An MSIP Label (sensitivity label) has a unique identifier (a GUID) and a human-readable name. Often both of these are stored within the file in which case File Content Extraction reports both in the KVMetadataKey_MIPLabel field. For some files however, only the GUID is stored. If you provide appropriate credentials, File Content Extraction can use Microsoft APIs to look up the human readable label.

To authenticate with the Microsoft APIs, your end user must go to the Microsoft Azure Portal and create an OAuth service application:

The application must have a redirect URL (to the Knowledge Discovery OAuth tool). OpenText recommends http://localhost:7878/oauth.
In the Certificates & Secrets section, upload a certificate that can be used to authenticate requests to the API.
To generate a self-signed certificate using OpenSSL
The following commands demonstrate how to use OpenSSL version 3.0 to generate a self-signed certificate. The output file certificate.cer is the file to upload to Azure. The file certificate.pfx is a PKCS#12 file that includes the private key. You will need this file to use the OAuth configuration tool.
```
openssl req -x509 -days 365 -newkey rsa:2048 -keyout certificate.pem -out certificate.pem
```
```
openssl pkcs12 -export -in certificate.pem -out certificate.pfx
```
```
openssl x509 -outform der -in certificate.pem -out certificate.cer
```
The application must be granted the following API permission: Microsoft Graph > Application permissions > InformationProtectionPolicy.Read.All. Grant admin consent for this permission.

Then, your end-user must run the Knowledge Discovery OAuth configuration tool as described below. You can find the OAuth tool in the File Content Extraction SDK, in the PLATFORM/tools directory.

Open the OAuth tool configuration file, oauth_tool.cfg, in a text editor.

In the [Default] section, set any SSL or proxy settings that are required to access the Microsoft Graph API:

`SSLMethod`	The version of SSL/TLS to use. `Negotiate` means that File Content Extraction uses the most secure protocol supported by both client and server. You can enforce TLS 1.3 by setting this parameter to `TLSV1.3`.
`ProxyHost`	The host name or IP address of the proxy server to use.
`ProxyPort`	The port of the proxy server to use.

For example:

SSLMethod=NEGOTIATE
ProxyHost=10.0.0.1
ProxyPort=8080

In the [OAuthTool] section, set the following parameters:

`AdminConsentUrl`	Replace the placeholder `{TenantId}` with your Microsoft 365 Tenant, for example `mydomain.onmicrosoft.com`.
`TokenUrl`	Replace the placeholder `{TenantId}` with your Microsoft 365 Tenant, for example `mydomain.onmicrosoft.com`.
`AppKey`	The application key of the Azure application created to represent File Content Extraction.
`CustomValue0`	The path to the `.pfx` file that contains the certificate and private key to use to authenticate API requests.
`CustomValue1`	The password for the private key.

Open a command-line window and run the following command:

oauth_tool.exe oauth_tool.cfg OAuthTool

A web browser opens, asking you to log in and grant admin consent.
Log in and grant admin consent.

The web page displays a message stating that the OAuth details have been successfully stored, and the OAuth tool creates the files oauth.cfg and oauth2_sites.bin.

The file oauth2_sites.bin must be copied into the File Content Extraction bin directory. Finally, your end-user must create a configuration file named metadatacryptographyservices.cfg in the File Content Extraction bin directory. All of the parameters in oauth.cfg must be copied to the [Rms] section of that configuration file.