On this page
Registration inline hook reference
This page provides reference documentation for registration import inline hooks, one type of inline hook supported by Okta. It 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.
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 steps to set up and activate the registration inline hook, see Set up and activate the registration inline hook.
For steps to enable this inline hook, see Enabling a registration inline hook.
For an example implementation of this inline hook, see Registration inline hook.
About
The Okta registration inline hook allows you to integrate your own custom code into Okta's Profile Enrollment (opens new window) 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.
Objects in the Request from Okta
The outbound call from Okta to your external service includes the following objects in its JSON payload:
requestType
OTP request or event for which this transaction is being requested: self-service registration (SSR) or Progressive Enrollment.
Values for requestType
are one of the following:
Enum Value | Associated Okta Event |
---|---|
self.service.registration | self-service registration (SSR) |
progressive.profile | Progressive Enrollment |
data.userProfile
This object appears in SSR requests from Okta. The object contains name-value pairs for each registration related attribute supplied by the user in the Profile Enrollment form, including:
lastName
firstName
login
email
- other custom attributes on the Sign-In Widget
The following attributes aren't included in the data.userProfile
object:
- the
password
field - any fields corresponding to user profile attributes marked as sensitive in your Okta user schema
Using the com.okta.user.profile.update
commands you send in your response, you can modify the values of the attributes, or add other attributes, before the values are assigned to the Okta user profile that will be created for the registering user.
You can only set values for profile fields which already exist in your Okta user profile schema. Registration inline hook functionality can only set values. It can't create new fields.
data.UserProfileUpdate
Identity EngineThis object appears in Progressive Profile requests from Okta. The object contains the delta between existing name-value pairs and the attributes that your end user wants to update.
Use the com.okta.user.progressive.profile.update
command in your response to progressively change the values of delta attributes in the user's Okta profile.
Note: You can also allow end users to update non-sensitive attributes in addition to the delta attributes Okta sends in the request.
data.action
Note: The
data.action
object can appear in both SSR and Progressive Profile requests.
The action that Okta is currently set to take, regarding whether to allow this registration attempt.
There are two possible values:
ALLOW
indicates that the registration attempt will be allowed to proceedDENY
indicates that the registration attempt will be terminated (no user will be created in Okta)
The action is ALLOW
by default (in practice, DENY
will never be sent to your external service).
Using the com.okta.action.update
command in your response, you can change the action that Okta will take.
Response objects that you send
The objects that you can return in the JSON payload of your response are an array of one or more commands
, to be executed by Okta, or an error
object, to indicate problems with the registration request.
Note: The size of your response payload must be less than 256 KB.
The response objects are defined as follows:
commands
The commands
object lets you invoke commands to modify or add values to the attributes in the Okta user profile that will be created for this user, as well as to control whether or not the registration attempt is allowed to proceed.
This object is an array, allowing you to send multiple commands in your response. Each array element requires a type
property and a value
property. The type
property is where you specify which of the supported commands you wish to execute, and value
is where you supply parameters for that command.
Property | Description | Data Type |
---|---|---|
type | One of the supported commands. | String |
value | Operand to pass to the command. | value |
For example commands, see the value section below.
Supported commands
The following commands are supported for the registration inline hook type:
Command | Description |
---|---|
com.okta.user.profile.update | Change attribute values in the user's Okta user profile. For SSR only. Invalid if used with a Progressive Profile response. |
com.okta.action.update | Allow or deny the user's registration. |
com.okta.user.progressive.profile.update | Change attribute values in the user's Okta Progressive Profile. Identity Engine |
To set attributes in the user's Okta profile, supply a type property set to com.okta.user.profile.update
, together with a value
property set to a list of key-value pairs corresponding to the Okta user profile attributes you want to set. The attributes must already exist in your user profile schema.
To explicitly allow or deny registration to the user, supply a type property set to com.okta.action.update
, together with a value property set to {"registration": "ALLOW"}
or {"registration": "DENY"}
. The default is to allow registration.
In Okta Identity Engine, to set attributes in the user's profile, supply a type property set to com.okta.user.progressive.profile.update
, together with a value
property set to a list of key-value pairs corresponding to the Progressive Enrollment attributes that you want to set. See Registration inline hook - Send response.
Identity Engine
Commands are applied in the order that they appear in the array. Within a single com.okta.user.profile.update
or com.okta.user.progressive.profile.update
command, attributes are updated in the order that they appear in the value
object.
You can never use a command to update the user's password, but you are allowed to set the values of attributes other than password that are designated sensitive in your Okta user schema. However, the values of those sensitive attributes, if included as fields in the Profile Enrollment form, aren't included in the data.userProfile
object sent to your external service by Okta. See data.userProfile.
value
The value
object is the parameter to pass to the command.
For com.okta.user.profile.update
commands, value
should be an object containing one or more name-value pairs for the attributes you wish to update, for example:
{
"commands":[
{
"type":"com.okta.user.profile.update",
"value":{
"middleName":"Danger",
"customerId":12345
}
}
]
}
The above example assumes that there is an attribute customerId
defined in your Okta user schema (middleName
is defined by default).
The same result could also be accomplished by means of two separate com.okta.user.profile.update
commands, as follows:
{
"commands":[
{
"type":"com.okta.user.profile.update",
"value":{
"middleName":"Danger"
}
},
{
"type":"com.okta.user.profile.update",
"value":{
"customerId":12345
}
}
]
}
For com.okta.action.update
commands, value
should be an object containing the attribute action
set to a value of either ALLOW
or DENY
, indicating whether the registration should be permitted or not, for example:
{
"commands": [
{
"type": "com.okta.action.update",
"value": {
"registration": "DENY"
}
}
]
}
Registrations are allowed by default, so setting a value of ALLOW
for the action
field is valid but superfluous.
error
See error for general information about the structure to use for the error
object.
For the registration inline hook, the error
object provides a way of displaying an error message to the end user who is trying to register or update their profile.
Note: Generic Progressive Enrollment error messages are only available in the Identity Engine.
If you're using the Okta Sign-In Widget for Profile Enrollment, only the
errorSummary
messages of theerrorCauses
objects that your external service returns appear as inline errors, given the following:- You don't customize the error handling behavior of the widget.
- The
location
oferrorSummary
in theerrorCauses
object specifies the request object's user profile attribute.
If you don't return a value for the
errorCauses
object, and deny the user's registration attempt through thecommands
object in your response to Okta, one of the following generic messages appears to the end user:- "Registration cannot be completed at this time." (SSR)
- "We found some errors. Please review the form and make corrections." (Progressive Enrollment)
If you don't return an
error
object at all and the registration is denied, the following generic message appears to the end user:- "Registration denied." (SSR)
- "Profile update denied." (Progressive Enrollment)
Note: If you include an error object in your response, no commands are executed and the registration fails. This holds true even if the top-level
errorSummary
and theerrorCauses
objects are omitted.
Timeout behavior
If there is a response timeout after receiving the Okta request, the Okta process flow stops. Depending on the request, either the self-service registration or the profile update is denied. One of the following default UI messages appears:
- "There was an error creating your account. Please try registering again." (SSR)
- "Your profile couldn't be updated at this time. Please try again later." (Profile Enrollment)
Sample SSR request
The following is an example of a JSON request received from Okta. The request properties contain data submitted by the end user who is trying to self register.
See request properties for full details.
{
"eventId": "04Dmt8BcT_aEgM",
"eventTime": "2022-04-25T17:35:27.000Z",
"eventType": "com.okta.user.pre-registration",
"eventTypeVersion": "1.0",
"contentType": "application/json",
"cloudEventVersion": "0.1",
"source": "regt4qeBKU29vSoPz0g3",
"requestType": "self.service.registration",
"data": {
"context": {
"request": {
"method": "POST",
"ipAddress": "127.0.0.1",
"id": "123dummyId456",
"url": {
"value": "/idp/idx/enroll/new"
}
}
},
"userProfile": {
"firstName": "Rosario",
"lastName": "Jones",
"login": "rosario.jones@example.com",
"email": "rosario.jones@example.com"
},
"action": "ALLOW"
}
}
Sample SSR responses
The external service responds to Okta indicating whether to accept the end user's self-registration attempt. The response returns a commands
object in the body of the HTTPS response. This object contains specific syntax that indicates whether the user is allowed or denied to self-register.
See response properties for full details.
Sample SSR response using data.userProfile
The following sample response shows a successful self-registration:
{
"commands": [
{
"type": "com.okta.user.profile.update",
"value": {
"login": "first.last@example.com"
}
}
]
}
Sample SSR response using data.action
The following sample response uses the DENY
value and a custom error caused by an invalid email domain:
{
"commands": [
{
"type": "com.okta.action.update",
"value": {
"registration": "DENY"
}
}
],
"error": {
"errorSummary": "Incorrect email address. Please contact your admin.",
"errorCauses": [
{
"errorSummary": "Only example.com emails can register.",
"reason": "INVALID_EMAIL_DOMAIN",
"locationType": "body",
"location": "data.userProfile.email",
"domain": "end-user"
}
]
}
}
Sample progressive enrollment request
The following JSON example provides the end user's profile data to the external service for evaluation.
See request properties for full details.
{
"eventId": "vzYp_zMwQu2htIWRbNJdfw",
"eventTime": "2022-04-25T04:04:41.000Z",
"eventType": "com.okta.user.pre-registration",
"eventTypeVersion": "1.0",
"contentType": "application/json",
"cloudEventVersion": "0.1",
"source": "regt4qeBKU29vS",
"requestType": "progressive.profile",
"data": {
"context": {
"request": {
"method": "POST",
"ipAddress": "127.0.0.1",
"id": "123dummyId456",
"url": {
"value": "/idp/idx/enroll/update"
}
},
"user": {
"passwordChanged": "2022-01-01T00:00:00.000Z",
"_links": {
"groups": {
"href": "/api/v1/users/00u48gwcu01WxvNol0g7/groups"
},
"factors": {
"href": "/api/v1/users/00u48gwcu01WxvNol0g7/factors"
}
},
"profile": {
"firstName": "Rosario",
"lastName": "Jones",
"timeZone": "America/Los_Angeles",
"login": "rosario.jones@example.com",
"locale": "en_US"
},
"id": "00u48gwcu01WxvNo"
}
},
"action": "ALLOW",
"userProfileUpdate": {
"employeeNumber": "1234"
}
}
}
Sample progressive enrollment responses
The external service responds to Okta indicating whether to accept the end user's profile update. The response returns a commands
object in the body of the HTTPS response. This object contains specific syntax that indicates whether the user is allowed or denied to update their profile with Okta.
See response properties for full details.
Sample progressive enrollment response using data.UserProfileUpdate
The following sample response shows the addition of an employee number to an end user's profile:
{
"commands": [
{
"type": "com.okta.user.progressive.profile.update",
"value": {
"employeeNumber": "1234"
}
}
]
}
Sample progressive enrollment response using data.action
The following sample response uses the DENY
value and a custom error caused by an invalid employee number:
{
"commands": [
{
"type": "com.okta.action.update",
"value": {
"registration": "DENY"
}
}
],
"error": {
"errorSummary": "Incorrect employee number. Enter an employee number with 4 digits.",
"errorCauses": [
{
"errorSummary": "Only employee numbers with 4 digits can register.",
"reason": "INVALID_EMPLOYEE_NUMBER",
"locationType": "body",
"location": "data.userProfile.employeeNumber",
"domain": "end-user"
}
]
}
}