This article provides instructions on how to use a Token Inline Hook to enrich ID and/or Access Tokens issued by a Custom Authorization Server based on the request parameters included in the /authorize (for example, for Implicit and Authorization Code flow) or /token request (for example, for Resource Owner Password Grant, Token Renewals), including extraneous parameters that are not supported by the endpoint itself.

• Custom Authorization Server
• Token Inline Hooks
• Okta Classic Engine
• Okta Identity Engine (OIE)

The full request URL for the request will be available in the request payload sent to the Token Inline Hook endpoint. Any additional parameters included in the request made to Okta will be ignored by Okta but will still be included in the request payload sent to the hook endpoint, thus allowing the application to send dynamic values to the /authorize and the /token endpoint that can be used to drive logic for the Token Inline Hook endpoint (such as adding this value as a claim in the resultant token).

Depending on the flow being executed, the extra parameters can be included within the /authorize request URL or the /token request URL. For example, if the application in question uses the Authorization Code flow, this parameter can be included in the /authorize request when the application first requests tokens for the user and in the /token request when the application renews the user's tokens with a refresh token.

The full request URL for the /authorize or /token request that triggered the hook execution can be found within the data.context.url.value object in the request payload (see example payload below)

Examples of URLs With an Extra Request Parameter

Authorize Eequest URL

https://oktaDomain/oauth2/aus1234567890/v1/authorize?client_id=0oa1234567890&scope=openid+profile&redirect_uri=https://example.com&response_type=code&state=asbn5dasau141n3io13&nonce=foo&extraParam=this_is_an_extra_parameter

Token Request URL

https://oktaDomain/oauth2/aus1234567890/v1/token?extraParam=this_is_an_extra_parameter

Example Inline Hook Payload

{
  "eventId": "<eventId>",
  "eventTime": "2024-07-03T18:51:51.000Z",
  "eventType": "com.okta.oauth2.tokens.transform",
  "eventTypeVersion": "1.0",
  "contentType": "application/json",
  "cloudEventVersion": "0.1",
  "source": "https://oktaDomain/oauth2/aus1234567890/v1/token",
  "data": {
    "context": {
      "request": {
        "id": "<id>",
        "method": "POST",
        "url": {
          "value": "https://oktaDomain/oauth2/aus1234567890/v1/token?extraParam=this_is_a_refresh"
        },
        "ipAddress": "<ipAddress>"
      },
      "protocol": {
        "type": "OAUTH2.0",
        "request": {
          "scope": "offline_access openid profile",
          "grant_type": "refresh_token",
          "client_id": "0oa01234567890"
        },
        "originalGrant": {
          "authorization": {
            "scope": "profile offline_access openid",
            "redirect_uri": "https://example.com",
            "response_type": "code",
            "grant_type": "authorization_code"
          },
          "refresh_token": {
            "jti": "oar1234567890"
          }
        },
        "issuer": {
          "uri": "https://oktaDomain/oauth2/aus1234567890"
        },
        "client": {
          "id": "0oa01234567890",
          "name": "Web App",
          "type": "PUBLIC"
        }
      },
      "session": {
        "id": "<id>",
        "userId": "00u1234567890",
        "login": "user@example.com",
        "createdAt": "2024-07-03T18:50:52.000Z",
        "expiresAt": "2024-07-03T20:51:51.000Z",
        "status": "ACTIVE",
        "lastFactorVerification": "2024-07-03T18:50:51.000Z",
        "amr": [
          "PASSWORD"
        ],
        "mfaActive": false
      },
      "user": {
        "id": "00u1234567890",
        "passwordChanged": "2021-10-28T00:27:44.000Z",
        "profile": {
          "login": "user@example.com",
          "firstName": "Test",
          "lastName": "User",
          "locale": "en",
          "timeZone": "America/Los_Angeles"
        },
        "_links": {
          "groups": {
            "href": "https://oktaDomain/api/v1/users/00u1234567890/groups"
          },
          "factors": {
            "href": "https://oktaDomain/api/v1/users/00u1234567890/factors"
          }
        }
      },
      "policy": {
        "id": "00p1234567890",
        "rule": {
          "id": "0pr1234567890"
        }
      }
    },
    "identity": {
      "claims": {
        "sub": "00u1234567890",
        "name": "Test User",
        "ver": 1,
        "iss": "https://oktaDomain/oauth2/aus1234567890",
        "aud": "0oa01234567890",
        "jti": "ID.12345678912345678",
        "amr": [
          "swk",
          "mfa",
          "pwd"
        ],
        "idp": "00o1234567890",
        "sid": "<>",
        "preferred_username": "test.user",
        "auth_time": 1720032651
      },
      "token": {
        "lifetime": {
          "expiration": 3600
        }
      }
    },
    "access": {
      "claims": {
        "ver": 1,
        "jti": "AT.12345678",
        "iss": "https://oktaDomain/oauth2/aus1234567890",
        "aud": "/hooks",
        "cid": "0oa01234567890",
        "uid": "00u1234567890",
        "auth_time": 1720032651,
        "sub": "test.user"
      },
      "token": {
        "lifetime": {
          "expiration": 3600
        }
      },
      "scopes": {
        "openid": {
          "id": "scpfhu4svvZ4Gl6Pm1d7",
          "action": "GRANT"
        },
        "offline_access": {
          "id": "scpfhu4sw0Zasc1oD1d7",
          "action": "GRANT"
        },
        "profile": {
          "id": "scpfhu4svwnGvLJ9x1d7",
          "action": "GRANT"
        }
      }
    },
    "refresh_token": {
      "jti": "oar1234567890"
    }
  }
}

Related References

• Token Inline Hook Reference
• Token Inline Hook Guide
• Custom Authorization Server