Encrypt and decrypt ID tokens¶

Asgardeo can encrypt ID tokens to enhance security during transmission. This ensures that only the intended recipient, who possesses the corresponding private key, can decrypt and read the token's contents. This guide explains how you can configure Asgardeo to encrypt ID tokens and how your applications can decrypt them.

How it works¶

Asgardeo uses JSON Web Encryption (JWE) standards to encrypt ID tokens. The ID token will be encrypted using the registered public key of the application. The application can then use its private key to decrypt the token and access the claims within.

Before you begin

Register an application by following the instructions in the relevant guide based on your application type:

Enable encryption¶

The following steps ensures that Asgardeo encrypts the ID token issued to your application.

On the Asgardeo Console, go to Applications and select your application.
In the Protocol tab of the application, make the following changes:
1. under Certificate, provide the public key of the application. You can do so in either of the following ways:
  - upload the public certificate of the application. If you don't have one, create a self-signed certificate by following the instructions in the create a self-signed certificate section below.
  - provide the JWKS URI of the application. Learn more about JWKS.
2. Under ID Token, select the Enable ID Token Encryption checkbox and configure the following parameters:
  - Algorithm: Asymmetric encryption method used to encrypt the Content Encryption Key (CEK), using the public key of the application.
  - Encryption method: Symmetric encryption algorithm used to encrypt the JWT claims set using the CEK.
    
    Note
    
    Learn more about the supported encryption algorithms and methods.
Click Update to save the changes.

(Optional) Create a self-signed certificate¶

You can create a self-signed certificate by following the steps below. You can skip this section if you already have a public certificate.

Create a new keystore.

keytool -genkey -alias wso2carbon -keyalg RSA -keysize 2048 -keystore testkeystore.jks -dname "CN=*.test.com,OU=test,O=test,L=MPL,ST=MPL,C=FR" -storepass wso2carbon -keypass wso2carbon -validity 10950

Create a file and name it as the client ID of the OAuth application (You can get it from the Protocol section of the application). Export the public key of the new keystore to the file you created.
```
keytool -export -alias wso2carbon -file <client-id> -keystore testkeystore.jks
```
Get the cert in X509 format.
```
keytool -printcert -rfc -file <client-id>
```
You will see the public certificate in X509 format in the console.

Copy the content of the certificate. A sample output is shown below.

Paste the copied certificate into the Certificate field of the application in Asgardeo Console.

Decrypt the ID token¶

Follow the steps below to get an encrypted ID token and decrypt it.

Use one of the following guides and perform an OIDC authentication flow to receive an encrypted ID token:
- Implement authorization code flow
- Implement authorization code flow with PKCE

You can use one of the following methods to decrypt the ID token:

Note

Learn more about the format of encrypted ID tokens in the reference.

Use the private key - You can use the private key corresponding to the public key registered in Asgardeo to decrypt the ID token. If you created a self-signed certificate by following the steps in the previous section, use the steps below to get the private key from the keystore.
1. Import JKS into a PKCS12 formatted store.
```
keytool -importkeystore -srckeystore testkeystore.jks -destkeystore testkeystore.p12 -srcstoretype JKS -deststoretype  PKCS12 -srcstorepass wso2carbon -deststorepass wso2carbon -srcalias wso2carbon -destalias wso2carbon -srckeypass  wso2carbon -destkeypass wso2carbon
```
2. Extract the private key into a file named key.pem
```
openssl pkcs12 -in testkeystore.p12 -out key.pem -passin pass:wso2carbon -passout pass:wso2carbon -nodes -nocerts
```
  The extracted key.pem file contains the private key in PEM format, which you can use to decrypt the ID token manually or with a script.

Use a keystore with a third-party library - You can use libraries such as Nimbus JOSE + JWT to perform the decryption. The following sample Java code demonstrates how to decrypt an encrypted ID token using the testkeystore.jks created in the previous section.

package org.wso2.sample;
import com.nimbusds.jose.crypto.RSADecrypter;
import com.nimbusds.jwt.EncryptedJWT;
import java.io.InputStream;
import java.security.KeyStore;
import java.security.interfaces.RSAPrivateKey;
public class DecryptIDToken {

    public static void main(String[] args) throws Exception {

        // Get keystore as a resource.
        InputStream file = ClassLoader.getSystemResourceAsStream("testkeystore.jks");
        KeyStore keystore = KeyStore.getInstance(KeyStore.getDefaultType());
        keystore.load(file, "wso2carbon".toCharArray());
        String alias = "wso2carbon";

        // Get the private key. Password for the key store is 'wso2carbon'.
        RSAPrivateKey privateKey = (RSAPrivateKey) keystore.getKey(alias, "wso2carbon".toCharArray());

        // Enter encrypted JWT String here.
        String encryptedJWTString = "eyJ4NXQiOiJOVEF4Wm1NeE5ETXlaRGczTVRVMVpHTTBNekV6T0RKaFpXSTRORE5sWkRVMU9HRmtOakZp" +
                "TVEiLCJraWQiOiJOVEF4Wm1NeE5ETXlaRGczTVRVMVpHTTBNekV6T0RKaFpXSTRORE5sWkRVMU9HRmtOakZpTVEiLCJlbmMiOiJ" +
                "BMjU2R0NNIiwiYWxnIjoiUlNBMV81In0.Zwp2xDvYER9lAo43QrYrcaKz-tPLFPYZb2s4RontDDVyvdo-seYl6II2C1Wb4cQhXd" +
                "ipcB_Qj093xvLrJyZXWxeavqYhryeuHi2jgcs59MfV1U9hMaKqqjVN1pcZYSrxDzn5leBF5bw7_YKaD_R6cFY8VtpVv5j_U8Woh" +
                "tyIjM7_n2CsZ55vY8MUHCAYxzXK9_s75e6Ug8L4MEqpgeoJGQzYCxFrBFgGyDMv1jadLwNl4Y3yLhv4RLtQMU5AM6nODI601UfY" +
                "drapObF3mpl_74H_YdRqT28LepGMtkEXbjeRgB-FiFGLvYlrK4wygczLBKrcviVyzyhrIrqz3TYV3g.Lf5lECzAdyAGgP8t.SHB" +
                "UZoWkqwW_7u0GElrUqX1tewqRaUMWdGPHxpLRPmpVuc7FwQ27-kdsQ6O1_twhZ7uzjzZaEkatNhMxy9k10733-r4GT1lTGVqidK" +
                "iBZq3mRQu7qJpcz7JWUroNFRLxhSoqpLpC8_tAhkohzG-mE42xdEh4tNDy3pBtAG0fe42WrLtWTuyg5lpmOYSppOc2Gb6LcDr4M" +
                "mxFNPgoatF0edJSgO-CpFJQTcXn-22lU2g7o22x3RcBx9_KZH0At3g9y9uTuBncExOoBRK_ZweKOl0q76TaLiv5faXINW15xz9h" +
                "ILA.RGYIL7FaQqAIMPAiQdkOig";  

        EncryptedJWT jwt = EncryptedJWT.parse(encryptedJWTString);

        // Create a decrypter with the specified private RSA key.
        RSADecrypter decrypter = new RSADecrypter(privateKey);

        jwt.decrypt(decrypter);

        // Printing decrypted id token header.
        System.out.println("ID token header: " + jwt.getHeader().toJSONObject());  

        // Printing decrypted id token header.
        System.out.println("ID token claims: " + jwt.getJWTClaimsSet().toJSONObject());
    }
}

Learn more¶

To learn more about token ID encryption and supported algorithms and methods, see the ID token encryption reference.