Troubleshooting
Common failures, and the first things to check for each.
Start with the error in the MIM run history, then match its time against the management agent log and the Windows Application log source Lithnet Okta MA.
Keep two things in mind when troubleshooting. The connector does its real validation when it first connects, so problems with keys, certificates, and scopes surface when you retrieve the schema rather than when you save the page. And a scope is not a permission: the schema can retrieve cleanly, and an import or export can still be refused by Okta.
Installation and configuration
Okta (Lithnet) is not in the management agent list
Close and reopen Synchronization Service Manager. If it is still missing, restart the MIM Synchronization Service. This usually happens when the product was installed or upgraded while the service was running.
The Connectivity page will not save
Fill in every field the selected authentication method requires. Check the tenant URL, the timeout, and the log path.
It works from your workstation but fails in MIM
The service runs as a different account. Check HTTPS_PROXY and NO_PROXY in the machine environment, and restart the service after changing them.
MIM asks for the API token again
This is normal. MIM clears encrypted parameters whenever the page is saved, so enter the token again.
No log file is created
Check the path, and grant the MIM Synchronization Service account write access to the directory.
Tenant URL is rejected
It must be the org root over HTTPS, with no path, query string, or fragment. Not the -admin hostname, an authorization server path, or the token endpoint.
API token
401 Unauthorized
The token value, whether it has expired or been revoked, whether its owning account is still active, network zone restrictions on the token, and the tenant URL.
403 Forbidden
The administrative access of the account that created the token, and whether it covers the object being touched.
OAuth
invalid_client
Client ID, tenant URL, whether the public key is actually registered on the app, that the kid matches, the signing algorithm, and certificate validity.
invalid_scope or consent_required
Grant okta.schemas.read and at least one user or group scope to the service app.
The token is issued but an API call returns 403
Scopes only control what appears in the token. Check the app's admin role and resource set, which control what Okta permits.
Schema retrieves but an export fails
Test the role permission for that specific operation: user, lifecycle, password, group, membership, or delete.
The schema still shows the old access after a scope change
Retrieve the schema again. MIM never refreshes it by itself.
Schema retrieval fails under a custom admin role
Okta doesn't publish a role permission that covers the user profile schema, which the connector needs to read. Standard roles include this access, but a custom role may not.
Private JWK
The path must be fully qualified
Enter a drive-qualified or UNC path. The field takes a path, not the JWK itself.
File not found, or access denied
Check the path, and grant the MIM Synchronization Service account read access to the file.
The JWK is not valid
One private JWK object, not a JWKS with a keys array. Check kid, alg, key type, the private values, UTF-8 encoding, and the 65,536-byte limit.
The key has no private values
The file contains the public JWK. Use the private key instead, which you saved when the key pair was created.
X.509 certificate
Certificate not found
The connector searches CurrentUser\My for the service account, then LocalMachine\My. Your own CurrentUser store is a different store, and the connector cannot see it.
More than one certificate with that thumbprint
Two copies exist in the same store. Remove the one you are not using.
The thumbprint is rejected
It must be exactly 40 hexadecimal characters. Spaces are stripped for you, so pasting from the certificate dialog is fine.
The private key cannot be used
Grant the MIM Synchronization Service account read access to the private key (certlm.msc > All Tasks > Manage Private Keys). For a TPM or HSM, check the provider's own access rules, and that using the key needs no interactive step.
The certificate is not valid
Check NotBefore, NotAfter, and the MIM server's clock.
The key type is not supported
RSA of at least 2048 bits, or EC on P-256, P-384, or P-521.
Okta rejects the assertion after a certificate change
A new certificate means a new thumbprint, and therefore a new kid. Register the new public JWK in Okta. See key rotation.
Schema and imports
A custom user attribute is missing
Add it to the default Okta user profile, then retrieve the schema again.
user or group is missing entirely
Grant the matching read or manage scope, then retrieve the schema again.
Attributes are import-only when you expected to export
Grant the matching manage scope, then retrieve the schema again.
Delta Import says it has no starting point
Run a Full Import for that object type.
The import is slow
Compare the enumeration and processing timings in the log. Then look at the selected factor attributes, group member, import concurrency, object and group sizes, page size, and Okta rate limits.
MIM's imported-object count is higher than the user count
It counts every selected object type together. The log has the separate counts.
Expected groups are missing
Check the object type selection and the Include built-in groups and Include app groups settings.
The import returns nothing at all
Check object type selection, whether the tenant actually holds those objects, the OAuth scopes, the role's resource set, and the group import settings.
Exports
A create failed but the object exists in Okta
Exports are not transactional. A later activation or membership call failed after the create succeeded. Import and reconcile the object rather than retrying the create.
An update to a built-in or app group fails
Only OKTA_GROUP groups are writable. Remove the outbound flows and deletion scoping that reach the others.
Suspension fails
Check the user's current Okta status, and confirm you are exporting suspended rather than status.
A permanent delete is never confirmed
Run a Full Import. A delta import cannot see an object Okta no longer holds.
A membership change returns 403
Membership touches both objects. Check the group and user resource sets, and both membership permissions.
A reprovisioned user is rejected as a duplicate login
The user was deactivated, not deleted, and Okta still holds the login. Reactivate the user in Okta.
Passwords
Password operations never reach the connector
MIM password synchronization configuration, PCNS or the source system, the connector joins, and whether the Okta management agent is selected as a target.
The password is rejected
Okta password policy, the user's status and authentication provider, the credential permissions on the role, and okta.users.manage.
A password change is rejected but a set works
The current password MIM supplied did not match. Everything that applies to a set applies to a change as well.
Last updated