Users migrating from legacy directories such as Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) often require a "silent" migration. This allows end users to sign in to Okta using their existing legacy credentials without requiring a password reset.
While standard documentation provides examples using static arrays, real-world scenarios require a dynamic validation against the legacy source. This article describes how to configure a Password Import Inline Hook to validate credentials against a live external AD/LDAP store during the user's first sign-in.
- Okta Identity Engine (OIE)
- Password Import Inline Hooks
- Active Directory (AD)
- Lightweight Directory Access Protocol (LDAP)
- User Migration Campaigns
Performing a live migration requires hosting an external web service that acts as an intermediary between Okta and the legacy directory.
Step 1: Prepare the External Web Service
Develop a web service (using Node.js with ldapjs or Python with ldap3) that is accessible to Okta via a public HTTPS endpoint.
- Logic: The service must listen for
POSTrequests from Okta. - Extraction: Parse the
data.context.credential.usernameanddata.context.credential.passwordfrom the JSON request body sent by Okta. - Verification: Use these credentials to attempt an LDAP Bind against the AD or LDAP server.
- Security Tip: Ensure the service uses HTTPS/TLS for the endpoint. All communication with the AD/LDAP server should occur over LDAPS (Port 636) to protect cleartext passwords during transit from the hook to the directory.
Step 2: Define the Hook Response
If the LDAP Bind is successful, the service must return an HTTP 200 OK with the following JSON body to tell Okta the password is correct:
{
"commands": [
{
"type": "com.okta.action.update",
"value": {
"credential": "VERIFIED"
}
}
]
}If the Bind fails, the service will return an HTTP 204 No Content or a response indicating the credential is "UNVERIFIED".
Step 3: Register the Hook in Okta
- Log in to the Okta Admin Console.
- Navigate to Workflow > Inline Hooks.
- Click Add Inline Hook and select Password Import.
- Enter a Name (for example, "Legacy AD Migration Hook").
- Enter the URL of the external web service.
- Configure the Authentication field and Authentication Secret to secure the communication between Okta and the hook.
- Click Save.
Step 4: Import Users and Trigger Migration
When importing users into Okta (via API or CSV), ensure the user's credential object is set to use the hook:
- The user must exist in Okta but have no password set.
- The user's credential provider must be set to the Password Import Inline Hook.
- Upon the first successful sign-in, Okta calls the hook, verifies the password against AD, and then securely hashes and stores that password in the Okta profile, completing the migration.
