Microsoft DKE APIs

CCKM provides support for Double Key Encryption (DKE) for Microsoft 365. With DKE, two keys are used to access content (such as files or documents) that is protected with the sensitivity labels that you apply when using any one of the supported Microsoft Office apps. You hold one key in CCKM, which you maintain full control over using Microsoft’s Double Key Encryption service. The other is securely stored within Microsoft Azure. To decrypt and gain access to the protected content, both keys are required. Since Microsoft holds only one of the keys, this solution ensures that Microsoft cannot independently access this content. Only your authorized users can access the protected content.

Only your highly confidential data should be protected by DKE, which is typically a small percentage of your organization’s overall data. For more information about DKE, guidance on what type of content to protect, the supported office applications, and other information, refer to Double Key Encryption.

DKE encryption workflow

1. User adds a DKE label to a document. The Microsoft Office client connects to Azure RMS (Protection Service).

2. User certificate, API templates, and Azure RMS key are sent to the Microsoft Office client.

3. Microsoft Office client requests CCKM for the DKE public key associated with the applied label.

4. CCKM verifies the request. After authorization succeeds, CCKM sends the DKE public key to the Microsoft Office client.

5. Microsoft Office client encrypts the document content with the content key.

6. Microsoft Office client encrypts the part of the metadata that controls access to the content with the DKE public key.

7. Microsoft Office client encrypts the encrypted metadata with the Azure RMS key.

The content is protected with the double-encrypted content key, RMS key and DKE public key. The following illustration shows the DKE encryption workflow:

DKE decryption workflow

1. User opens a document which has a DKE label. The Microsoft Office client first sends the double-encrypted metadata to Azure RMS (Protection Service).

2. Azure RMS (Protection Service) decrypts the double-encrypted metadata using the Azure RMS key and returns the simple-encrypted metadata.

3. Microsoft Office client sends the simple-encrypted metadata to CCKM and requests CCKM to decrypt it.

4. CCKM verifies the request and goes through the authorization process. When authorization passes successfully, CCKM decrypts the simple-encrypted metadata and returns the decrypted metadata to the Microsoft Office client.

5. Microsoft Office client uses the content key to decrypt the document. The user can view the document content.

The following illustration shows the DKE decryption workflow:

The following are the high-level steps to configure DKE within Microsoft and CipherTrust Manager/CCKM:

1. Complete the prerequisites.

2. Configure DKE on CCKM.

3. Register your DKE service from Microsoft Azure portal.

4. Create the DKE sensitivity label and label policy.

Prerequisites

In preparation for deploying DKE, ensure that the following prerequisites are met:

1. Ensure CipherTrust Manager/CCKM is installed and running. In addition, ensure to activate and install the CCKM license. Refer to the CipherTrust Manager Deployment Guide and Licensing for details.

2. The NTP server is added. Refer to Add an NTP Server for details.

3. Install a third-party CA certificate on the web interface.

   Note

   We recommend obtaining a CA-signed certificate for the web interface from trusted CAs that are part of the Microsoft Trusted Root Program. For more information, refer to Microsoft Trusted Root Program participants.

4. Ensure the following.

   • If you have a load balancer that terminates the TLS connection and has mTLS disabled, the load balancer has a valid TLS certificate signed by a trusted CA.

   • If you have a load balancer that doesn't terminate the TLS connection or you don't have a load balancer in front of CipherTrust Manager, CipherTrust Manager has a valid TLS certificate signed by a trusted CA.

   • Additional DNS record is configured with dke. prefix and pointing to the same IP Address of the CipherTrust Manager or SSL Passthrough Load Balancer.

   • Subject Alternative Name (SAN) in the TLS certificate includes dke. prefixed DNS name, along with other DNS names associated with CipherTrust Manager or SSL Passthrough Load Balancer.

5. Microsoft 365 E5 License: Windows clients must have a Microsoft 365 E5 license. Refer to information about system and licensing requirements for DKE for more information these licensing requirements.

   Note

   CCKM supports built-in sensitivity labeling with Office apps. CCKM does not support Azure Information Protection unified labeling client, which is to be deprecated in the future.

6. User Presence in Azure Directory: Users who have to create and share documents or files protected by DKE must be part of the Azure Active Directory (Azure AD) associated with the organization's tenant.

   Note

   • DKE is tested on the Windows and iOS devices. It is not tested on macOS and Android devices.

   • To configure the B2B cross-tenant access settings, refer to Configure cross-tenant access settings for B2B collaboration.

You can now Configure DKE on CCKM.

Configure DKE on CCKM

To configure DKE on CCKM, do the following:

1. From the CCKM GUI or API, create a DKE endpoint. Refer to Creating Microsoft DKE Endpoints for details on how to create a DKE endpoint from the CCKM GUI or Creating Microsoft DKE Endpoints using the CCKM API.

   Note

   • Only Azure AD users are currently supported. The email addresses included in the API call must be associated with a user Azure AD. The email address parameter an optional field applicable only if authorization_type is set to email.

     If you specified one or more email addresses in a DKE endpoint, this field would be validated against JWT received in the decrypt operation.

   • A Microsoft Office 365 client user and email (if configured in CipherTrust Manager) must match.

   • The Issuer field must be specific to the tenant configured in the Microsoft Azure Portal.

   • The web interface port within CipherTrust Manager can be changed from the default port of 443 to another port. If you plan to change the default port for the CipherTrust Manager web interface, ensure to change it BEFORE configuring the Microsoft DKE service on CCKM. Also reflect this port change when creating a DKE endpoint on CCKM as part of the prerequisites for deploying DKE. Changing the default port AFTER configuring Microsoft DKE is not supported.

Register DKE Service

After creating a DKE endpoint, register your DKE service from the Microsoft Azure portal.

Single Tenant Application

When to Use the Single Tenant Application

Single tenant applications are only available in the tenant they were registered in, also known as their home tenant. DKE-labeled data will only be used within home tenant, configured with one CCKM environment.

For more details, refer to Tenancy in Microsoft Entra ID.

Register a Single Tenant Application

To register a single tenant application.

1. Sign in to the Microsoft Azure portal.

2. Under Azure services, click App registrations.

3. Click New registration.

4. Enter Name, like SingleTenantApplication.

5. Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Single Tenant) as the account type.

6. Under Redirect URI:

   1. Select Web as the platform.

   2. Enter the URI of CipherTrust Manager, like https://dke.thalescpl.io.

7. Click Register.

Copy the Application (client) ID and Directory (tenant) ID.

Now configure the single tenant application that includes the following.

1. Authenticate Tokens and ID Tokens

2. Adding a Certificate or Secret.

   Note

   • It is optional to add a certificate or secret.

   • You will get the credentials after adding a certificate or secret. You will need the credentials during the role-based authentication.

3. Adding an API permission.

4. Exposing an API.

5. Adding the Owner.

   Note

   It is optional to add the owner.

Authenticate Tokens and ID Tokens

To authenticate the tokens and ID tokens.

1. Go to the left pane, click Manage > Authentication.

2. Enable Access tokens

3. Enable ID Tokens.

4. Click Save.

Adding a Certificate or Secret

To add a certificate or secret.

1. Go to the left pane, click Manage > Certificates & secrets.

2. Click New client secret. The Add a client secret wizard is displayed.

3. Enter Description.

4. (Optional) Select the desired Expires (Expiry days) from the drop-down list.

5. Click Add.

Copy the Value and Secret ID of the secret. You will need the Value and Secret ID to add an Azure connection on CCKM.

Adding an API Permission

To add an API permission.

1. Go to the left pane, click Manage > API permissions.

2. Click Add a permission. The Request API permissions wizard is displayed.

3. Click Microsoft Graph.

4. Click Application permissions.

5. In the Select permissions search box, search for Directory.

6. Expand Directory from the result.

7. Select Directory.Read.All from the Directory list.

8. Click Add permissions.

9. Click Grant admin consent for {tenant}. The Grant admin consent confirmation dialog box is displayed.

10. Click Yes.

Exposing an API

Exposing an API includes adding the Application ID URI, adding a scope, and authorizing the client applications.

Adding the application ID URI.

1. Go to the left pane, click Manage > Expose an API.

2. Click Add. The Edit application ID URI is displayed.

3. Enter Application ID URI, the URI of the CipherTrust Manager.

4. Click Save.

Adding a scope.

1. Click Add a scope. The Add a scope wizard is displayed.

2. Enter Scope name, like "user_impersonation".

3. Select the Consent as Admins and users.

4. Enter Admin consent display name.

5. Enter Admin consent description.

6. (Optional) Enter User consent display name.

7. (Optional) Enter User consent description.

8. (Optional) Enable State.

9. Click Add scope.

Authorizing the client applications.

You need to authorize the Microsoft Office and Azure Information Protection applications. Perform the below steps for both the applications.

1. Click Add a client application. The Add a client application wizard is displayed.

2. Enter Client ID.

   Note

   The Client ID of Microsoft Office and Azure Information Protection applications are d3590ed6-52b3-4102-aeff-aad2292ab01c and c00e9d32-3c8d-4a7d-832b-029040e7db99, respectively.

3. Enable Authorized scopes.

4. Click Add application.

Adding the Owner

To add the owner.

1. Go to the left pane, click Manage > Owners.

2. Click Add owners.

3. Search and select the desired owner.

4. Click Select.

Multitenant Application

When to Use the Multitenant Application

Multitenant applications are available to the users in both their home tenant and other tenants. Multitenant application can be used for the following.

• Cross-tenant access for B2B collaboration.

• Sharing one DKE endpoint across multiple Azure tenants.

• Using one CCKM environment for supporting DKE in multiple Azure tenants. For example Managed Service Providers need to create a multitenant application when their customers share one CCKM environment.

For more details, refer to Tenancy in Microsoft Entra ID.

Register a Multitenant Application

To create a multitenant application.

1. Sign in to the Microsoft Azure portal.

2. Go to the left pane, click Authentication.

3. Click App registrations.

4. Click New registration.

5. Enter Name, like MultiTenantApplication.

6. Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) as the account type.

7. Under Redirect URI:

   1. Select Web as the platform

   2. Enter the URI of CipherTrust Manager, like https://dke.thalescpl.io.

8. Click Register.

Copy the Application (client) ID and Directory (tenant) ID.

Now configure the multitenant application that includes the following.

1. Authenticate Tokens and ID Tokens

2. Adding a Certificate or Secret.

   Note

   • It is optional to add a certificate or secret.

   • You will get the credentials after adding a certificate or secret. You will need the credentials during the role-based authentication.

3. Adding an API permission.

4. Exposing an API.

5. Adding the Owner.

   Note

   It is optional to add the owner.

Authenticate Tokens and ID Tokens

To authenticate the tokens and ID tokens.

1. Go to the left pane, click Manage > Authentication.

2. Enable Access tokens

3. Enable ID Tokens.

4. Click Save.

Adding a Certificate or Secret

To add a certificate or secret.

1. Go to the left pane, click Manage > Certificates & secrets.

2. Click New client secret. The Add a client secret wizard is displayed.

3. Enter Description.

4. (Optional) Select the desired Expires (Expiry days) from the drop-down list.

5. Click Add.

Copy the Value and Secret ID of the secret. You will need the Value and Secret ID to add an Azure connection on CCKM.

Adding an API Permission

To add an API permission.

1. Go to the left pane, click Manage > API permissions.

2. Click Add a permission. The Request API permissions wizard is displayed.

3. Click Microsoft Graph.

4. Click Application permissions.

5. In the Select permissions search box, search for Directory.

6. Expand Directory from the result.

7. Select Directory.Read.All from the Directory list.

8. Click Add permissions.

9. Click Grant admin consent for {tenant}. The Grant admin consent confirmation dialog box is displayed.

10. Click Yes.

Exposing an API

Exposing an API includes adding the Application ID URI, adding a scope, and authorizing the client applications.

Adding the application ID URI.

1. Go to the left pane, click Manage > Expose an API.

2. Click Add. The Edit application ID URI is displayed.

3. Enter Application ID URI, the URI of the CipherTrust Manager.

4. Click Save.

Adding a scope.

1. Click Add a scope. The Add a scope wizard is displayed.

2. Enter Scope name, like "user_impersonation".

3. Select the Consent as Admins and users.

4. Enter Admin consent display name.

5. Enter Admin consent description.

6. (Optional) Enter User consent display name.

7. (Optional) Enter User consent description.

8. (Optional) Enable State.

9. Click Add scope.

Authorizing the client applications.

You need to authorize the Microsoft Office and Azure Information Protection applications. Perform the below steps for both the applications.

1. Click Add a client application. The Add a client application wizard is displayed.

2. Enter Client ID.

   Note

   The Client ID of Microsoft Office and Azure Information Protection applications are d3590ed6-52b3-4102-aeff-aad2292ab01c and c00e9d32-3c8d-4a7d-832b-029040e7db99, respectively.

3. Enable Authorized scopes.

4. Click Add application.

Adding the Owner

To add the owner.

1. Go to the left pane, click Manage > Owners.

2. Click Add owners.

3. Search and select the desired owner.

4. Click Select.

Create DKE Sensitivity Label and Label Policy

After successfully registering the DKE service, create the DKE sensitivity label from the Microsoft Compliance portal. To use the senstivity level, you need to publish it by creating a new label policy.

Create DKE Sensitivity Label

To create a DKE sensitivity label.

1. Sign in to the Microsoft Compliance portal.

2. Go to the left pane, under the Solutions section, click lnformation protection > Labels.

3. Click Create a Label. The Label details tab of the New sensitivity label screen is displayed.

Label details

1. Enter Name.

2. Enter Display name.

3. (Optional) Select a Label Priority from the drop-down list.

4. Enter Description for users.

5. Click Next. The Scope tab is displayed.

Scope

1. Ensure that Files, Emails, and Schematized data assets (preview) are enabled.

2. Click Next. The Items tab is displayed.

Items

1. Enable Control access.

2. Enable Apply content marking.

3. Click Next. Within the Items tab, the Access control section is displayed.

4. Select Configure access control settings.

5. Select Assign permissions now from the Assign permissions now or let users decide? drop-down list.

6. Select Never from the User access to content expires drop-down list.

7. Select Never from the Allow offline access drop-down list.

   Note

   For labels that are configured to have Offline Access set to Never, the decrypt requests will be sent to the CipherTrust Manager. Otherwise, if labels are configured to have Offline Access set to Always, the decrypt requests will not be sent to the CipherTrust Manager.

8. Under Assign permissions to specific users and groups, click Assign permissions. The Assign permissions wizard is displayed.

9. Click Add all users and groups in your organization.

10. (Applicable to multitenant only) Add the email addresses or domains of the other tenants.

    1. Click Add specific email addresses or domain.

    2. Enter email addresses or domains.

    3. Click Add.

11. Click Save.

12. Enable Use Double Key Encryption.

13. Enter DKE Endpoint URL. You can copy the desired DKE Endpoint URL from CCKM. Refer to the Viewing DKE endpoints section.

14. Click Next. The Content marking section is displayed.

15. (Optional) Enable Content marking.

16. Click Next. The Auto-labeling for files and emails section is displayed.

17. Click Next. The Groups & sites tab is displayed.

Groups & sites

    Click Next. The Schematized data assets (preview) tab is displayed.

Schematized data assets (preview)

    Click Next. The Finish tab is displayed.

Finish

1. Click Create Label.

2. Click Done.

Create Policy

After creating the sensitivity label, the Publish Label wizard is displayed. Click Create new label policy to create a new label policy. Alternatively, you can also create a new label policy from the lnformation protection > Label policies section. The Labels to publish tab of the Create Policy screen is displayed.

Labels to publish

1. Click Choose sensitivity labels to publish. The Sensitivity labels to publish wizard is displayed.

2. Select the Label that you have created above, from the list.

3. Click Add.

4. Click Next. The Admin units tab is displayed.

Admin units

    Click Next. The Users and groups tab is displayed.

Users and groups

1. Enable Users and groups.

2. Click Next. The Settings tab is displayed.

Settings

1. Click Next. Within the Settings tab, the Documents section is displayed.

2. Select the label that you created above as the Default label.

3. Click Next. The Emails section is displayed.

4. Select the label that you created above as the Default label.

5. Click Next. The Meetings section is displayed.

6. Click Next. The Fabric and Power BI section is displayed.

7. Click Next. The Name tab is displayed.

Name

1. Enter the Name of the label policy.

2. (Optional) Enter Description.

3. Click Next. The Finish tab is displayed.

Finish

1. Click Submit.

2. Click Done.

The new label policy is created. After a label is published by the defining policy, it can take up to 24 hours for a label to be made available (after the label policy is published) for use in a Microsoft 365 Apps, such as Word or PowerPoint.

Refer to the following DKE API sections:

• Creating DKE Endpoints

• Fetching List of DKE Endpoints

• Viewing Details of DKE Endpoints

• Updating Attributes of DKE Endpoints

• Deleting DKE Endpoints

• Rotating DKE Endpoints

• Enabling Key-Rotation Schedule for DKE Endpoint

• Disabling Key-Rotation Schedule for DKE Endpoint

• Enabling DKE Endpoints

• Disabling DKE Endpoints

• Archiving DKE Endpoints

• Recovering DKE Endpoints

• Creating DKE Authorized Tenants

• Viewing Details of DKE Authorized Tenants

• Fetching List of DKE Authorized Tenants

• Updating Attributes of DKE Authorized Tenants

• Deleting DKE Authorized Tenants

• Fetching List of DKE Roles