Integration detail

Overview

This integration guide configures a custom application using the Okta Sign-In Widget and the Onfido SDK to demonstrate how Onfido Identity Verification (IDV) integrates with Okta to create a high trust model using privileged application features.

Prerequisites

Creating and configuring this app integration requires:

• An Okta organization within the okta.com or oktapreview.com domains. You can create a developer org for free.
• An API token created by an administrative account within that domain. See Create an API token. The minimum permission level required to create an Okta API token is "Read Only Administrator".
• An Onfido account. If you don't already have one, you can request a Sandbox Account.
• A NodeJS development environment, version 12 or later.
• A GitHub account.

Procedure

Create an Onfido API token

1. Sign in to your Onfido Dashboard.
2. From the side navigation, click Developers > Tokens.
3. Click Generate API token. You can set the token scope to either Sandbox (recommended for this integration guide) or Live (for production or a live trial). Click Generate.
4. Record the API in a secure location, as you can't retrieve this token value after you exit this window. Click Close.

Add an OpenID Connect app integration

1. In your Okta org, sign in to the Okta Admin Console.
2. From the side navigation, click Applications > Applications.
3. Click Add Application and Create New App.
4. In the App Integration Wizard, select Single Page App (SPA) as the platform. The sign-on method is set automatically to OpenID Connect. Click Create.
5. Give your app integration a unique name and an optional logo.
6. In the Login redirect URIs section, click Add URI. Enter http://localhost:3000/login/callback as the URI.
7. In the Logout redirect URIs section, click Add URI. Enter http://localhost:3000 as the URI.
8. Click Save.
9. On the General tab for the app integration, confirm that the Authorization Code is selected in the Allowed grant types section.
10. In the Assignments tab for the app integration, assign the application to the users or groups you want to have verified by Onfido.

Extend the default Okta user profile

1. In the Okta Admin Console, select Directory > Profile Editor.
2. On the User (default) profile, click Profile.
3. Click Add Attribute and create the following profile attribute:
   • Onfido IDV Status
     • Data type — string
     • Display Name — Onfido IDV Status
     • Variable Name — onfidoIdvStatus
   • Click Save and Add Another
   • Onfido Applicant ID
     • Data type — string
     • Display Name — Onfido Applicant ID
     • Variable Name — onfidoApplicantId
   • Click Save
4. Click Back to profiles.
5. In the Profile Editor, find your Open ID Connect app integration, and click Profile.
6. Repeat step 3 to create these same attributes for the profile in your app integration.

   Note: When creating these attributes in the app integration user profile, select the User personal check box beside the Scope option.

7. Click Back to profiles.
8. Next, add a mapping for the attributes between the default user profile and your app integration user profile. Click Mappings for your app integration. In the Okta User User Profile column, choose the user.onfidoIdvStatus from the drop-down menu that matches with the onfidoIdvStatus row under your {App Name} User Profile. In the middle drop-down menu, select Apply mapping on user create and update.
9. Repeat for the user.onfidoApplicantId row.
10. Click Save Mappings and Apply updates now.

Add a Trusted Origin in Okta

1. From the Okta Admin Console side navigation, click Security > API.
2. Click the Trusted Origins tab.
3. Click Add Origin.
4. Fill in a unique name, along with the origin URL you are using to access the Okta API, including a port number if applicable. For this sample application, the origin URL is http://localhost:3000. Select both the CORS and Redirect options. Click Save to add the trusted origin.

Configuration

The following steps cover the configuration and deployment of a sample application that enables you to test your Onfido and Okta integration.

1. Clone the example application repository from GitHub to a local folder on your system.

2. Open a terminal and change to the base directory where you cloned the repository. All subsequent directory references assume that you are in that directory.

3. In the terminal window, change to the backend/ directory. Then install the necessary packages and create and configure a file to hold the specific environment variables used in the back-end processes:

   cd backend/
   npm install
   touch .env
   

4. Open that .env file in an editor and add the following lines:

   APP_SECRET_KEY=SOME-RANDOM-APP_SECRET_KEY
   OKTA_ORG_URL=https://yourOktaOrgURL
   OKTA_TOKEN=yourOktaApiToken
   ONFIDO_TOKEN=yourOnfidoToken
   PORT=3001
   

   The APP_SECRET_KEY is any long string of random values and is used to secure site cookies. Locate your OKTA_ORG_URL in your Okta Admin Console by opening the drop-down menu from the top right corner and copying the Okta org domain to the clipboard. The OKTA_TOKEN and ONFIDO_TOKEN values are the API tokens you created at the start of this guide. Save this file.

5. Open a second terminal and change to the base directory where you cloned the repository. All subsequent directory references assume that you are in that directory.

6. In the terminal window, change to the frontend directory. Then install the necessary packages used in the front-end processes:

   cd frontend/
   npm install
   

7. Edit the testenv file in your project's base directory (where the backend and frontend folders live) to match the following lines:

   CLIENT_ID=0000000000000000
   ISSUER=https://{your-okta-org}
   OKTA_TESTING_DISABLEHTTPSCHECK=true
   REACT_APP_BACKEND_URL=http://localhost:3001
   

   For the value of these environment variables, enter:

   • CLIENT_ID — In your Okta app integration, click the General tab; this value is the generated Client ID in the Client Credentials pane
   • ISSUER — In your Okta app integration, click the Sign On tab, this value is the Issuer field in the OpenID Connect ID Token pane
   • OKTA_TESTING_DISABLEHTTPSCHECK — For local development, set this to true
   • REACT_APP_BACKEND_URL — The back-end URL, which in this example is http://localhost:3001

Your sample application environment is now ready to run the tests between Onfido and Okta.

Test

1. Launch the back-end process from a terminal window:

   cd onfido-okta-example/backend
   npm start
   

2. From a separate terminal window:

   cd onfido-okta-example/frontend
   npm start
   

When you launch the front end of the sample application, a new browser window opens. THe browser address is http://localhost:3000 and the title is Onfido + Okta Example App.

1. Click the Login button.
2. Sign in to the example application using a valid Okta account which also has the app integration assigned in your Okta org. The application will successfully sign you in and present an authentication message.
3. Click on Profile in the top navigation bar to see your Okta profile information. Note that there are no Onfido claim values in the user profile at this point.
4. In a new browser window or tab, open the Onfido Sandbox test documentation site and download the sample driver's license file to test the identity proofing in the following steps.
5. Click Protected in the top navigation bar to initiate the Identity Proofing test. Click Verify Identity.
6. On the page labeled Verify your Identity, click Verify Identity.
7. Click Driver's license.
8. Click Upload photo - no scans or photocopies. From the file system, select the sample_driving_licence.png file and click Open.
9. Check the image and click Confirm.
10. On the page labelled Submit license (back), click Upload photo - no scans or photocopies. Again, from the file system, select the sample_driving_licence.png file and click Open.
11. Check the image and click Confirm.
12. On the Take a selfie page, click Continue and grant your browser access to the camera. Position your face in the Take a selfie window and click on the white circle. Onfido does not retain your image as part of the sample application testing.
13. Check the selfie picture to confirm that it clearly shows your face, and click Confirm.
14. Onfido verifies the identity based on these inputs and returns an Identity Verified! message. You can click View Profile or Profile in the top navigation bar to see the updated user information. Note that the Onfido verification system has populated both the onfidoApplicantID and onfidoIdvStatus fields.
15. You can confirm the updated data in Okta using the Admin Console. From the side navigation, click Directory > People and then click the name of the person you used to run the test verification. Their Profile tab now has the Onfido fields populated with the same values you saw in the sample application.

Related content

• Onfido - Okta Identity Verification example app on GitHub for complete details
• Onfido - API Reference
• Onfido - Sandbox testing
• Okta and Onfido - Digital access verification video

Support

If you need help or have an issue, post a question in the Okta Developer Forum or the Onfido support site.