Pass runtime data downstream in a JWT
The following sections describe how to pass identity or other runtime information in a JWT, downstream to a protected application:
The examples in this section use the following objects:
- 
JwtBuilderFilter to collect runtime information and pack it into a JWT
 - 
HeaderFilter to add the information to the forwarded request
 
To help with development, the sample application includes a /jwt endpoint to
display the JWT, verify its signature, and decrypt the JWT.
Pass runtime data in a JWT signed with a PEM
- 
Set up secrets
- 
Locate a directory for secrets, and go to it:
$ cd /path/to/secrets - 
Generate PEM files to sign and verify the JWT:
$ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout id.key.for.signing.jwt.pem \ -out id.key.for.verifying.jwt.pem 
 - 
 - 
Set up AM:
- 
(From AM 6.5.3) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:
- 
http://ig.example.com:8080/* - 
http://ig.example.com:8080/*?* 
 - 
 - 
Select Applications > Agents > Identity Gateway, and add an agent with the following values:
- 
Agent ID:
ig_agent - 
Password:
passwordFor AM 6.5.x and earlier versions, set up an agent as described in Set up an IG agent in AM 6.5 and earlier.
 
 - 
 
 - 
 - 
Set up IG:
- 
Set an environment variable for the IG agent password, and then restart IG:
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.
 - 
Add the following route to IG, to serve .css and other static resources for the sample application:
- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/static-resources.json
%appdata%\OpenIG\config\routes\static-resources.json
{ "name" : "sampleapp-resources", "baseURI" : "http://app.example.com:8081", "condition": "${find(request.uri.path,'^/css')}", "handler": "ReverseProxyHandler" } - 
 - 
Add the following route to IG, replacing value of the property
secretsDirwith the directory for the PEM file:- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/jwt-builder-sign-pem.json
%appdata%\OpenIG\config\routes\jwt-builder-sign-pem.json
{ "name": "jwt-builder-sign-pem", "condition": "${find(request.uri.path, '/jwt-builder-sign-pem')}", "baseURI": "http://app.example.com:8081", "properties": { "secretsDir": "/path/to/secrets" }, "capture": "all", "heap": [ { "name": "pemPropertyFormat", "type": "PemPropertyFormat" }, { "name": "FileSystemSecretStore-1", "type": "FileSystemSecretStore", "config": { "format": "PLAIN", "directory": "&{secretsDir}", "suffix": ".pem", "mappings": [{ "secretId": "id.key.for.signing.jwt", "format": "pemPropertyFormat" }] } }, { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam", "version": "7.2" } } ], "handler": { "type": "Chain", "config": { "filters": [{ "name": "SingleSignOnFilter", "type": "SingleSignOnFilter", "config": { "amService": "AmService-1" } }, { "name": "UserProfileFilter", "type": "UserProfileFilter", "config": { "username": "${contexts.ssoToken.info.uid}", "userProfileService": { "type": "UserProfileService", "config": { "amService": "AmService-1" } } } }, { "name": "JwtBuilderFilter-1", "type": "JwtBuilderFilter", "config": { "template": { "name": "${contexts.userProfile.commonName}", "email": "${contexts.userProfile.rawInfo.mail[0]}" }, "secretsProvider": "FileSystemSecretStore-1", "signature": { "secretId": "id.key.for.signing.jwt", "algorithm": "RS512" } } }, { "name": "HeaderFilter-1", "type": "HeaderFilter", "config": { "messageType": "REQUEST", "add": { "x-openig-user": ["${contexts.jwtBuilder.value}"] } } }], "handler": "ReverseProxyHandler" } } }Notice the following features of the route:
- 
The route matches requests to
/jwt-builder-sign-pem. - 
The agent password for AmService is provided by a SystemAndEnvSecretStore.
 - 
If the request does not have a valid AM session cookie, the SingleSignOnFilter redirects the request to authenticate with AM. If the request already has a valid AM session cookie, the SingleSignOnFilter passes the request to the next filter, and stores the cookie value in an SsoTokenContext.
 - 
The UserProfileFilter reads the username from the SsoTokenContext, uses it to retrieve the user’s profile info from AM, and places the data into the UserProfileContext.
 - 
The JwtBuilderFilter refers to the secret ID of the PEM, and uses the FileSystemSecretStore to manage the secret.
 - 
The FileSystemSecretStore mapping refers to the secret ID of the PEM, and uses the PemPropertyFormat to define the format.
 - 
The HeaderFilter retrieves the JWT from the JwtBuilderContext, and adds it to the header field
x-openig-userin the request, so that the sample app can display the JWT. - 
The ClientHandler passes the request to the sample app, which displays the JWT.
 
 - 
 
 - 
 - 
Test the setup
- 
If you are logged in to AM, log out and clear any cookies.
 - 
Log in to AM as user
demo, passwordCh4ng31t, or as another user. The sample app displays the signed JWT along with its header and payload. - 
In
USE PEM FILEin the sample app, enter the path toid.key.for.verifying.jwt.pemto verify the JWT signature. 
 - 
 
Pass runtime data in a JWT signed with PEM then encrypted with a symmetric key
This example passes runtime data in a JWT that is signed with a PEM, and then encrypted with a symmetric key.
- 
Set up secrets
- 
Locate a directory for secrets, and go to it:
$ cd /path/to/secrets - 
From the secrets directory, generate PEM files to sign and verify the JWT:
$ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout id.key.for.signing.jwt.pem \ -out id.key.for.verifying.jwt.pem - 
Encrypt the PEM file used to sign the JWT:
$ openssl pkcs8 \ -topk8 \ -inform PEM \ -outform PEM \ -in id.key.for.signing.jwt.pem \ -out id.encrypted.key.for.signing.jwt.pem \ -passout pass:encryptedpassword \ -v1 PBE-SHA1-3DESThe encrypted PEM file used for signatures is
id.encrypted.key.for.signing.jwt.pem. The password to decode the file isencryptedpassword.If encryption fails, make sure that your encryption methods and ciphers are supported by the Java Cryptography Extension.  - 
Generate a symmetric key to encrypt the JWT:
$ openssl rand -base64 32 > symmetric.key.for.encrypting.jwt - 
Make sure that you have the following keys in your secrets directory:
- 
id.encrypted.key.for.signing.jwt.pem - 
id.key.for.signing.jwt.pem - 
id.key.for.verifying.jwt.pem - 
symmetric.key.for.encrypting.jwt 
 - 
 
 - 
 - 
Set up AM:
- 
(From AM 6.5.3) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:
- 
http://ig.example.com:8080/* - 
http://ig.example.com:8080/*?* 
 - 
 - 
Select Applications > Agents > Identity Gateway, and add an agent with the following values:
- 
Agent ID:
ig_agent - 
Password:
passwordFor AM 6.5.x and earlier versions, set up an agent as described in Set up an IG agent in AM 6.5 and earlier.
 
 - 
 
 - 
 - 
Set up IG:
- 
In IG, create an environment variable for the base64-encoded password to decrypt the PEM file used to sign the JWT:
$ export ID_DECRYPTED_KEY_FOR_SIGNING_JWT='ZW5jcnlwdGVkcGFzc3dvcmQ=' - 
Set an environment variable for the IG agent password, and then restart IG:
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.
 - 
Add the following route to IG, to serve .css and other static resources for the sample application:
- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/static-resources.json
%appdata%\OpenIG\config\routes\static-resources.json
{ "name" : "sampleapp-resources", "baseURI" : "http://app.example.com:8081", "condition": "${find(request.uri.path,'^/css')}", "handler": "ReverseProxyHandler" } - 
 - 
Add the following route to IG, replacing the value of
secretsDirwith your secrets directory:- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/jwtbuilder-sign-then-encrypt.json
%appdata%\OpenIG\config\routes\jwtbuilder-sign-then-encrypt.json
{ "name": "jwtbuilder-sign-then-encrypt", "condition": "${find(request.uri.path, '/jwtbuilder-sign-then-encrypt')}", "baseURI": "http://app.example.com:8081", "properties": { "secretsDir": "/path/to/secrets" }, "capture": "all", "heap": [ { "name": "SystemAndEnvSecretStore", "type": "SystemAndEnvSecretStore", "config": { "mappings": [{ "secretId": "id.decrypted.key.for.signing.jwt", "format": "BASE64" }] } }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore", "url": "http://am.example.com:8088/openam", "version": "7.2" } }, { "name": "pemPropertyFormat", "type": "PemPropertyFormat", "config": { "decryptionSecretId": "id.decrypted.key.for.signing.jwt", "secretsProvider": "SystemAndEnvSecretStore" } }, { "name": "FileSystemSecretStore-1", "type": "FileSystemSecretStore", "config": { "format": "PLAIN", "directory": "&{secretsDir}", "mappings": [{ "secretId": "id.encrypted.key.for.signing.jwt.pem", "format": "pemPropertyFormat" }, { "secretId": "symmetric.key.for.encrypting.jwt", "format": { "type": "SecretKeyPropertyFormat", "config": { "format": "BASE64", "algorithm": "AES" } } }] } } ], "handler": { "type": "Chain", "config": { "filters": [{ "name": "SingleSignOnFilter", "type": "SingleSignOnFilter", "config": { "amService": "AmService-1" } }, { "name": "UserProfileFilter", "type": "UserProfileFilter", "config": { "username": "${contexts.ssoToken.info.uid}", "userProfileService": { "type": "UserProfileService", "config": { "amService": "AmService-1" } } } }, { "name": "JwtBuilderFilter-1", "type": "JwtBuilderFilter", "config": { "template": { "name": "${contexts.userProfile.commonName}", "email": "${contexts.userProfile.rawInfo.mail[0]}" }, "secretsProvider": "FileSystemSecretStore-1", "signature": { "secretId": "id.encrypted.key.for.signing.jwt.pem", "algorithm": "RS512", "encryption": { "secretId": "symmetric.key.for.encrypting.jwt", "algorithm": "dir", "method": "A128CBC-HS256" } } } }, { "name": "AddBuiltJwtToHeader", "type": "HeaderFilter", "config": { "messageType": "REQUEST", "add": { "x-openig-user": ["${contexts.jwtBuilder.value}"] } } }, { "name": "AddBuiltJwtAsCookie", "type": "HeaderFilter", "config": { "messageType": "RESPONSE", "add": { "set-cookie": ["my-jwt=${contexts.jwtBuilder.value};PATH=/"] } } }], "handler": "ReverseProxyHandler" } } }Notice the following features of the route:
- 
The route matches requests to
/jwtbuilder-sign-then-encrypt. - 
The SystemAndEnvSecretStore provides the IG agent password and the password to decode the PEM file for the signing keys.
 - 
The FileSystemSecretStore maps the secret IDs of the encrypted PEM file used to sign the JWT, and the symmetric key used to encrypt the JWT.
 - 
After authentication, the UserProfileFilter reads the username from the SsoTokenContext, uses it to retrieve the user’s profile info from AM, and places the data into the UserProfileContext.
 - 
The JwtBuilderFilter takes the username and email from the UserProfileContext, and stores them in a JWT in the JwtBuilderContext. It uses the secrets mapped in the FileSystemSecretStore to sign then encrypt the JWT.
 - 
The
AddBuiltJwtToHeaderHeaderFilter retrieves the JWT from the JwtBuilderContext, and adds it to the header fieldx-openig-userin the request so that the sample app can display the JWT. - 
The
AddBuiltJwtAsCookieHeaderFilter adds the JWT to a cookie calledmy-jwtso that it can be retrieved by the JwtValidationFilter in Validate JWTs. The cookie is ignored in this example. - 
The ClientHandler passes the request to the sample app.
 
 - 
 
 - 
 - 
Test the setup
- 
If you are logged in to AM, log out and clear any cookies.
 - 
Go to http://ig.example.com:8080/jwtbuilder-sign-then-encrypt.
 - 
Log in to AM as user
demo, passwordCh4ng31t. The sample app displays the encrypted JWT. The payload is concealed because the JWT is encrypted. - 
In the
ENTER SECRETbox, enter the value ofsymmetric.key.for.encrypting.jwtto decrypt the JWT. The signed JWT and its payload are now displayed. - 
In the
USE PEM FILEbox, enter the path toid.key.for.verifying.jwt.pemto verify the JWT signature. 
 - 
 
Pass runtime data in JWT encrypted with a symmetric key
- 
Set up secrets:
- 
Locate a directory for secrets, and go to it:
$ cd /path/to/secrets - 
In the secrets folder, generate an AES 256-bit key:
$ openssl rand -base64 32 loH...UFQ= - 
In the secrets folder, create a file called
symmetric.key.for.encrypting.jwtcontaining the AES key:$ echo -n 'loH...UFQ=' > symmetric.key.for.encrypting.jwtMake sure that the password file contains only the password, with no trailing spaces or carriage returns.
 
 - 
 - 
Set up AM:
- 
(From AM 6.5.3) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:
- 
http://ig.example.com:8080/* - 
http://ig.example.com:8080/*?* 
 - 
 - 
Select Applications > Agents > Identity Gateway, and add an agent with the following values:
- 
Agent ID:
ig_agent - 
Password:
passwordFor AM 6.5.x and earlier versions, set up an agent as described in Set up an IG agent in AM 6.5 and earlier.
 
 - 
 
 - 
 - 
Set up IG:
- 
Set an environment variable for the IG agent password, and then restart IG:
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.
 - 
Add the following route to IG, to serve .css and other static resources for the sample application:
- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/static-resources.json
%appdata%\OpenIG\config\routes\static-resources.json
{ "name" : "sampleapp-resources", "baseURI" : "http://app.example.com:8081", "condition": "${find(request.uri.path,'^/css')}", "handler": "ReverseProxyHandler" } - 
 - 
Add the following route to IG, replacing the value of the property
secretsDirwith your value:- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/jwtbuilder-encrypt-symmetric.json
%appdata%\OpenIG\config\routes\jwtbuilder-encrypt-symmetric.json
{ "name": "jwtbuilder-encrypt-symmetric", "condition": "${find(request.uri.path, '/jwtbuilder-encrypt-symmetric')}", "baseURI": "http://app.example.com:8081", "properties": { "secretsDir": "/path/to/secrets" }, "heap": [ { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam", "version": "7.2" } }, { "name": "FileSystemSecretStore-1", "type": "FileSystemSecretStore", "config": { "format": "PLAIN", "directory": "&{secretsDir}", "mappings": [{ "secretId": "symmetric.key.for.encrypting.jwt", "format": { "type": "SecretKeyPropertyFormat", "config": { "format": "BASE64", "algorithm": "AES" } } }] } } ], "handler": { "type": "Chain", "config": { "filters": [{ "name": "SingleSignOnFilter-1", "type": "SingleSignOnFilter", "config": { "amService": "AmService-1" } }, { "name": "UserProfileFilter-1", "type": "UserProfileFilter", "config": { "username": "${contexts.ssoToken.info.uid}", "userProfileService": { "type": "UserProfileService", "config": { "amService": "AmService-1" } } } }, { "name": "JwtBuilderFilter-1", "type": "JwtBuilderFilter", "config": { "template": { "name": "${contexts.userProfile.commonName}", "email": "${contexts.userProfile.rawInfo.mail[0]}" }, "secretsProvider": "FileSystemSecretStore-1", "encryption": { "secretId": "symmetric.key.for.encrypting.jwt", "algorithm": "dir", "method": "A128CBC-HS256" } } }, { "name": "HeaderFilter-1", "type": "HeaderFilter", "config": { "messageType": "REQUEST", "add": { "x-openig-user": ["${contexts.jwtBuilder.value}"] } } }], "handler": "ReverseProxyHandler" } } }Notice the following features of the route:
- 
The route matches requests to
/jwtbuilder-encrypt-symmetric. - 
The JWT encryption key is managed by the FileSystemSecretStore in the heap, which defines the SecretKeyPropertyFormat.
 - 
The JwtBuilderFilter
encryptionproperty refers to key in the FileSystemSecretStore. - 
The HeaderFilter retrieves the JWT from the JwtBuilderContext, and adds it to the header field
x-openig-userin the request, so that the sample app can display the JWT. 
 - 
 
 - 
 - 
Test the setup:
- 
If you are logged in to AM, log out and clear any cookies.
 - 
Go to http://ig.example.com:8080/jwtbuilder-encrypt-symmetric.
 - 
Log in to AM as user
demo, passwordCh4ng31t, or as another user. The JWT is displayed in the sample app. - 
In the
ENTER SECRETfield, enter the value of the AES 256-bit key to decrypt the JWT and display its payload. 
 - 
 
Pass runtime data in JWT encrypted with an asymmetric key
The asymmetric key in this example is a PEM, but you can equally use a keystore.
- 
Set up secrets:
- 
Locate a directory for secrets, and go to it:
$ cd /path/to/secrets - 
Generate an encrypted PEM file:
$ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout id.key.for.encrypting.jwt.pem \ -out id.key.for.decrypting.jwt.pem 
 - 
 - 
Set up AM:
- 
(From AM 6.5.3) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:
- 
http://ig.example.com:8080/* - 
http://ig.example.com:8080/*?* 
 - 
 - 
Select Applications > Agents > Identity Gateway, and add an agent with the following values:
- 
Agent ID:
ig_agent - 
Password:
passwordFor AM 6.5.x and earlier versions, set up an agent as described in Set up an IG agent in AM 6.5 and earlier.
 
 - 
 
 - 
 - 
Set up IG:
- 
Set an environment variable for the IG agent password, and then restart IG:
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.
 - 
Add the following route to IG, to serve .css and other static resources for the sample application:
- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/static-resources.json
%appdata%\OpenIG\config\routes\static-resources.json
{ "name" : "sampleapp-resources", "baseURI" : "http://app.example.com:8081", "condition": "${find(request.uri.path,'^/css')}", "handler": "ReverseProxyHandler" } - 
 - 
Add the following route to IG, replacing value of the property
secretsDirwith the directory for the PEM file:- 
Linux
 - 
Windows
 
$HOME/.openig/config/routes/jwtbuilder-encrypt-asymmetric.json
%appdata%\OpenIG\config\routes\jwtbuilder-encrypt-asymmetric.json
{ "name": "jwtbuilder-encrypt-asymmetric", "condition": "${find(request.uri.path, '/jwtbuilder-encrypt-asymmetric')}", "baseURI": "http://app.example.com:8081", "properties": { "secretsDir": "/path/to/secrets" }, "capture": "all", "heap": [ { "name": "pemPropertyFormat", "type": "PemPropertyFormat" }, { "name": "FileSystemSecretStore-1", "type": "FileSystemSecretStore", "config": { "format": "PLAIN", "directory": "&{secretsDir}", "suffix": ".pem", "mappings": [{ "secretId": "id.key.for.decrypting.jwt", "format": "pemPropertyFormat" }] } }, { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam", "version": "7.2" } } ], "handler": { "type": "Chain", "config": { "filters": [{ "name": "SingleSignOnFilter", "type": "SingleSignOnFilter", "config": { "amService": "AmService-1" } }, { "name": "UserProfileFilter", "type": "UserProfileFilter", "config": { "username": "${contexts.ssoToken.info.uid}", "userProfileService": { "type": "UserProfileService", "config": { "amService": "AmService-1" } } } }, { "name": "JwtBuilderFilter-1", "type": "JwtBuilderFilter", "config": { "template": { "name": "${contexts.userProfile.commonName}", "email": "${contexts.userProfile.rawInfo.mail[0]}" }, "secretsProvider": "FileSystemSecretStore-1", "encryption": { "secretId": "id.key.for.decrypting.jwt", "algorithm": "RSA-OAEP-256", "method": "A128CBC-HS256" } } }, { "name": "HeaderFilter-1", "type": "HeaderFilter", "config": { "messageType": "REQUEST", "add": { "x-openig-user": ["${contexts.jwtBuilder.value}"] } } }], "handler": "ReverseProxyHandler" } } }Notice the following features of the route:
- 
The route matches requests to
/jwtbuilder-encrypt-asymmetric. - 
The JwtBuilderFilter refers to the secret ID of the PEM, and uses the FileSystemSecretStore to manage the secret.
 - 
The FileSystemSecretStore mapping refers to the secret ID of the PEM, and uses the default PemPropertyFormat.
 - 
The HeaderFilter retrieves the JWT from the JwtBuilderContext, and adds it to the header field
x-openig-userin the request, so that the sample app can display the JWT. 
 - 
 
 - 
 - 
Test the setup:
- 
If you are logged in to AM, log out and clear any cookies.
 - 
Go to http://ig.example.com:8080/jwtbuilder-encrypt-asymmetric.
 - 
Log in to AM as user
demo, passwordCh4ng31t, or as another user. The JWT is displayed in the sample app. - 
In the
USE PEM FILEfield, enter the path toid.key.for.encrypting.jwt.pemto decrypt the JWT and display its payload. 
 -