Inline Hooks

Lists all inline hooks or all inline hooks of a specific type.

When listing a specific inline hook, you need to specify its type. The following types are currently supported:

Creates an inline hook

This endpoint creates an inline hook for your org in an ACTIVE status. You need to pass an inline hooks object in the JSON payload of your request. That object represents the set of required information about the inline hook that you're registering, including:

• The URI of your external service endpoint
• The type of inline hook you're registering
• The type of authentication you're registering

There are two authentication options that you can configure for your inline hook: HTTP headers and OAuth 2.0 tokens.

HTTP headers let you specify a secret API key that you want Okta to pass to your external service endpoint (so that your external service can check for its presence as a security measure).

Note: The API key that you set here is unrelated to the Okta API token you must supply when making calls to Okta APIs.

You can also optionally specify extra headers that you want Okta to pass to your external service with each call.

To configure HTTP header authentication, see parameters for the config object.

OAuth 2.0 tokens provide enhanced security between Okta and your external service. You can configure these tokens for the following types—client secret and private key.

Note: Your external service's endpoint needs to be a valid HTTPS endpoint. The URI you specify should always begin with https://.

The total number of inline hooks that you can create in an Okta org is limited to 50, which is a combined total for any combination of inline hook types.

Retrieves an inline hook by inlineHookId

Updates an inline hook by inlineHookId

Replaces an inline hook by inlineHookId. The submitted inline hook properties replace the existing properties after passing validation.

Note: Some properties are immutable and can't be updated.

Deletes an inline hook by inlineHookId. After it's deleted, the inline hook is unrecoverable. As a safety precaution, only inline hooks with a status of INACTIVE are eligible for deletion.

Executes the inline hook that matches the provided inlineHookId by using the request body as the input. This inline hook sends the provided data through the channel object and returns a response if it matches the correct data contract. Otherwise it returns an error. You need to construct a JSON payload that matches the payloads that Okta would send to your external service for this inline hook type.

A timeout of three seconds is enforced on all outbound requests, with one retry in the event of a timeout or an error response from the remote system. If a successful response isn't received after the request, a 400 error is returned with more information about what failed.

Note: This execution endpoint isn't tied to any other functionality in Okta, and you should only use it for testing purposes.

Activates the inline hook by inlineHookId

Deactivates the inline hook by inlineHookId

Creates an Okta telephony inline hook request. This is an automated request from Okta to your third-party service endpoint.

The objects that you return in the JSON payload of your response to this Okta request are an array of one or more objects, which specify the Okta commands to execute.

Note: The size of your response payload must be less than 256 KB.

See also:

• For a general introduction to Okta inline hooks, see Inline hooks
• For information on the API for registering external service endpoints with Okta, see Inline Hooks Management API
• For an example implementation of a telephony inline hook, see Telephony inline hook

About

The Okta telephony inline hook allows you to integrate your own custom code into Okta flows that send SMS or voice call messages. You can integrate this hook with enrollment, authentication, and recovery flows that involve the phone authenticator. Okta uses your external provider to deliver the one-time passcode (OTP) to the Requester. The provider can respond with commands that indicate if the delivery was successful or not.

You can have only one active telephony inline hook per org.

When you create a telephony inline hook, you must include the authScheme parameter. See Create inline hook and the authScheme object.

Time-out behavior

If the provider response times out, Okta attempts to send the OTP using the Okta telephony providers. See Troubleshoot.

Note: The failover mechanism that uses the Okta telephony providers is heavily rate-limited.

Troubleshoot

This section explains several common causes of failure for telephony inline hooks.

Note: Administrators can use the Okta System Log to view errors. See the Troubleshooting section in the inline hooks topic for details on events captured by the Okta System Log.

Creates a password import 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. The objects that you return in the JSON payload of your response to this Okta request are an array of one or more objects, which specify the Okta commands to execute.

Note: The size of your response payload must be less than 256 KB.

The password import inline hook allows you to migrate users from another data store where you want the users to retain their current passwords. Use this hook with the Create user with password import inline hook flow that's described in the Users API.

The password import inline hook is triggered when the user tries to sign in to Okta for the first time. Okta sends your external service the password that the user supplied. Your external service then needs to send a response to Okta indicating whether the password supplied by the end user is valid.

If your service returns a response that indicates that the password is valid, Okta sets the password for the user. The password import inline hook won't need to call your service again. However, if the Okta service is in read-only mode, it might not be possible to set the password. Okta then needs to call your service again the next time the user attempts to sign in. See Password inline hook and Okta read-only mode and Removing password from existing user store.

Notes:

• Password policies don't apply to the password import inline hook. That is, if your external service validates the password, the password is imported even if it doesn't meet the Okta password policy requirements.
• You can create only one password import inline hook per org.

See also:

• Inline hooks for a general introduction to Okta inline hooks
• Inline Hooks Management API for information on the API for registering external service endpoints with Okta
• Add an inline hook for steps to enable this inline hook in the Admin Console
• Password import inline hook for an example implementation of this inline hook

Enable a password import inline hook

To enable a password import inline hook, you first need to register your external service endpoint with Okta and configure it as an inline hook of type com.okta.user.credential.password.import. You can enable the hook using the Admin Console, see Add an inline hook or through the Inline Hooks Management API. When creating a user with the Users API, you need to use the Create User with password import inline hook use case. This involves specifying a credentials.password.hook property in the request body.

When the user that you have added attempts to sign in to Okta for the first time, the hook is triggered and Okta calls your external service. The call sends the credentials that the end user provided. Your service can check the credentials and respond with a command to indicate whether the credentials are valid or not.

Password inline hook and Okta read-only mode

If your external service responds to Okta indicating that the credentials are valid, Okta saves the password and can authenticate the user independently from then on. However, if your Okta org is in a special read-only mode at the time the user signs in, then saving the password might not be possible. The next time the end user attempts to sign in, the password import inline hook needs to be called again.

Password removal from an existing user store

Because of the possibility of your org being in a special service mode, you shouldn't attempt to permanently delete user passwords from your existing user store until you can verify the success of the password import . An Okta System Log Event, user.import.password, is available for this purpose. An event of this type is created every time a password import inline hook is fired, with its Event.Outcome property providing a status of FAILURE or SUCCESS for the password import operation. If the status is SUCCESS, Okta has successfully saved the end user's password, and it's safe to delete it from your previous user store.

You can configure an Event hook to send this event type to you for use when triggering automated cleanup of end-user passwords after successful migration.

Creates a registration 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. The objects that you return in the JSON payload of your response to this Okta request are an array of one or more objects, which specify the Okta commands to execute.

The Okta registration inline hook allows you to integrate your own custom code into Okta's Profile Enrollment flow. The hook is triggered after Okta receives the registration or profile update request. Your custom code can:

• Allow or deny the registration attempt, based on your own validation of the information the user has submitted
• Set or override the values that are populated in attributes of the user's Okta profile

  Note: Profile Enrollment and self-service registration (SSR) inline hooks only work with the Okta Sign-In Widget version 4.5 or later.

See also:

• Inline hooks for a general introduction to Okta inline hooks
• Inline Hooks Management API for information on the API for registering external service endpoints with Okta
• Add an inline hook for steps to enable this inline hook in the Admin Console
• Registration inline hook for an example implementation of this inline hook

Creates a user import 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. The objects that you return in the JSON payload of your response to this Okta request are an array of one or more objects, which specify the Okta commands to execute.

The user import inline hook enables you to add custom logic to the process of importing new users into Okta from an app. You can resolve conflicts in user name or other profile attributes, modify values of profile attributes, and control whether the imported user is treated as a match for an existing user or not. The hook is invoked for each user being imported, at the point immediately after any applicable profile attribute mappings have been applied, and any potential matches with existing users have been found, but before the Okta user profile is created.

Note: If the external service times out after receiving an Okta request, the Okta process flow continues and the user is created.

See also:

• Inline hooks for a general introduction to Okta inline hooks
• Inline Hooks Management API for information on the API for registering external service endpoints with Okta
• Add an inline hook for steps to enable this inline hook in the Admin Console

Note: The procedure for associating a user import inline hook with an app using the Admin Console can't be used with AD or LDAP.

Creates a SAML assertion 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. The objects that you return in the JSON payload of your response to this Okta request are an array of one or more objects, which specify the Okta commands to execute.

This type of inline hook is triggered when Okta generates a SAML assertion in response to an authentication request. Before sending the SAML assertion to the app that will consume it, Okta calls out to your external service. Your external service can respond with commands to add attributes to the assertion or to modify its existing attributes.

You can use this functionality to add data to assertions, which might be data that is sensitive, calculated at runtime, or complexly-structured and not appropriate for storing in Okta user profiles. Data added this way is never logged or stored by Okta. As an example, SAML assertions generated for a medical app could be augmented with confidential patient data provided by your external service and not stored in Okta.

This inline hook works only when using custom SAML apps, not apps from the OIN.

See also:

• Inline hooks for a general introduction to Okta inline hooks
• Inline Hooks Management API for information on the API for registering external service endpoints with Okta
• For a use case example of how to implement a SAML assertion inline hook, see SAML assertion inline hook
• For steps to enable this inline hook, see Add an inline hook.

Specify location within the assertion

Specify the location within the assertion where you want to apply your operation using a slash-delimited path, which follows JSON Patch conventions.

When you perform an add op to add a new attribute statement, begin with /claims/ and follow that with the name of the new attribute that you're adding.

When you modify an existing assertions statement, begin the path with /subject/, /authentication/, /conditions/, or /claims/, depending on which part of the assertion you want to modify. You then look deeper within the child elements using slash-delimited element names, for example, /claims/array/attributeValues/1/value. (The /1/ in the path indicates the index of the array, using zero-based indexing.)

URI claims

Okta supports URI claims with SAML assertion hooks. When you need to replace or add a URI claim, encode the claim name within the command per the JavaScript Object Notation (JSON) Pointer specification. Specifically, this replaces ~ with ~0 and / with ~1.

SessionNotOnOrAfter support

In some scenarios, your service provider may require the SessionNotOnOrAfter attribute for the <saml:AuthnStatement> in the SAML assertion, which sets the provider session time correctly. Use add op with the path /authentication/sessionLifetime and a value for session lifetime in seconds to add this attribute. Okta calculates SessionNotOnOrAfter by adding the /authentication/sessionLifetime value to the issueInstant attribute and returns it in the SAML `data.assertion.