Skip to content

Create a token inline hook
Webhook

Request

Creates a token inline hook request, one type of inline hook supported by Okta. This is an automated request from Okta to your third-party service endpoint. This reference provides sample JSON objects that are contained in the outbound request from Okta to your external service, and sample JSON objects that you can include in your response.

This type of inline hook is triggered when OAuth 2.0 and OpenID Connect (OIDC) tokens are minted by your Okta custom authorization server. Before sending the token to the requester, Okta calls out to your external service. Your service can then respond with commands to add custom claims to the token or to modify existing claims.

Use this functionality to add data that is sensitive, calculated at runtime, or complexly structured and not appropriate for storing in Okta user profiles. Okta never logs nor stores data that is added this way. As an example, tokens minted for a medical app could be augmented with confidential patient data provided by your external service and not stored in Okta.

In addition to adding custom claims, you can modify or remove an existing custom claim or an OIDC standard profile claim. You can also update how long an access token or an ID token is valid.

This inline hook works only when using an Okta custom authorization server, not the built-in Okta org authorization server.

See also:

Timeout behavior

After receiving the Okta request, if there's a response timeout, the Okta process flow proceeds with the original token returned. The token inline hook isn't retried.

Enabling a token inline hook

To activate the inline hook, you first need to register your external service endpoint with Okta using the Inline Hooks Management API. You then need to associate the registered inline hook with a custom authorization server policy rule by completing the following steps:

  1. Go to Security > API > Authorization Servers.
  2. Select a custom authorization server from the list.
  3. Select Access Policies and select a policy to use with the hook. In most cases, pick the Default Policy.
  4. One of the policy's rules needs to trigger the inline hook. Click the pencil icon for a rule to edit it. If you only have one rule, edit the Default Policy Rule.
  5. Click the Use this Inline Hook dropdown menu. Any inline hooks that you have registered are listed. Select the hook that you would like to use.
  6. Click Update Rule.

Note: You can associate only one inline hook with each rule.

Troubleshoot

This section covers what happens when a token inline hook flow fails either due to the external inline hook service returning an error object or not returning a successful response, or the inline hook patch fails.

Note: Administrators can use the Okta System Log to view errors. See the Troubleshooting section in the inline hooks concept piece for more information on the events related to inline hooks that the Okta System Log captures.

  • When there's a communication failure with the external service, a timeout for example, the inline hook operation is skipped. The token is generated without any modification from the inline hook. The token inline hook isn't retried.

    Who can see this error? Administrators

  • When the external service returns a response with any other HTTP status code besides 200, the inline hook operation is skipped. The token is generated without any modification from the inline hook.

    Who can see this error? Administrators

  • When the external service returns an error object in the response, the entire token inline hook flow fails with no token generated.

    Who can see this error? Administrators, developers, and end users. When the OAuth 2.0 client receives the error, the client developer can see that error if the client has the debug information. What the end user sees depends on how errors are handled within the client.

    Note: See the error section on this page for more information on what to include in the error object of your response and what the OAuth 2.0 error includes that Okta returns to the requestor of the token.

  • When a hook command (for example, updating, adding, and deleting claims) can't be performed, the inline hook operation is skipped. The token is generated without any modification from the inline hook.

    Who can see this error? Administrators

    The following actions result in an error:

    • Using an invalid command. For example, if only an ID token is requested, the commands array shouldn't contain commands of the type com.okta.access.patch.
    • Using an invalid operation
    • Attempting to remove a system-specific claim
    • Attempting to update a claim that doesn't exist
    • Attempting to update an element within an array that doesn't exist or specifying an invalid index
    • Attempting to remove a claim that doesn't exist
Bodyapplication/jsonrequired
cloudEventVersionstring

The inline hook cloud version

Example:0.1
contentTypestring

The inline hook request header content

Example:"application/JSON"
eventIdstring

The individual inline hook request ID

Example:"3o9jBzq1SmOGmmsDsqyyeQ"
eventTimestring

The time the inline hook request was sent

Example:"2020-01-17T21:23:56.000Z"
eventTypeVersionstring

The inline hook version

Example:1
dataobject
eventTypestring

The type of inline hook. The token inline hook type is com.okta.oauth2.tokens.transform.

sourcestring

The URL of the token inline hook

Payload

An example token inline hook request body

{ "source": "https://{yourOktaDomain}/oauth2/default/v1/authorize", "eventId": "3OWo4oo-QQ-rBWfRyTmQYw", "eventTime": "2019-01-15T23:20:47.000Z", "eventTypeVersion": "1.0", "cloudEventVersion": "0.1", "contentType": "application/json", "eventType": "com.okta.oauth2.tokens.transform", "data": { "context": { … }, "identity": { … }, "access": { … }, "refresh_token": { … } } }

Responses

Successful response

Bodyapplication/json
commandsArray of objects

You can use the commands object to provide commands to Okta. It's where you can tell Okta to add more claims to the token. The commands object is an array, allowing you to send multiple commands. In each array element, there needs to be a type property and value property. The type property is where you specify which of the supported commands you want to execute, and value is where you supply an operand for that command. In the case of the token hook type, the value property is itself a nested object in which you specify a particular operation, a path to act on, and a value.

errorobject

When an error object is returned, it causes Okta to return an OAuth 2.0 error to the requester of the token. In the error response, the value of error is server_error, and the value of error_description is the string that you supplied in the errorSummary property of the error object that you returned.

Response
{ "commands": [ { … }, { … } ] }