Client Credentials JWT Populate Lambda

If you would like to augment the claims provided in the JWT before it has been signed you can specify a lambda in the JWT configuration. This lambda will be invoked prior to the token being signed and issued as a result of the client credentials grant, on behalf of an Entity.

When you create a new lambda using the FusionAuth UI we will provide you an empty function for you to implement.

Lambda Structure

If you are using the API to create the lambda you will need to ensure your function has the following signature:

function populate(jwt, recipientEntity, targetEntities, permissions) {
  // Lambda code goes here
}

This lambda must contain a function named populate that takes four parameters. The parameters that the lambda is passed are:

jwt - the claims object to be signed and return as the JWT payload. You can modify this object.
recipientEntity - the Recipient Entity. This object is read-only. See an example below.
targetEntities - the Target Entities. This object is read-only. See an example below.
permissions - the permissions assigned to the Entity. This object is read-only. Example below.

The recipientEntity and targetEntities objects are well documented in the Permissions & Entity Types APIs and Entities API documentation. The JWT object is a JavaScript object containing the JWT payload. See here for more.

You may add or modify anything in the jwt object. However, you may not modify the header keys or values of the JWT. FusionAuth also protects certain reserved claims. The following claims are considered reserved and modifications or removal will not be reflected in the final JWT payload:

aud
exp
iat
permissions
sub
tid

The tid claim was added in version 1.36.0.

Assigning The Lambda

Once a lambda is created, you must assign it. To do so via the administrative user interface, navigate to Tenants -> Your Tenant -> OAuth and update the Client credentials populate lambda setting.

Example Entities And Permissions Objects

For these example objects (available in the lambda) there are three entities created (reminder, todo, and email) with an api entity type with read and write user defined permission values.

Example JSON for recipientEntity object.

{
  "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"
      }
    ]
  }
}

Example JSON for targetEntities object.

{
  "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"
        }
      ]
    }
  }
}

Example JSON for permissions object.

{
  "0b56a9ff-5e5d-4969-9cc2-3f1f49e5c64d": [
    "write"
  ],
  "b22a5012-3464-4490-bc1b-603d6d9d619b": [
    "read"
  ]
}

Related information about Client Credentials Grant.

Results