Pass End-User Attributes to Upstream Services¶

There are scenarios where a backend service needs to apply specific logic or make decisions depending on the user consuming an API. In such scenarios, you must pass end-user attributes to the backend during an API call.

Choreo provides a method to send user information to a backend service through a JSON Web Token (JWT) in an HTTP header of an API request.

How it works¶

The backend JWT contains claims transferred between the parties, such as the user and the backend. A claim can be metadata of the request or data about the user. A set of claims is called a dialect, for example, http://wso2.org/claims.

For each API request, a digitally signed JWT is carried to the backend service in the following format to ensure that the authenticity of the claims list is verified:

{token header}.{claims list}.{signature}

When a request goes through Choreo, the backend JWT is appended as the X-JWT-Assertion header in the outgoing message. The backend service fetches the JWT and retrieves the required information about the user, application, or token.

Claims¶

Claims are fragments of information included in the JWT.

The following is a sample claim set added to the end-user token for an access token generated via the authorization code:

Tip

This access token is generated via Asgardeo using the authorization code grant type. Here, the Asgardeo application is configured to include the email claim in the token.

{
  "sub": "11f53c32-f8ac-4810-bb79-615b2184baf5",
  "http://wso2.org/claims/apiname": "JWT Test - Endpoint 9090 803",
  "http://wso2.org/claims/applicationtier": "Unlimited",
  "http://wso2.org/claims/version": "1.0.0",
  "http://wso2.org/claims/keytype": "PRODUCTION",
  "iss": "wso2.org/products/am",
  "http://wso2.org/claims/applicationname": "jwtTest2",
  "http://wso2.org/claims/enduserTenantId": "0",
  "http://wso2.org/claims/applicationUUId": "45101ccb-865f-4f48-b7ac-18e43b07edd3",
  "client_id": "IMJB5ZiR1dHQYBdiMIRAGis1WToa",
  "http://wso2.org/claims/subscriber": "5f4a7105-a889-4f92-9612-eef5bafe4eec",
  "azp": "IMJB5ZiR1dHQYBdiMIRAGis1WToa",
  "org_id": "b554e001-761c-4d3a-a7a6-a61d73d34221",
  "http://wso2.org/claims/tier": "Unlimited",
  "scope": "email openid profile",
  "exp": 1690537362,
  "http://wso2.org/claims/applicationid": "45101ccb-865f-4f48-b7ac-18e43b07edd3",
  "http://wso2.org/claims/usertype": "Application_User",
  "org_name": "test",
  "iat": 1690533762,
  "email": "testmail@gmail.com",
  "jti": "69558555-d386-4a81-9ca0-0a23f809cd3c",
  "http://wso2.org/claims/apicontext": "/b554e001-761c-4d3a-a7a6-a61d73d34221/swog/jwt-test/endpoint-9090-803/1.0.0"
}

The following table describes the information contained in the sample JWT claims set given above:

Claim Name	Description	Mandatory/Optional
`iat`	The time the token was issued.	Mandatory
`jti`	The unique token identifier.	Mandatory
`exp`	The token expiry time.	Mandatory
`iss`	The issuer of the token.	Mandatory
`http://wso2.org/claims/apiname`	The name of the API in Choreo.	Optional
`http://wso2.org/claims/version`	The API version.	Optional
`http://wso2.org/claims/keytype`	The environment in Choreo that the API is in (`Development` or `production`).	Optional
`http://wso2.org/claims/apicontext`	The API context in Choreo.	Optional
`http://wso2.org/claims/subscriber`	The subscriber to the API, usually the app developer.	Optional
`http://wso2.org/claims/applicationname`	The application through which the API invocation is done.	Optional
`http://wso2.org/claims/applicationid`	The ID of the application through which the API invocation is done.	Optional
`http://wso2.org/claims/applicationUUId`	The UUID of the application.	Optional
`client_id`	The client identifier. This is copied from the original token.	Optional
`azp`	The authorized party (the party to which the ID token was issued). This is copied from the original token.	Optional
`org_id`	The organization ID. This is copied from the original token.	Optional
`org_name`	The organization name. This is copied from the original token.	Optional
`http://wso2.org/claims/tier`	The tier/price band for the subscription.	Optional
`scope`	The scope of the token. This is copied from the original token.	Optional
`http://wso2.org/claims/usertype`	The type of application user whose action invoked the API.	Optional
`email`	The email address of the user. This is copied from the original token.	Optional

Note

The claims that get added to the end-user token can vary depending on the grant type used when generating the access token. For example, if you use the client-credentials grant type to generate the access token, the generated backend JWT would contain the following information:

{ 
  "http://wso2.org/claims/apiname": "DefaultAPI", 
  "http://wso2.org/claims/version": "1.0.0", 
  "http://wso2.org/claims/keytype": "PRODUCTION", 
  "iss": "wso2.org/products/am", 
  "http://wso2.org/claims/enduserTenantId": "0", 
  "exp": 1673245727, 
  "http://wso2.org/claims/usertype": "Application_User", 
  "iat": 1673242127, 
  "jti": "6e3f4392-8bd9-4900-9d08-eaab7429c510", 
  "http://wso2.org/claims/apicontext": "/9e71ab5e-6df5-4727-92d2-80ecf1a6218d/qbky/default/1.0.0" 
}

To verify the authenticity of claims in a JWT, the claims must be validated using the public key corresponding to the private key used to sign the JWT.

JSON web key set (JWKS) is a set of keys to validate a JWT. It contains a collection of JSON web keys, which are public keys used to verify the signature of a JWT.

Typically, when a third party (such as an identity provider)issues a JWT and the recipient needs to verify its signature, they can use a JWKS. JWKS allows the issuer to rotate keys dynamically rather than hard-coding the public key in the application. The recipient can obtain the public key by accessing the JWKS endpoint.

JWKS support in Choreo to validate the JWT¶

Choreo provides an endpoint to specify the public keys for backend JWT validation. Here are the endpoint URLs for the US East and EU regions:

Note

For private data planes (PDPs), use the following JWKS endpoint URL template:

https://<PDP_GATEWAY_DOMAIN>/.wellknown/jwks

Be sure to replace <PDP-GATEWAY-DOMAIN> with the default domain configured to access the PDP APIs.

The endpoint provides one or more signing keys to validate the JWT. The JSON web keys have a kid identifier that can be matched with the same property on the JWT to decide which key to use when validating.

The following is a sample JWKS response:

{
   "keys": [
       {
           "kty": "RSA",
           "e": "AQAB",
           "use": "sig",
           "kid": "ZjcwNmI2ZDJmNWQ0M2I5YzZiYzJmZmM4YjMwMDFlOTA4MGE3ZWZjZTMzNjU3YWU1MzViYjZkOTkzZjYzOGYyNg",
           "alg": "RS256",
           "n": "8vjeHzRhvpfMystncPnLBWy_t5F3eCxbcLbdugWnzfnIgaV6TWnqPBUagJBKpzRZs4A9Qja_ZrSVJjYsbARzCS_qiWp0Cdwkqn6ZCXpmbpfjYnKORq8N8M-zWaSZYbNvWJ5oSO4kH-LKWzODaFebwTJBpsR1vChHH95doxFuUjiZaisVaQgUJ6drRdlDtImp9r9EAX36YROuYFPoEJcvsH4_uuAR6ClJ12RE3M-YN4NTi1waVNvGbz43oNrpPy7SXgpizingxSGMqI6WU2ysRmk_f9ALgiPIpFDpufiCTYaIcRT-YcUyp9nMDlTRskMuD-dQ1sdJOa11P_yMs-glfQ"
       }
   ]
}

The following table describes the information contained in the JWKS response:

Property	Description
`kty`	The cryptographic family to which the key belongs. Choreo only supports RSA.
`e`	The exponent value of the public key.
`use`	The purpose of the key. For example, whether it is for signing or encryption.
`kid`	The identification parameter to match a specific key.
`alg`	The algorithm to use with the key.
`n`	The modulus value of the public key.

Enable passing end-user attributes to the backend¶

To enable passing end-user attributes to the backend through API calls via Choreo, follow the steps given below:

Sign in to the Choreo Console.
In the Components Listing pane, click on the component for which you want to pass end-user attributes to the backend.
In the left navigation menu, click Deploy.
Go to the Set Up card and click Endpoint Configurations. This opens the Endpoint Configurations pane.

Note

If the component is an API Proxy, go to the Build Area card and click Security Settings. This opens the Security Settings pane.
Select the Pass Security Context To Backend checkbox.
Optionally, specify appropriate audience values in the End User Token Audiences field. Specifying values restricts the JWT to the respective audiences, enabling the backend service to validate and confirm the intended recipients, including itself.

Note

The backend JWT does not include the audience field (aud) by default.
Click Apply.
To redeploy the component with the applied setting, go to the Set Up card and click Deploy.