Instructions for

Registration inline hook

Note: This document is only for Okta Classic Engine. If you are using Okta Identity Engine, see Configure a registration inline hook. See Identify your Okta solution (opens new window) to determine your Okta version.

This guide provides a working example of an Okta registration inline hook. It uses the web site Glitch.com (opens new window) to act as an external service and receive and respond to registration inline hook calls.

Learning outcomes

Understand the Okta registration inline hook calls and responses.
Implement a simple working example of a registration inline hook with a Glitch.com project.
Preview and test a registration inline hook.

What you need

Okta Developer Edition organization (opens new window)
Glitch.com (opens new window) project or account

Sample code

Okta Registration Inline Hook Example (opens new window)

About registration inline hook implementation

In the following example, the external service code parses requests from Okta and responds with commands that indicate whether the end user's email domain is valid and allowed to register.

At a high-level, the following workflow occurs:

A user attempts to self-register with your Okta org.
A registration inline hook triggers during this process and sends a call to the external service with the user's data.
The external service evaluates the Okta call to ensure the user is from domain example.com.
The external service responds to Okta with a command to allow or deny the registration based on the email domain.

Add request code

This step includes the code that parses the body of the request received from Okta, which gets the values of data.userProfile. These properties contain the credentials submitted by the end user who is trying to self register.

The following code checks the email property of an incoming request from Okta, which is the email used to self-register. The values of data.userProfile from within the request body contains the email property that is verified. The variable emailRegistration stores the value of the email.

See the request properties of a Registration Inline Hook for full details.

app.post('/registrationHook', async (request, response) => {
  var emailRegistration = request.body.data.userProfile['email'];


}

Note: The method definition in the previous code snippet is incomplete. See the next section for the complete method.

Send response

The external service responds to Okta indicating whether to accept the user self-registration by returning a commands object in the body of the HTTPS response. This object contains specific syntax that indicates whether the user is allowed or denied self-registration with Okta.

For this example, only users with emails that contain example.com are allowed to self-register. You can also include an error object in the response for users that are denied self-registration.

See the response properties of a registration inline hook for full details.

app.post('/registrationHook', async (request, response) => {
  console.log(" "); // for separation of logs during testing
  console.log('Email for ' + request.body.data.userProfile['firstName'] + " " + request.body.data.userProfile['lastName'] + " " + request.body.data.userProfile['email']);

  var emailRegistration = request.body.data.userProfile['email'];
  if (emailRegistration.includes("example.com")){

    var returnValue = { "commands":[
                          { "type":"com.okta.action.update",
                            "value":{ "registration": "ALLOW"} }
                                   ]
                      }

  }

  else {

    var returnValue = { "commands":[
                          { "type":"com.okta.action.update",
                            "value":{ "registration": "DENY"} }
                                   ],
                         "error": {
                          "errorSummary":"Incorrect email address. Please contact your admin.",
                          "errorCauses":[
                             {
                                "errorSummary":"Only yourDomain emails can register.",
                                "reason":"INVALID_EMAIL_DOMAIN",
                                "locationType":"body",
                                "location":"data.userProfile.login",
                                "domain":"end-user"
                             }
                                        ]
                          }

                      }
  }

  response.send(JSON.stringify(returnValue));

  }
)

Activate and enable

The registration inline hook must be set up, activated, and enabled within your Okta Admin Console.

To set up and activate the registration inline hook:

In the Admin Console, go to Workflow > Inline Hooks.
Click Add Inline Hook and select Registration from the dropdown menu.
Add a name for the hook (in this example, use "Guide Registration Hook Code").
Add your external service URL, including the endpoint. For example, use your Glitch project name with the endpoint: https://your-glitch-projectname.glitch.me/registrationHook.
Include the authentication field and secret. In this example:
- Authentication Field = authorization
- Authorization Secret = Basic YWRtaW46c3VwZXJzZWNyZXQ=
Click Save.

The registration inline hook is now set up with an active status.

Note: You can also set up an inline hook using the API. See Inline Hooks Management API.

Enable the registration inline hook in the Classic Engine

If you have a Classic Engine org, you must enable self-service registration (SSR) to implement a registration inline hook.

Note: Self-service registration and registration inline hooks are only supported with the Okta Sign-In Widget version 2.9 or later.

To enable the registration inline hook on the self-service registration page:

In the Admin Console, go to Directory > Self-Service Registration.
Click Edit.
From the Extension dropdown menu, select the hook that you set up and activated previously ("Guide Registration Hook Code").
Click Save.

The registration inline hook is now enabled for self-service registration. You are now ready to preview and test the example.

Preview and test

The external service example is now ready with code to receive and respond to an Okta call. The Okta org is now set up to call the external service using a registration inline hook.

In your Okta org, you can preview the request and response JSON right from the Admin Console. You can also test the code directly with self-registering users.

Preview

To preview the registration inline hook:

In the Admin Console, go to Workflow > Inline Hooks.
Select the registration inline hook name (in this example, select "Guide Registration Hook Code").
Click the Preview tab.
In the Configure Inline Hook request block, select an end user from your org in the data.userProfile field. That is, select a value from your data.user.profile object.
From the Preview example Inline Hook request block, click Generate Request. The user's request information in JSON format that is sent to the external service appears.
From the View service's response block, click View Response. The response from your external service in JSON format appears, which indicates that self-registration was either allowed or denied.

Test

To run a test of your registration inline hook, go to the Okta sign-in page for your Okta org, click the Sign Up link, and attempt to self-register.

If you use an allowable email domain, such as john@example.com, the user registration goes through.
If you use an incorrect email domain, the user registration is denied. Review the error message that displays the error summary from the external service code and is passed back to Okta.

Note: Review Troubleshooting hook implementations if you encounter any set up or configuration difficulties.

Next steps

Review the following guides to implement other inline or event hook examples:

On this page