Instructions for

On this page

Registration inline hook

Identity Engine

This guide provides examples of an Okta registration inline hook for profile enrollment (self-service registration) and progressive profile enrollments. 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. The sample project provides external code for three registration inline hook use cases:

  • A simple profile enrollment (self-service registration)
  • Progressive profile enrollment updates
  • Profile enrollment and progressive profile enrollments together

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 profile enrollment (SSR) and progressive profile enrollment.
  • Implement examples of a registration inline hook with a Glitch.com project.
  • Preview and test a registration inline hook for profile enrollment (SSR) and progressive profile enrollment.

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 profile enrollment)
  • Whether the end user's employee number is valid and allowed to be added to their profile (for progressive profile enrollment)

In these examples, you set up your registration inline hook to handle either the simple profile enrollment (SSR) scenario, progressive profile enrollment scenario, or both. You configure a profile enrollment policy to define these scenarios and implement the registration hook. The registration hook customizes how to add new users to your Okta org or update the profiles of existing users.

The following is a high-level workflow for the profile enrollment (self-service registration) scenario:

  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 the domain okta.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 profile enrollment scenario:

  1. An existing registered end user attempts to sign in to their profile.
  2. A profile enrollment policy presents a custom sign-in form that asks for extra 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.

Profile enrollment (self-service registration) requests

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.

Note: The requestType is self.service.registration.

{
    "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 profile enrollment requests

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.

Note: The requestType is progressive.profile.

{
    "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"
        }
    }
}

Set up for profile enrollment (SSR) scenario

The simple scenario of profile enrollment (self-service registration) involves new users self-registering from the Sign up link with the default three sign-up fields (Email, First name, and Family name). With this use case, the registration inline hook triggers and evaluates the domain in the Email field. If the domain is from okta.com, the user can register. If not, the user is denied registration. To implement this scenario:

Set up your external service code response for profile enrollment

You need to remix your own version of the Okta sample Glitch project and confirm that it's 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. Click Logs. If you see the following message, "Your app is listening on port {XXXX}", the app is live and ready to receive Okta requests.

In the following code, the external service responds to Okta indicating whether to accept the end user's self-registration. 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 self-registration.

app.post('/registrationHookSSR', async (request, response) => {
  console.log();
  console.log("Type of Okta registration hook request: " + request.body.requestType); // confirms the type of Okta request
  var returnValue = {};

  if (request.body.requestType === 'self.service.registration') {
    var emailRegistration = (request.body.data.userProfile['login']).split('@');
    if (emailRegistration[1].includes('okta.com')) {
      console.log(request.body.data.userProfile['firstName'] + " " + request.body.data.userProfile['lastName'] + " " + request.body.data.userProfile['email'] + " has registered!");
      returnValue = {
        'commands':[
          {
            type: 'com.okta.action.update',
            value: {
              'registration': 'ALLOW',
            }
          }
        ]
      };
    } 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 okta.com emails can register.',
            'reason':'INVALID_EMAIL_DOMAIN',
            'locationType':'body',
            'location':'data.userProfile.email',
            'domain':'end-user'
          }]
        }
      };
    }
  }

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

Add your registration hook for profile enrollment

Configure your registration inline hook for your Okta org to use the glitch project for profile enrollment (SSR).

  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 "Profile Enrollment SSR").

  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 (registrationHookSSR):

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

  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 the Add Authentication method.

  6. Click Save.

Create an enrollment policy for profile enrollment (SSR)

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 Dashboard, 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 Add your registration hook for profile enrollment.

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

  11. In Run this hook, select When a new user is created.

  12. Click Save.

Your registration inline hook is configured for profile enrollment (self-service registration). Go to the Preview the registration inline hook or Test your registration inline hook to preview and run the sample.

Set up for progressive profile enrollment scenario

The scenario of progressive profile enrollment involves existing users prompted for new information to add to their profile when they sign in. With this use case, the registration inline hook triggers and the external service code evaluates the employee number field. If the value is four digits, the user's profile is updated. To implement this scenario:

Set up your external service code response for progressive profile enrollment

You need to remix your own version of the Okta sample Glitch project and confirm that it's 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. Click Logs. If you see the following message, "Your app is listening on port {XXXX}", the app is live and ready to receive Okta requests.

Review the following project code with endpoint /registrationHookPP. The external service responds to Okta indicating whether to update the end user's profile with a valid employee number. 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 to update their Okta profile.

app.post('/registrationHookPP', async (request, response) => {
  console.log();
  console.log("Type of Okta registration hook request: " + request.body.requestType); // confirms the type of Okta request
  var returnValue = {};

  if (request.body.requestType === 'progressive.profile') {
    var employeeNumber = request.body.data.userProfileUpdate['employeeNumber'];
    if (employeeNumber && employeeNumber.length === 4) {
      console.log(request.body.data.context.user.profile['firstName'] + ' ' + request.body.data.context.user.profile['lastName']+ " " + request.body.data.context.user.profile['login'] + " has updated profile!");
      returnValue = {
        'commands':[
          {
            type: 'com.okta.user.progressive.profile.update',
            value: {
              'employeeNumber': employeeNumber,
              'mobilePhone': request.body.data.userProfileUpdate['mobilePhone']
            },
          }
        ]
      };
    } else {
      console.log(request.body.data.context.user.profile['firstName'] + ' ' + request.body.data.context.user.profile['lastName']+ " " + request.body.data.context.user.profile['login'] + " employee number is not the correct number of digits!");
      returnValue = {
        'commands':[
        ],
        'error': {
          'errorSummary':'Incorrect employee number. Enter an employee number with 4 digits.',
          'errorCauses':[{
            'errorSummary':'Employee numbers must have 4 digits.',
            'reason':'INVALID_EMPLOYEE_NUMBER',
            'locationType':'body',
            'location':'data.userProfile.employeeNumber',
            'domain':'end-user'
          }]
        }
      };
    }
  }

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

})

Add your registration hook for progressive profile

Configure your registration inline hook for your Okta org to use the glitch project for progressive profile enrollment.

  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 "Progressive Profile Enrollment").

  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 (registrationHookPP):

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

  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 the Add Authentication method.

  6. Click Save.

Create an enrollment policy for progressive profile enrollment

Before creating the enrollment policy, ensure the user profile attribute employeeNumber is set to a status of read-write. The employeeNumber attribute is read-only by default.

  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.

To associate the registration inline hook with a profile enrollment policy and add the employee number field:

  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 Dashboard, 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 Denied.

  10. For Progressive Profiling, select Enabled.

  11. From the Inline hook dropdown menu, select the hook that you set up and activated earlier. See Add your registration hook for progressive profile enrollment.

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

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

  13. From the dropdown menu, select the Employee number.

  14. In the Add form input dialog, under Customize form input, set the Input requirement as Required.

  15. Click Save

Your registration inline hook is configured for progressive profile enrollment. Go to Preview the registration inline hook or Test your registration inline hook to preview and run the sample.

Set up for profile enrollment (SSR) and progressive profile enrollment scenario

This scenario involves both profile enrollment (self-service registration) and progressive profile enrollment use cases. Existing users are prompted for new information (a four-digit employee number) to add to their profile when they sign in. New users self-registering from the Sign up link are required to include the default three sign-up fields (Email, First name, and Family name) and the employee number field. With this use case, the external code updates the profiles of existing users if the employee number is four digits. The external code adds new users if their email domain contains okta.com and their employee number is four digits, otherwise their registration is denied. To implement this scenario:

Set up your external service code response for profile and progressive profile enrollment

You need to remix your own version of the Okta sample Glitch project and confirm that it's 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. Click Logs. If you see the following message, "Your app is listening on port {XXXX}", the app is live and ready to receive Okta requests.

Review the following project code with endpoint /registrationHookSSRandPP. The external service responds to Okta indicating whether to update the end user's profile with a valid employee number or allow a self-registration of a new user. 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 self-registration or can update their profile with Okta.

app.post('/registrationHookSSRandPP', async (request, response) => {
  console.log();
  console.log("Type of Okta registration hook request: " + request.body.requestType); // confirms the type of Okta request
  var returnValue = {};

  if (request.body.requestType === 'progressive.profile') {
    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 {
    var emailRegistration = (request.body.data.userProfile['email']).split('@');
    var employeeNumberSSR = (request.body.data.userProfile['employeeNumber']);
    if (emailRegistration[1].includes('okta.com') && (employeeNumberSSR && employeeNumberSSR.length === 4)){
      console.log(request.body.data.userProfile['firstName'] + " " + request.body.data.userProfile['lastName'] + " " + request.body.data.userProfile['email'] + " has registered!");
      returnValue = {
        'commands':[
          {
            type: 'com.okta.action.update',
            value: {
              'registration': 'ALLOW',
            }
          }
        ]
      };
    } 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 or employee number. Please contact your admin.',
          'errorCauses':[{
            'errorSummary':'To register, you must have an "okta" email and a 4-digit employee number.',
            'reason':'INVALID_EMAIL_DOMAIN',
            'locationType':'body',
            'location':'data.userProfile.email',
            'domain':'end-user'
          }]
        }
      };
    }
  }

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

Add your registration hook for profile and progressive profile enrollment

Configure your registration inline hook for your Okta org to use the glitch project for both profile enrollment (self-service registration) and progressive profile enrollment.

  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 "Profile and Progressive Profile Enrollment").

  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 (registrationHookSSRandPP):

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

  5. Add the Authentication field and Authentication secret values. This example uses HTTP Basic Authentication.

    • Authentication field = authorization
    • Authentication secret = Basic YWRtaW46c3VwZXJzZWNyZXQ=

    Note: If you want to use OAuth 2.0 to secure your inline hooks, see OAuth 2.0: Client Secret or OAuth 2.0: Private Key.

  6. Click Save.

Create an enrollment policy for profile and progressive profile enrollment

Before creating the enrollment policy, ensure the user profile attribute employeeNumber is set to a status of read-write. The employeeNumber attribute is read-only by default.

  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.

To associate the registration inline hook with a profile enrollment policy and add the employee number field:

  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 Dashboard, 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. For Progressive Profiling, select Enabled.

  11. From the Inline hook dropdown menu, select the hook that you set up and activated earlier. See Add your registration hook for progressive profile enrollment.

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

  12. In Run this hook, select Both.

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

  14. From the dropdown menu, select the Employee number.

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

  16. Click Save

Your registration inline hook is configured for both profile and progressive profile enrollment. Go to Preview the registration inline hook or Test your registration inline hook to preview and run the sample.

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.

To preview a profile enrollment (self-service registration) request and response:

  1. In the Admin Console, go to Workflow > Inline Hooks.
  2. Select the registration inline hook name that you created.
  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. 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. Optional: Click Edit to update your request before previewing the response. For this example, you can change the email domain to view a response that accepts or denies the registration. That is, a user registering with an okta.com email or not. Click Save.
  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. You can also review the console output from your Glitch application's Logs.

To preview a progressive profile enrollment request and response:

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

  2. Select the registration inline hook name that you created.

  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. Under requestType, select Progressive Profile.

  6. From the Preview example Inline Hook request block, select Generate Request.

  7. Click Edit to update userProfileUpdate and add a value for the employeeNumber attribute (either four digits or larger based on the use case you want to preview):

    "userProfileUpdate": {
       "employeeNumber": "1234"
       }
    

    Note: Make sure that your edits are valid JSON.

  8. 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 your registration inline hook

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

Test the profile enrollment (self-service registration) inline hook

To run a test of your profile enrollment (self-service registration) 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 rosario.jones@okta.com, the end user registration goes through for the profile enrollment scenario.
  • If you use an allowable email domain and employee number, the end user registration goes through for the profile and progressive profile enrollment scenario.
  • If you use an incorrect email domain or employee number (depending on the scenario), 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 the Okta sign-in page. See error. You can also review the console output from your Glitch application's Logs.

Test the progressive enrollment inline hook

To run a test of your progressive profile enrollment registration inline hook, create (opens new window) or use an existing user in your org.

  • If you use valid sign-in credentials with an Employee number value of four digits, the user's profile is updated.
  • If you enter an employee number in an invalid format, the profile update is denied.

Sign back in as your org admin to review the profile of the user and confirm that the user's profile was updated and the employee number value exists.

For invalid, employee numbers review the error message that displays the error summary from the external service code and is passed back to the Okta sign-in page. See error. You can also review the console output from your Glitch application's Logs.

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.