SAML token encryption - Microsoft Entra ID (2024)

SAML token encryption enables the use of encrypted SAML assertions with an application that supports it. When configured for an application, Microsoft Entra ID will encrypt the SAML assertions it emits for that application using the public key obtained from a certificate stored in Microsoft Entra ID. The application must use the matching private key to decrypt the token before it can be used as evidence of authentication for the signed in user.

Encrypting the SAML assertions between Microsoft Entra ID and the application provides additional assurance that the content of the token can't be intercepted, and personal or corporate data compromised.

Even without token encryption, Microsoft Entra SAML tokens are never passed on the network in the clear. Microsoft Entra ID requires token request/response exchanges to take place over encrypted HTTPS/TLS channels so that communications between the IDP, browser, and application take place over encrypted links. Consider the value of token encryption for your situation compared with the overhead of managing more certificates.

To configure token encryption, you need to upload an X.509 certificate file that contains the public key to the Microsoft Entra application object that represents the application. To obtain the X.509 certificate, you can download it from the application itself, or get it from the application vendor in cases where the application vendor provides encryption keys or in cases where the application expects you to provide a private key, it can be created using cryptography tools, the private key portion uploaded to the application’s key store and the matching public key certificate uploaded to Microsoft Entra ID.

Microsoft Entra ID uses AES-256 to encrypt the SAML assertion data.

Prerequisites

To configure SAML token encryption, you need:

• A Microsoft Entra user account. If you don't already have one, you can Create an account for free.
• One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

Configure enterprise application SAML token encryption

This section describes how to configure enterprise application's SAML token encryption. Applications that have been set up from the Enterprise applications blade in the Microsoft Entra admin center, either from the Application Gallery or a Non-Gallery app. For applications registered through the App registrations experience, follow the Configure registered application SAML token encryption guidance.

To configure enterprise application's SAML token encryption, follow these steps:

1. Obtain a public key certificate that matches a private key that's configured in the application.

   Create an asymmetric key pair to use for encryption. Or, if the application supplies a public key to use for encryption, follow the application's instructions to download the X.509 certificate.

   The public key should be stored in an X.509 certificate file in .cer format. You can copy the contents of the certificate file to a text editor and save it as a .cer file. The certificate file should contain only the public key and not the private key.

   If the application uses a key that you create for your instance, follow the instructions provided by your application for installing the private key that the application will use to decrypt tokens from your Microsoft Entra tenant.

2. Add the certificate to the application configuration in Microsoft Entra ID.

Configure token encryption in the Microsoft Entra admin center

You can add the public cert to your application configuration within the Microsoft Entra admin center.

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.

2. Browse to Identity > Applications > Enterprise applications > All applications.

   See Also

   Enable single sign-on for an enterprise application - Microsoft Entra ID

3. Enter the name of the existing application in the search box, and then select the application from the search results.

4. On the application's page, select Token encryption.

   

   Note

   The Token encryption option is only available for SAML applications that have been set up from the Enterprise applications blade in the Microsoft Entra admin center, either from the Application Gallery or a Non-Gallery app. For other applications, this menu option is disabled.

5. On the Token encryption page, select Import Certificate to import the .cer file that contains your public X.509 certificate.

   

6. Once the certificate is imported, and the private key is configured for use on the application side, activate encryption by selecting the ... next to the thumbprint status, and then select Activate token encryption from the options in the dropdown menu.

7. Select Yes to confirm activation of the token encryption certificate.

8. Confirm that the SAML assertions emitted for the application are encrypted.

To deactivate token encryption in the Microsoft Entra admin center

1. In the Microsoft Entra admin center, go to Identity > Applications > Enterprise applications > All applications, and then select the application that has SAML token encryption enabled.

2. On the application's page, select Token encryption, find the certificate, and then select the ... option to show the dropdown menu.

3. Select Deactivate token encryption.

Configure registered application SAML token encryption

This section describes how to configure registered application's SAML token encryption. Applications that have been set up from the App registrations blade in the Microsoft Entra admin center. For enterprise application, follow the Configure enterprise application SAML token encryption guidance.

Encryption certificates are stored on the application object in Microsoft Entra ID with an encrypt usage tag. You can configure multiple encryption certificates and the one that's active for encrypting tokens is identified by the tokenEncryptionKeyID attribute.

You'll need the application's object ID to configure token encryption using Microsoft Graph API or PowerShell. You can find this value programmatically, or by going to the application's Properties page in the Microsoft Entra admin center and noting the Object ID value.

When you configure a keyCredential using Graph, PowerShell, or in the application manifest, you should generate a GUID to use for the keyId.

To configure token encryption for an application registration, follow these steps:

Next steps

• Find out How Microsoft Entra ID uses the SAML protocol
• Learn the format, security characteristics, and contents of SAML tokens in Microsoft Entra ID