Client Credentials JWT Populate Lambda
On this page
A client credentials JWT populate lambda adds claims to the access token FusionAuth issues for the Client Credentials grant. FusionAuth runs the lambda before signing the token for the Entity.
When you create a lambda in the Admin UI, FusionAuth provides an empty function for you to implement.
Lambda Structure#
When you create the lambda with the API, give the function the following signature:
function populate(jwt, recipientEntity, targetEntities, permissions, context) {
// Lambda code goes here
}
The lambda must contain a function named populate that accepts the following parameters:
jwt: the claims object that FusionAuth signs and returns as the JWT payload. You can modify this object.recipientEntity: the Entity requesting the token. This object is read-only.targetEntities: the Entities the token grants access to, keyed by Entity Id. This object is read-only.permissions: the granted permission names, keyed by target Entity Id. This object is read-only.context: Available since1.64.0an object containing the context of the request, including access to secrets. This object is read-only.
The Permissions & Entity Types APIs and Entities API documentation describe the recipientEntity and targetEntities objects. For the claims in the JWT payload, see OpenID Connect & OAuth 2.0 Token.
You can add or change any claim in the jwt object, except the header and the reserved claims. FusionAuth discards changes to the following reserved claims, including removals:
act: Available since1.70.0the actor claim chain, which token exchangeAn OAuth 2.0 grant type enabling security token exchange, delegation, and impersonation across services. managesamraudauthenticationTypecnfexpgtyiatpermissionssubtidttyuse
FusionAuth discards changes to reserved claims without an error or a log entry, and you can't turn off this behavior. To confirm the claims in a token, decode the issued token.
Before version 1.70.0, a lambda could set act. If a lambda sets a custom act claim, rename the claim with a namespace.
To remove a claim that isn't reserved, set the claim to null. FusionAuth also sets the scope claim to the requested scopes. The scope claim isn't reserved, but resource serversThe API or service that accepts access tokens and returns protected data. A resource server validates each access token before responding. rely on scope, so don't overwrite the claim.
The recipientEntity object includes the clientSecret of the Entity. Don't copy the whole recipientEntity object, or the clientSecret, into a claim.
Assigning the Lambda#
After you create the lambda, assign the lambda in the Admin UI. Navigate to Tenants -> Your Tenant -> OAuth and update the Client credentials populate lambda setting.
Example Entities and Permissions Objects#
The following example objects come from a tenant with three Entities: Reminder API, Todo API, and Email API. All three Entities use an API Entity TypeA category of Entity that defines the Permissions available to Entities of that type. with read and write permissions. The Reminder API Entity requests a token for the other two Entities:
{
"clientId": "9d570ab2-8705-483b-8cbd-9dd74935fce1",
"clientSecret": "LUtIbHgOiCwOjVGDwTcgNaYELJAJJyj-qzhT5XQzhvE",
"data": {},
"id": "9d570ab2-8705-483b-8cbd-9dd74935fce1",
"insertInstant": 1625005371790,
"lastUpdateInstant": 1625005371790,
"name": "Reminder API",
"tenantId": "30663132-6464-6665-3032-326466613934",
"type": {
"data": {},
"id": "0bd2dcc9-6389-494e-b0cd-743de05d67a5",
"insertInstant": 1625002067313,
"jwtConfiguration": {
"enabled": false,
"timeToLiveInSeconds": 60
},
"lastUpdateInstant": 1625002067313,
"name": "API",
"permissions": [
{
"data": {},
"description": "read something",
"id": "640e7e1c-5f39-458c-ba0f-15c1e1c0eac7",
"insertInstant": 1625007399127,
"isDefault": false,
"lastUpdateInstant": 1625007399127,
"name": "read"
},
{
"data": {},
"description": "write something",
"id": "41ea8074-43b1-4b08-845c-418dacdc0a44",
"insertInstant": 1625007410986,
"isDefault": false,
"lastUpdateInstant": 1625007410986,
"name": "write"
}
]
}
}{
"0b56a9ff-5e5d-4969-9cc2-3f1f49e5c64d": {
"clientId": "0b56a9ff-5e5d-4969-9cc2-3f1f49e5c64d",
"clientSecret": "dSD5mxPXEF-SJL6LPxOAFOwgU6vwitzixlMafHiJWIM",
"data": {},
"id": "0b56a9ff-5e5d-4969-9cc2-3f1f49e5c64d",
"insertInstant": 1625005404087,
"lastUpdateInstant": 1625005404087,
"name": "Email API",
"tenantId": "30663132-6464-6665-3032-326466613934",
"type": {
"data": {},
"id": "0bd2dcc9-6389-494e-b0cd-743de05d67a5",
"insertInstant": 1625002067313,
"jwtConfiguration": {
"enabled": false,
"timeToLiveInSeconds": 60
},
"lastUpdateInstant": 1625002067313,
"name": "API",
"permissions": [
{
"data": {},
"description": "read something",
"id": "640e7e1c-5f39-458c-ba0f-15c1e1c0eac7",
"insertInstant": 1625007399127,
"isDefault": false,
"lastUpdateInstant": 1625007399127,
"name": "read"
},
{
"data": {},
"description": "write something",
"id": "41ea8074-43b1-4b08-845c-418dacdc0a44",
"insertInstant": 1625007410986,
"isDefault": false,
"lastUpdateInstant": 1625007410986,
"name": "write"
}
]
}
},
"b22a5012-3464-4490-bc1b-603d6d9d619b": {
"clientId": "b22a5012-3464-4490-bc1b-603d6d9d619b",
"clientSecret": "ICCUTaPG0-6rfcW65zFFNPe0N7MAF6CkFOu5sWan4Xo",
"data": {},
"id": "b22a5012-3464-4490-bc1b-603d6d9d619b",
"insertInstant": 1625002153314,
"lastUpdateInstant": 1625002153314,
"name": "Todo API",
"tenantId": "30663132-6464-6665-3032-326466613934",
"type": {
"data": {},
"id": "0bd2dcc9-6389-494e-b0cd-743de05d67a5",
"insertInstant": 1625002067313,
"jwtConfiguration": {
"enabled": false,
"timeToLiveInSeconds": 60
},
"lastUpdateInstant": 1625002067313,
"name": "API",
"permissions": [
{
"data": {},
"description": "read something",
"id": "640e7e1c-5f39-458c-ba0f-15c1e1c0eac7",
"insertInstant": 1625007399127,
"isDefault": false,
"lastUpdateInstant": 1625007399127,
"name": "read"
},
{
"data": {},
"description": "write something",
"id": "41ea8074-43b1-4b08-845c-418dacdc0a44",
"insertInstant": 1625007410986,
"isDefault": false,
"lastUpdateInstant": 1625007410986,
"name": "write"
}
]
}
}
}{
"0b56a9ff-5e5d-4969-9cc2-3f1f49e5c64d": [
"write"
],
"b22a5012-3464-4490-bc1b-603d6d9d619b": [
"read"
]
}Example Lambda#
FusionAuth puts the granted permissions in the reserved permissions claim, keyed by target Entity Id. The following lambda adds a second claim that names each target Entity, such as Todo API:read. The lambda also adds a tier from the data of the recipient Entity, with a default of standard:
// adds permissions named by target entity, and the recipient's tier from entity data
function populate(jwt, recipientEntity, targetEntities, permissions, context) {
var named = [];
Object.keys(permissions).forEach(function (targetId) {
var target = targetEntities[targetId];
var name = target ? target.name : targetId;
permissions[targetId].forEach(function (permission) {
named.push(name + ':' + permission);
});
});
jwt['https://example.com/permissions'] = named.sort();
jwt['https://example.com/tier'] = (recipientEntity.data && recipientEntity.data.tier) || 'standard';
}With the example objects above, the token gets the following claims:
{
"https://example.com/permissions": ["Email API:write", "Todo API:read"],
"https://example.com/tier": "standard"
}
Related
Learn how to add custom claims to the access tokens and Id tokens FusionAuth issues.
Learn how to add custom claims to the UserInfo response.
Learn about the APIs for creating, retrieving, updating and deleting entities, as well as searching them.
Learn about the APIs for creating, retrieving, updating and deleting entities and entity types.