Instructions for

On this page

Registration inline hook

Identity Engine

This guide provides working examples of an Okta registration inline hook for self-service registration (SSR) and Progressive Enrollment support. It uses the web site Glitch.com (opens new window) to act as an external service to receive and respond to registration inline hook calls.

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


Learning outcomes

  • Understand the Okta inline hook calls and responses for SSR and Progressive Enrollment support.
  • Implement working examples of a registration inline hook with a Glitch.com project.
  • Preview and test a registration inline hook for SSR and Progressive Enrollment support.

What you need

Sample code

Okta Registration Inline Hook Example (opens new window)


About registration inline hook implementation

In the following examples, the external service code parses requests from Okta and responds with commands that indicate the following:

  • Whether the end user's email domain is valid and allowed to register (for SSR)
  • Whether the end user's employee number is valid and allowed to be added to their profile (for Progressive Enrollment support)

In these examples, you set up your registration inline hook to handle both SSR and Progressive Enrollment support. It is possible to configure one workflow and not the other. However, by configuring both, you need to set up your code to handle the requests of each workflow. When the end user attempts to self-register or update their profile, Okta dynamically detects the request type. See Enable the registration inline hook.

The following is a high-level workflow for an SSR inline hook:

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

The following is a high-level workflow for a progressive enrollment inline hook:

  1. An existing registered end user attempts to sign in to their profile.
  2. A profile enrollment policy presents a custom form that asks for additional data from the end user.
  3. A registration inline hook triggers during this process and sends a call to the external service with the end user's data.
  4. The external service responds to Okta with a command to allow or deny the addition of the new data to the end user's profile.

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 the request properties of a registration inline hook 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"
    }
}

Progressive enrollment request

The following JSON example provides the end user's profile data to the external service for evaluation.

See the request properties of a registration inline hook 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"
        }
    }
}

Send response

The external service responds to Okta indicating whether to accept the end user's self-registration or 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 self-register or to update their profile with Okta.

In our sample Glitch project, you can see this response in the server.js (opens new window) file.

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

// Registration inline hook code to parse the incoming Okta request

app.post('/registrationHook', async (request, response) => {
  console.log();

  var returnValue = {};

  if (request.body.requestType === 'progressive.profile') {
    // For example, 'employeeNumber' is an additional attribute collected after end user registration.
    console.log('Employee number added to profile ' + request.body.data.context.user.profile['login'] + ': ' + request.body.data.userProfileUpdate['employeeNumber']);
    var employeeNumber = request.body.data.userProfileUpdate['employeeNumber'];
    if (employeeNumber && employeeNumber.length === 4) {
      returnValue = {
        'commands':[
          {
            type: 'com.okta.user.progressive.profile.update',
            value: {
              'employeeNumber': employeeNumber,
            }
          }
        ]
      };
    } else {
      returnValue = {
        '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'
          }]
        }
      };
    }
  } else {
    console.log(request.body.data.userProfile['firstName'] + " " + request.body.data.userProfile['lastName'] + " " + request.body.data.userProfile['email'] + " has registered!");
    var emailRegistration = request.body.data.userProfile['email'];
    if (emailRegistration.includes('example.com')) {
      returnValue = {
        'commands':[
          {
            type: 'com.okta.user.profile.update',
            value: {
              'login': emailRegistration,
            }
          }
        ]
      };
    } else {
      console.log(request.body.data.userProfile['firstName'] + " " + request.body.data.userProfile['lastName'] + " " + request.body.data.userProfile['email'] + " denied registration!");
      returnValue = {
        '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'
          }]
        }
      };
    }
  }

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

Set up, activate, and enable

You must set up, activate, and enable the registration inline hook within your Okta Admin Console.

Set up your Glitch project

You need to remix your own version of the Okta sample Glitch project and confirm that it is live.

  1. Go to the Okta Registration Inline Hook Example (opens new window).
  2. Click Remix your own.
  3. Click Share.
  4. In the Live site field, click the copy icon. This is your external service URL. Make a note of it as you need it later.
  5. Update the project with your own code. For example, you can use the Send response sample in the server.js file.

Set up and activate the registration inline hook

  1. In the Admin Console, go to Workflow > Inline Hooks.

  2. Click Add Inline Hook and select Registration from the dropdown menu.

  3. Add a name for the hook (in this example, use "Guide Registration Hook Code").

  4. Add your external service URL (see Set up your Glitch project), and append it with the endpoint. For example, use your Glitch project name with the endpoint (registrationHook):

    https://your-glitch-projectname.glitch.me/registrationHook

  5. Include the authentication field and secret. In this example:

    • Authentication Field = authorization
    • Authorization Secret = Basic YWRtaW46c3VwZXJzZWNyZXQ=

    Note: If you want to use OAuth 2.0 to secure your inline hooks, see Add Authentication method.

  6. Click Save.

  7. In your Glitch project, click Logs. If your set up is successful, a "Your app is listening on port {XXXX}" message appears.

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.

Set up the employee number attribute

In the Progressive Enrollment example, end users are asked to submit a valid employee number. The employeeNumber attribute is read-only by default. You need to change employeeNumber to read-write.

  1. In the Admin Console, go to Directory > Profile Editor.
  2. Select User (default).
  3. Under Attributes, find Employee Number and click the information icon.
  4. In the Employee Number dialog, under User permission, select Read-Write.
  5. Click Save Attribute.

End users can now update the employee number in their profile.

Enable the registration inline hook

To enable the registration inline hook, you must associate it with a Profile Enrollment policy. In this example, you create an enrollment policy specifically for your hook. See enable and configure a Profile Enrollment policy (opens new window).

Note: Profile Enrollment and registration inline hooks are only supported by the Okta Sign-In Widget version 4.5 or later.

To associate the registration inline hook with a Profile Enrollment policy:

  1. In the Admin Console, go to Security > Profile Enrollment.

  2. Click Add Profile Enrollment Policy.

  3. Give your policy a name (in this example, use "Inline Hook"), and then click Save.

  4. From the list of Enrollment Policies, find Inline Hook and click the pencil icon.

  5. Click Manage Apps, and then click Add Apps to this Policy.

  6. Locate the Okta Admin Console, click Apply, and then click Close.

  7. Click Back to Profile Enrollment Policy.

  8. In Profile enrollment, click Edit.

  9. For Self-service registration, select Allowed.

  10. From the Inline hook dropdown menu, select the hook that you set up and activated earlier. See Set up and activate the registration inline hook.

    Note: You can associate only one inline hook at a time with your Profile Enrollment policy.

  11. In Run this hook, select Both. For our examples, this trigger allows both an SSR request and a Progressive Enrollment data update request.

  12. Click Save.

  13. Under Profile Enrollment Form, click Add form input.

  14. From the dropdown menu, select Employee number.

  15. In the Add form input dialog, under Customize form input, set Input requirement as Optional.

  16. Click Save.

Your registration inline hook is configured for Profile Enrollment. You are now ready to preview and test the example.

Preview the registration inline hook

Your Okta org is set up to call the sample external service using a registration inline hook, and the external service is ready to receive and respond to an Okta call.

In your Okta org, you can preview the request and response JSON in the Admin Console.

  1. In the Admin Console, go to Workflow > Inline Hooks.
  2. Select the registration inline hook name (in this example, select Guide Registration Hook Code).
  3. Click Preview.
  4. 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.
  5. To test an SSR request, under requestType, select Self-Service Registration.
  6. From the Preview example Inline Hook request block, select Generate Request. The end user's request information in JSON format, that is sent to the external service, appears.
  7. Click Edit to update your request before previewing the response. For this example, change the email domain to @example.com.
  8. 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.
  9. To test a profile update, select an end user from your org in the data.userProfile field, and then under requestType select Progressive Profile.
  10. From the Preview example Inline Hook request block, select Generate Request.
  11. Click Edit to update userProfileUpdate:
    "userProfileUpdate": {
       "employeeNumber": "1234"
       }
    

    Note: Make sure that you delete the comma after the value you enter for an employee number. It isn't valid JSON otherwise.

  12. From the View service's response block, click View Response. The response from your external service in JSON format appears, which indicates that the profile update was either allowed or denied.

Test

You can also test the code directly with self-registering or profile-updating end users.

Test the SSR inline hook

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

Note: The Employee number field appears as optional. To test SSR, you can leave Employee number blank.

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

Test the progressive enrollment inline hook

To test the progressive enrollment inline hook, you need to make Employee number required and manually add a user with a password.

  1. Sign in to the Okta Admin Console as an admin.
  2. Go to Security > Profile Enrollment.
  3. Under Profile enrollment form, find Employee number, and then click Edit.
  4. Set the Input requirement to Required.
  5. Click Save.
  6. Go to Directory > People, and then click Add person.
  7. Enter the credentials for your test user and select I will set password.
  8. Enter a password, and then click Save.
  9. Sign out from the Admin Console and sign in with your new @example.com credentials.
  • If you use valid sign-in credentials, the Employee number field appears on the next page.
  • If you enter an employee number in a valid format (4 digits), the update goes through.
  • If you enter an employee number in an invalid format, the update is denied. Review the error message that displays the error summary from the external service code and is passed back to Okta. See error.

Note: Review Troubleshooting hook implementations for help with any difficulties during setup or configuration.

Next steps

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

See also

For a complete description of this inline hook type, see Registration inline hook.