Configuring Custom Claims Mapping for Incode IDV in Okta

Overview

When integrating Incode Identity Verification (IDV) with Okta, you can customize which user attributes are sent for verification.

By default, Okta uses the firstName and lastName fields in the user profile. However, if your organization stores legal names in custom fields (such as user.LegalFirstName and user.LegalLastName), mapping these attributes to Incode ensures more accurate matches and reduces the number of manual review cases.

🔧 Prerequisites

Before you begin, ensure that:

The Incode IDV app integration is already created and configured in Okta.
You have admin access to your Okta tenant.
Your custom fields (e.g. LegalFirstName, LegalLastName) are defined in the Okta Universal Directory user schema.

⚙️ Step-by-Step Configuration

1. Navigate to the Incode IDV Integration

In your Okta Admin Console, go to Security → Identity Providers.
Locate Incode IDV in the list.
Click Edit to open the configuration panel.

2. Edit Profile & Mappings

Under the Incode IDV section, click Edit Profile & Mappings.
Scroll to the User Profile section.
Click Edit Mappings to open the attribute mapping interface.

3. Configure Attribute Mappings

In this screen, you will map Okta user attributes to Incode IDV user attributes.

Okta Attribute (Source)	Incode Attribute (Target)	Description
`user.LegalFirstName`	`givenName`	Maps the legal first name stored in Okta to the given name used for ID verification
`user.LegalLastName`	`familyName`	Maps the legal last name stored in Okta to the family name used for ID verification

Tip: The username is automatically managed by Incode IDV and should not be modified in this mapping.

Your mapping table should look like this:

4. Save and Confirm the Mapping

Click Save Mappings to apply your changes.
Return to the Identity Providers page.
Test the configuration by triggering an identity verification flow for a user whose legal name differs from their display name.

Expected Results

Once configured, Okta will send the Legal First Name and Legal Last Name to Incode IDV for verification. This alignment minimizes false mismatches caused by nickname or preferred name variations and reduces manual review volume in the Incode dashboard.

Additional Notes

Any updates to Okta user profiles will automatically sync to Incode on the next verification request.
For debugging, check the Okta System Log to confirm that the correct attributes are being passed to Incode.