DKE Troubleshooting

The following blog post helps you troubleshoot the reference implementation for DKE. Some of this information may apply to DKE partner implementations as well, but it covers primarily the reference implementation hosted in Azure or on IIS. At any rate, this guide does not replace the official documentation. 

This blog post consists of three parts:

• Part A: Checklist
• Part B: Useful tools for troubleshooting DKE
• Part C: Step by step troubleshooting guide

 

Part A: Checklist

After installing / configuring DKE using the official documentation, going through this checklist will help you in identifying and correcting errors in your setup.

The troubleshooting guide below refers to some of the steps in this checklist, using the codes prepended to the titles of the sections (e.g. «CL1»).

 

CL1: Office version

DKE is supported on Microsoft 365 Apps for enterprise version 2009 or later. Here’s how you check the version:

 

CL2: DKE URL in root

The DKE service URL needs to be based on the root level, i.e. not a sub directory:

• Working example: https://dkeservice.contoso.com/samplekey1  
• This example does not work: https://webserver.contoso.com/dkeservice/samplekey1

 

CL3: No trailing slash in DKE URL

The DKE URL must not contain a trailing slash:

• Working example: https://dkeservice.contoso.com/samplekey1 
• This example does not work: https://dkeservice.contoso.com/samplekey1/

 

CL4: Outbound connectivity to Azure AD

In order to perform Azure AD authentication, the DKE service needs to have transparent outbound connectivity as described in box 56 of our documentation:

By adapting the source code of the DKE reference implementation, you may also use a forward proxy. The necessary changes have been implemented in an open pull request. Please observe that an anonymous proxy is required for this, i.e. a proxy that allows access to the necessary URLs without authentication.

 

CL5: Permissions in the sensitivity label used for DKE

The sensitivity label used for DKE protection needs to provide sufficient permissions for all intended recipients of the documents. During the test phase, it’s suggested to grant permission to the whole tenant:

 

After DKE has been tested successfully, it’s good practice to remove permissions on the sensitivity label for users and groups that are not allowed to access the DKE service.

 

CL6: Web application configuration

In the «Authentication» section of the DKE web application registration, verify that the redirect URI does not contain a trailing slash (see also CL3):

 

In the section “API permissions”, make sure the whole tenant has been granted consent to “User.Read”:

 

Check that these points have been addressed in the section “Expose an API”:

• The “Application ID URI” is configured as the DKE URL.
• Client Ids are registered both for Office (d3590ed6-52b3-4102-aeff-aad2292ab01c) and the AIP (Azure Information Protection) client (c00e9d32-3c8d-4a7d-832b-029040e7db99).

 

CL7: Recipients are allowed to use the DKE service

The DKE service authorizes users either via a list of email addresses or via membership in a local AD group. Either way, you have to ensure all test users are allowed to access the DKE service.
If you use email-based authorization, make sure email addresses of all users are included in the list of email addresses in the configuration file. Please observe that each individual user email address needs to be in quotes, e.g. ["jane.doe@contoso.com","albert.smith@contoso.com"].

 

CL8: Client connectivity to DKE and Azure AD

For acquiring the public key and for decrypting existing keys, clients needs to be able to reach the DKE service. To allow authentication, clients also require access to Azure AD.
Both transparent connectivity and forward proxies (with or without authentication) are supported.

 

CL9: DKE-related registry values are set on each client

Ensure the following registry values are defined on each client, please observe that some of the registry keys may also need to be created:

[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\MSIPC\flighting]
"DoubleKeyProtection"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSIPC\flighting]
"DoubleKeyProtection"=dword:00000001

 

CL10: Tenant is listed in the TrustedIssuers value

Check the following setting in the ‘TokenValidationParameters’ section of the DKE configuration file:
In ‘ValidIssuers’, your Azure AD tenant needs to be listed (e.g. «https://sts.windows.net/ 7d024093-e9a7-47e4-a205-bbbd4eed8e3a/»).

 

CL11: The host name in the "JwtAudience" is correct (case sensitive)

Ensure the host name contained in the "JwtAudience" value of the DKE configuration is identical to the host name in the DKE URL (including case).

 

Part B: Useful tools for troubleshooting DKE

The following tools have proven to be useful in debugging DKE installations.
Codes prepended to the titles of the sections (e.g. «T4») are again referenced in the step by step troubleshooting guide.

 

T1: Fiddler trace

Fiddler allows you to see the communication between the client and the DKE service in detail. To get a trace, consider performing the following steps:

1. Install and launch Fiddler, available on https://www.telerik.com/fiddler.
2. Select «Tools\Options», switch to tab «HTTPS», check option «Decrypt HTTPS» traffic, click OK and acknowledge prompts for installing a root certificate.
3. Try to reproduce the issue you want to debug.

In a Fiddler trace, you may check the communication with the DKE service.

 

T2: Export AIP Logs

In the Word toolbar, select «Sensitivity». Choose option «Help and Feedback» and click on «Export Logs»:

The ZIP file contains the relevant logs, for instance the MSIPC logs which cover DKE activity of the client.

 

T3: Web Server Logs

The web server logs show two kinds of activities:

1. Clients downloading the public key (when protecting content with DKE)
2. DKE clients attempting to run decrypt operations (when opening DKE protected content)

Repeated attempts for decrypt operations where the server responds with 401 would indicate authentication issues.
If clients fail to protect content with DKE labels and there’s no activity in the web server logs, likely there’s a misconfiguration or a connectivity issue.

 

T4: Event logs

Check the event logs for any exception messages.
If you installed the DKE service on IIS, you’ll find the event log in «Windows Event Viewer», «Application log».
If you’re hosting the DKE service on an Azure web app, you’ll find the event log as follows:

1. Go to your App Service
2. Open left-hand menu, "Diagnose and solve problems"
3. Select «Diagnostic Tools» (in the main pane)
4. Open «Support Tools/Application Event Logs» on the left-hand menu of the new screen

 

Part C: Step by Step guide

In order to narrow down which piece is missing, we suggest to perform the troubleshooting in the following order:

1. Check the web site with the validation script.
2. Try to save a document protected with a DKE label.
3. Have another user open a DKE protected document.
4. Let a user re-label a DKE protected document by right-clicking the document and selecting «classify and protect».

Some resolution steps refer to checklist items and tools. The reference uses codes that are prepended to the titles of the checklist items (e.g. «CL1») and tools (e.g. «T4»).

 

Step 1: Check the web site with the validation script

We suggest to run the validation script:

[…]\DoubleKeyEncryptionService\src\customer-key-store\scripts> .\key_store_tester.ps1 <DKE URL>/<Key>

If this is successful, please proceed with step 2.

However you may see the following output:

Validation request started: <DKE URL>/<Key>
Validation failure: Unable to access the provided url Not Found

Similarly, a 404 error is issued when you open the URL in a web browser.
This indicates one of the following issues:

 

Step 2: Try to save a document protected with a DKE label

(Ensure the DKE label has defined «Allow offline access:» as «Always».)
Saving the document successfully shows the client can reach the DKE service anonymously and the service provides a suitable RSA key. In this case, please proceed with step 3.
But you might encounter this behavior:
Despite having ample space on a disk (or on OneDrive), the following message is shown when saving a DKE protected document: «Word cannot save or create this file. Make sure the disk you want to save the file on it is not full, write-protected, or damaged.»
This indicates one of the following issues:

 

Step 3: Have another user open a DKE protected document

If user1 protects a document with DKE and user2 succeeds in opening this document, users can be authenticated to DKE. In this case you may proceed with step 4.
But a user trying to open a DKE document not protected by herself may see the following error message:
«You are not signed in to Office with an account that has permission to open this document. You may sign in a new account into Office that has permission or request permission from the content owner.»
This indicates one of the following issues:

 

Step 4: Let a user re-label her own DKE protected document with right-click, «classify and protect»

(For this test, the user has protected the document herself in Office.)
If the user succeeds in re-labeling this protected document with right-click, the AIP client is also registered with the web application and an Office version supporting DKE is installed.
However, the user may see the following error message in the AIP client:
«An unknown error occurred. If this problem persists, contact your administrator or help desk.»
This indicates one of the following issues: