Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Enable your service application to work with cloud based RMS

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  

It is a recommended best practice to test your Rights Management Services SDK 2.1 application first with the RMS pre-production environment against an RMS Server. Then, should you want your customer to have the ability to use your application with the Azure RMS Service, move to testing with that environment.

In order to use your RMS SDK 2.1 service application with Azure RMS, you will need to request an Azure RMS Tenant, if you don’t already have one. Send mail to rmcstbeta@microsoft.com with your tenant request.

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 IPC_CONNECTION_INFO parameter of IpcGetTemplateList or IpcGetTemplateIssuerList.

      Generate a symmetric key and collect the needed information

      Instructions to generate a symmetric key

      • Install Microsoft Online Sign-in Assistant
      • Install Azure AD Powershell Module.

        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 key including the key itself and AppPrincipalId.

        The following symmetric key was created as one was not supplied 
        ZYbF/lTtwE28qplQofCpi2syWd11D83+A3DRlb2Jnv8=
        
        DisplayName : GurgenTestApp
        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 aadrm
        Connect-AadrmService (type-in your admin credentials)
        Get-AadrmConfiguration

        The command will generate output, something like this:

        BPOSId                                    : 23976bc6-dcd4-4173-9d96-dad1f48efd42
        RightsManagementServiceId                 : 1a302373-f233-4406-9090-4cdf305e2e76
        LicensingIntranetDistributionPointUrl     : https://1a302373-f233-4406-9090-4cdf305e2e76.rms.na.aadrm.com/_wmcs/licensing
        LicensingExtranetDistributionPointUrl     : https://1a302373-f233-4406-9090-4cdf305e2e76.rms.na.aadrm.com/_wmcs/licensing
        CertificationIntranetDistributionPointUrl : https://1a302373-f233-4406-9090-4cdf305e2e76.rms.na.aadrm.com/_wmcs/certification
        CertificationExtranetDistributionPointUrl : https://1a302373-f233-4406-9090-4cdf305e2e76.rms.na.aadrm.com/_wmcs/certification
        
      
      // 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 tenent identifier";
      
      

      For more information see, IPC_CREDENTIAL_SYMMETRIC_KEY.

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

      
      // Create a credential structure.
      IPC_CREDENTIAL cred = {0};
      
      // 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 IpcGetTemplateIssuerList with IPC_PROMPT_CTX.

    
    PCIPC_TEMPLATE_ISSUER_LIST pTemplateIssuerList = NULL;
    
    hr = IpcGetTemplateIssuerList(NULL, 
           0, 
           &promptCtx, 
           NULL, 
           &pTemplateIssuerList);
    
    

    Call IpcGetTemplateList passing in the same instance of IPC_PROMPT_CTX, and pass on the connectionInfo received from IpcGetTemplateIssuerList.

    
    PCIPC_TIL pTemplates = NULL; 
    IPC_TEMPLATE_ISSUER templateIssuer = (pTemplateIssuerList->aTi)[0];
    
    hr = IpcGetTemplateList(&(templateIssuer.connectionInfo),
           IPC_GTL_FLAG_FORCE_DOWNLOAD, 
           0, 
           &promptCtx, 
           NULL, 
           &pTemplates);
    
    
    Tip  You could choose to specify a custom license handle by calling IpcCreateLicenseFromScratch or IpcCreateLicenseFromTemplateID instead of performing the previous two steps.
  • 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.

Related topics

Developer concepts
Getting started with Azure Rights Management
Getting started with RMS SDK 2.1
Create a service identity via ACS
IpcSetGlobalProperty
IpcInitialize
IPC_PROMPT_CTX
IPC_CREDENTIAL
IPC_CREDENTIAL_SYMMETRIC_KEY
IpcGetTemplateIssuerList
IpcGetTemplateList
IpcfDecryptFile
IpcfEncrcyptFile
IpcCreateLicenseFromScratch
IpcCreateLicenseFromTemplateID

 

 

Show:
© 2015 Microsoft