How-to: enable your service application to work with cloud based RMS

  • Article

Important

Versions of the Microsoft Rights Management Service SDK released prior to March 2020 are deprecated; applications using earlier versions must be updated to use the March 2020 release. For full details, see the deprecation notice.

No further enhancements are planned for the Microsoft Rights Management Service SDK. We strongly recommend adoption of the Microsoft Information Protection SDK for classification, labeling, and protection services.

This topic outlines steps for setting up your service application to use Azure Rights Management. For more information, see Getting started with Azure Rights Management.

Important
In order to use your Rights Management Services SDK 2.1 service application with Azure RMS, you'll need to create your own tenants. For more information, see Azure RMS requirements: Cloud subscriptions that support Azure RMS

Prerequisites

Connecting to the Azure Rights Management Service

  • Call IpcInitialize.

  • Set IpcSetGlobalProperty.

    int mode = IPC_API_MODE_SERVER;
IpcSetGlobalProperty(IPC_EI_API_MODE, &(mode));

    Note For more information, see Setting the API security mode

  • The following steps are the setup for creating an instance of an IPC_PROMPT_CTX structure with the pcCredential (IPC_CREDENTIAL) member populated with connection information from the Azure Rights Management Service.

  • Use the information from your symmetric key service identity creation (see the prerequisites listed earlier in this topic) to set the wszServicePrincipal, wszBposTenantId, and cbKey parameters when you create an instance of an IPC_CREDENTIAL_SYMMETRIC_KEY structure.

Note - Due to an existing condition with our discovery service, if you are not in North America, symmetric key credentials are not accepted from other regions therefore, you must specify your tenant URLs directly. This is done through the pConnectionInfo parameter, type IPC_CONNECTION_INFO, on functions IpcGetTemplateList or IpcGetTemplateIssuerList.

Generate a symmetric key and collect the needed information

Instructions to generate a symmetric key

Note - You must be a tenant administrator to use the Powershell cmdlets.

  • Start Powershell and run the following commands to generate a key

    Import-Module MSOnline

    Connect-MsolService (type-in your admin credentials)

    New-MsolServicePrincipal (type-in a display name)

  • After it generates a symmetric key, it will output information about the key including the key itself and an AppPrincipalId.

    The following symmetric key was created as one was not supplied
ZYbF/lTtwE28qplQofCpi2syWd11D83+A3DRlb2Jnv8=

DisplayName : RMSTestApp
ServicePrincipalNames : {7d9c1f38-600c-4b4d-8249-22427f016963}
ObjectId : 0ee53770-ec86-409e-8939-6d8239880518
AppPrincipalId : 7d9c1f38-600c-4b4d-8249-22427f016963

Instructions to find out TenantBposId and Urls

  • Install Azure RMS powershell module.

  • Start Powershell and run the following commands to get the RMS configuration of the tenant.

    Import-Module AIPService

    Connect-AipService (type-in your admin credentials)

    Get-AipServiceConfiguration

  • Create an instance of an IPC_CREDENTIAL_SYMMETRIC_KEY and set a few members.

    // Create a key structure.
IPC_CREDENTIAL_SYMMETRIC_KEY symKey = {0};

// Set each member with information from service creation.
symKey.wszBase64Key = "your service principal key";
symKey.wszAppPrincipalId = "your app principal identifier";
symKey.wszBposTenantId = "your tenant identifier";

For more information see, IPC_CREDENTIAL_SYMMETRIC_KEY.

  • Create an instance of an IPC_CREDENTIAL structure containing your IPC_CREDENTIAL_SYMMETRIC_KEY instance.

    Note - The connectionInfo members are set with URLs from the previous call to Get-AipServiceConfiguration and noted here with those field names.

    // Create a credential structure.
IPC_CREDENTIAL cred = {0};

IPC_CONNECTION_INFO connectionInfo = {0};
connectionInfo.wszIntranetUrl = LicensingIntranetDistributionPointUrl;
connectionInfo.wszExtranetUrl = LicensingExtranetDistributionPointUrl;

// Set each member.
cred.dwType = IPC_CREDENTIAL_TYPE_SYMMETRIC_KEY;
cred.pcCertContext = (PCCERT_CONTEXT)&symKey;

// Create your prompt control.
IPC_PROMPT_CTX promptCtx = {0};

// Set each member.
promptCtx.cbSize = sizeof(IPC_PROMPT_CTX);
promptCtx.hwndParent = NULL;
promptCtx.dwflags = IPC_PROMPT_FLAG_SILENT;
promptCtx.hCancelEvent = NULL;
promptCtx.pcCredential = &cred;

Identify a template and then encrypt

  • Select a template to use for your encryption. Call IpcGetTemplateList passing in the same instance of IPC_PROMPT_CTX.

    PCIPC_TIL pTemplates = NULL;
IPC_TEMPLATE_ISSUER templateIssuer = (pTemplateIssuerList->aTi)[0];

hr = IpcGetTemplateList(&(templateIssuer.connectionInfo),
       IPC_GTL_FLAG_FORCE_DOWNLOAD,
       0,
       &promptCtx,
       NULL,
       &pTemplates);

  • With the template from earlier in this topic, call IpcfEncrcyptFile, passing in the same instance of IPC_PROMPT_CTX.

    Example use of IpcfEncrcyptFile:

    LPCWSTR wszContentTemplateId = pTemplates->aTi[0].wszID;
hr = IpcfEncryptFile(wszInputFilePath,
       wszContentTemplateId,
       IPCF_EF_TEMPLATE_ID,
       IPC_EF_FLAG_KEY_NO_PERSIST,
       &promptCtx,
       NULL,
       &wszOutputFilePath);

    Example use of IpcfDecryptFile:

    hr = IpcfDecryptFile(wszInputFilePath,
       IPCF_DF_FLAG_DEFAULT,
       &promptCtx,
       NULL,
       &wszOutputFilePath);

You have now completed the steps needed to enable your application to use Azure Rights Management.