Okta API Search Returns 400 Bad Request Invalid Search Criteria When Using Distinguished Name Attribute

An Okta API search for a user using the distinguishedName attribute returns a 400 Bad Request error because the attribute does not exist by default in the Okta user profile. Map the Active Directory attribute to the Okta user profile to resolve the issue. The API search fails and Okta generates the following error when executing a query similar to /api/v1/users?search=profile.distinguishedName eq "<value>":

Invoke-RestMethod : The remote server returned an error: (400) Bad Request.

{
    "errorCode": "E0000031",
    "errorSummary": "Invalid search criteria.",
    "errorLink": "E0000031",
    "errorId": "oaeUFYsVJCtQ7Wjkyj_DbTppQ",
    "errorCauses": [
        {
            "errorSummary": "Invalid search attribute."
        }
    ]
}

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Okta API
• Active Directory (AD)

The distinguishedName attribute (or any other AD attribute) is an AD attribute that does not exist by default in the Okta user profile schema. The Okta User API only searches attributes that exist natively inside the Okta user profile schema. API searches cannot run directly against raw AD attributes. Map the AD attribute into the Okta universal profile using the Okta Directory Profile Editor.

How is the Active Directory attribute mapped to the Okta user profile?

Add the custom attribute to the Okta user profile and map it from the Active Directory app profile to ensure the API search query functions correctly.

1. In the Admin Console, go to Directory, and then select Profile Editor.
2. Select the User (Okta) profile.
3. Select Add Attribute.
4. Complete the required fields, ensuring the Variable name matches the attribute name used in the API search query exactly (for example, distinguishedName).
5. Save the changes.
6. Return to the Profile Editor and select the Active Directory app profile.
7. Select Mappings and choose Active Directory to Okta User.
8. Locate the new distinguishedName Okta attribute on the right, and map it from the Active Directory attribute on the left: appuser.dn.
9. Save the mappings and select Apply mappings now to synchronize and index the data for existing users.