AzureAD / azure-activedirectory-powershell-tokenkey

Scripts to override the Azure Active Directory token signing key.

Azure Active Directory Token Signing Key Scripts

This repository contains PowerShell scripts that developers and administrators can use to:

• Test their Azure Active Directory integrated applications for automatic token signing key rollover.
• Establish a manual signing key rollover process for their Azure Active Directory integrated applications that do not support automatic token signing key rollover.

For more information about signing key rollover, check out the Signing key rollover in Azure Active Directory documentation.

Impact

These scripts set the preferred token signing key on a specific application. As a result, any user that signs in to the application after the script is run will receive tokens signed with the preferred key.

Pre-Requisites

These scripts can only be run by an Azure Active Directory Global Administrator.

If the application does not support automatic rollover, changing the token signing key will result in downtime. Therefore, it is strongly recommended that these scripts are only run either

• on a test application for which downtime is acceptable; or,
• on a production application during downtime window.

Steps To Setup The Scripts

1. Download and extract the scripts.

2. Start Windows PowerShell.

3. Navigate to the folder where the scripts were extracted.

4. Run the following to install the AADGraph module (and ADAL):

   .\install-aadGraphModule.ps1

Steps To Test For Automatic Rollover

1. Get the list of available signing keys:

   .\Get-AADSigningKey.ps1 | Format-Table

2. Pick any of the keys and configure Azure Active Directory to use that key with your application:

   .\Set-AADSigningKey.ps1 -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>

3. Test the web application. The change is instantaneous, but make sure you use a new browser session (e.g. IE's "InPrivate", Chrome "Incognito", or Firefox's "Private") to ensure you are issued a new token.

4. Repeat steps 2 through 3 with all the keys returned from step 1.

5. If the web application signs you in properly, it supports automatic rollover. If it does not:

• Modify your application to support automatic rollover. Check out Signing key rollover in Azure Active Directory documentation for more information.
• Establishing a manual rollover process.

6. Execute the following script to revert to normal behavior:

   .\Set-AADSigningKey.ps1 -ApplicationId <ApplicationId> -Default

Steps To Perform Manual Rollover

1. Get the latest signing key:

   .\Get-AADSigningKey.ps1 -Latest

2. Compare this key against the key your application is currently hardcoded or configured to use.

3. If the latest key is different from the key your application is using, download the latest signing key:

   ..\Get-AADSigningKey.ps1 -Latest -DownloadPath <DownloadPath>

4. Update your application's code or configuration to the new key.

5. Configure Azure Active Directory to use that latest key with your application:

   .\Set-AADSigningKey.ps1 -ApplicationId <ApplicationId> -Latest

6. Test the web application. The change is instantaneous, but make sure you use a new browser session (e.g. IE's "InPrivate", Chrome "Incognito", or Firefox's "Private") to ensure you are issued a new token.

7. If you experience any issues, revert to the previous key you were using and contact Azure support:

   .\Set-AADSigningKey.ps1 -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>

8. Once you update your application as per our guidance in Signing key rollover in Azure Active Directory documentation to support for automatic rollover, revert to normal behavior:

   .\Set-AADSigningKey.ps1 -ApplicationId <ApplicationId> -Default

Security Reporting

If you find a security issue with our libraries or services please report it to [e-mail] with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.

We Value and Adhere to the Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.