Token encryption is a Microsoft Entra ID P1 or P2 feature. To learn more about Microsoft Entra editions, features, and pricing, see Microsoft Entra pricing.
SAML token encryption enables the use of encrypted SAML assertions with an application that supports it. When configured for an application, Microsoft Entra ID encrypts the SAML assertions it emits for that application. It encrypts the SAML assertions 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 more 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. You can also get it from the application vendor in cases where the application vendor provides encryption keys. If the application expects you to provide a private key, you can create it using cryptography tools. The private key portion is 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.
This section describes how to configure an enterprise application's SAML token encryption. These applications are set up from the Enterprise applications pane 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:
Obtain a public key certificate that matches a private key 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 created for your instance, follow the instructions provided by your application for installing the private key that the application is to use to decrypt tokens from your Microsoft Entra tenant.
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.
Browse to Identity > Applications > Enterprise applications > All applications.
Enter the name of the existing application in the search box, and then select the application from the search results.
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 pane in the Microsoft Entra admin center, either from the application gallery or a non-gallery app. For other applications, this option is disabled.
On the Token encryption page, select Import Certificate to import the .cer file that contains your public X.509 certificate.
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.
Select Yes to confirm activation of the token encryption certificate.
Confirm that the SAML assertions emitted for the application are encrypted.
To deactivate token encryption in the Microsoft Entra admin center
In the Microsoft Entra admin center, browse to Identity > Applications > Enterprise applications > All applications, and then select the application that has SAML token encryption enabled.
On the application's page, select Token encryption, find the certificate, and then select the ... option to show the dropdown menu.
This section describes how to configure a registered application's SAML token encryption. These applications are set up from the App registrations pane 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 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:
The following example shows an application manifest configured with two encryption certificates, and with the second selected as the active one using the tokenEncryptionKeyId.
Update the application's keyCredentials with an X.509 certificate for encryption. The following example shows a Microsoft Graph JSON payload with a collection of key credentials associated with the application.
PATCH https://graph.microsoft.com/beta/applications/<application objectid>
{
"keyCredentials":[
{
"type":"AsymmetricX509Cert","usage":"Encrypt",
"keyId":"aaaaaaaa-0b0b-1c1c-2d2d-333333333333", (Use a GUID generator to obtain a value for the keyId)
"key": "MIICADCCAW2gAwIBAgIQ5j9/b+n2Q4pDvQUCcy3…" (Base64Encoded .cer file)
}
]
}
Identify the encryption certificate that's active for encrypting tokens. The following example shows a Microsoft Graph JSON payload with the tokenEncryptionKeyId element. The tokenEncryptionKeyId element specifies the key ID of a public key from the keyCredentials collection.
PATCH https://graph.microsoft.com/beta/applications/<application objectid>
{
"tokenEncryptionKeyId":"aaaaaaaa-0b0b-1c1c-2d2d-333333333333" (The keyId of the keyCredentials entry to use)
}
This module focuses on effectively managing identities and enhancing security in Microsoft Enterprise Identity, ensuring that users, groups, and external identities are protected against security threats and unauthorized access.