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:
- Install and launch Fiddler, available on https://www.telerik.com/fiddler.
- Select «Tools\Options», switch to tab «HTTPS», check option «Decrypt HTTPS» traffic, click OK and acknowledge prompts for installing a root certificate.
- 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:
- Clients downloading the public key (when protecting content with DKE)
- 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:
- Go to your App Service
- Open left-hand menu, "Diagnose and solve problems"
- Select «Diagnostic Tools» (in the main pane)
- 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:
- Check the web site with the validation script.
- Try to save a document protected with a DKE label.
- Have another user open a DKE protected document.
- 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:
|
Potential issue |
Suggested resolution steps |
|
The URL is not correct. |
Double-check the URL, please observe that the key name in the URL is case sensitive. |
|
There’s an internal exception in the web site. |
Check the event log on the DKE service (see tool T4). |
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:
|
Potential issue |
Suggested resolution steps |
|
The client is not configured to use DKE. |
Re-check the Office version (see checklist item CL1). Verify the DKE registry keys have been imported on the client (see checklist item CL9). |
|
The client cannot reach the DKE service. |
On the client, try opening the DKE-URL configured in the sensitivity label. If that fails, fix the network issue as needed. |
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:
|
Potential issue |
Suggested resolution steps |
|
The user hasn’t been granted permission in the sensitivity label. |
During tests, try granting the whole tenant access in the sensitivity label permissions (see checklist item CL5). |
|
The DKE service URL contains a sub-folder. |
Verify that the DKE URL consists of the FQDN only (see checklist item CL2). |
|
The web application isn’t configured correctly. |
Check the settings in the web application (see checklist item CL6). |
|
The DKE service is hosted on IIS, but it cannot reach Azure AD due to lacking outbound Internet connectivity. |
Check for exception «System.InvalidOperationException: IDX20803: Unable to obtain configuration» in the event viewer (see tool T4). If this exception occurs, make sure the DKE service has outbound connectivity. |
|
The configuration file doesn’t grant permission for the tenant. |
Ensure «TrustedIssuers» contains the tenant specific URL (see checklist item CL10). |
|
DKE doesn’t authorize the user to access the service. |
Check the authorization option (see checklist item CL7). |
|
The host name in the "JwtAudience" doesn't exactly match the host name in the DKE URL (including case). |
Check the exact spelling of the host name, including case (see checklist item CL11). |
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:
|
Potential issue |
Suggested resolution steps |
|
The client doesn’t have the correct Office version installed. |
Re-check the Office version (see checklist item CL1). |
|
The AIP client is not registered in the web application. |
Check whether the client ID for the AIP client has also been registered in the web application (see checklist item CL6). |
Microsoft
