VerifiedKnock
Duo help-desk recovery
Admin API application
Duo Admin Panel → Applications → Application Catalog → Admin API. A Duo Owner creates it. Grant only these permissions:
- Grant administrators - Read, so a Duo administrator can be refused. Do not grant Grant administrators - Write.
- Grant resource - Read and Grant resource - Write, so VerifiedKnock can look up the user, issue one bypass code, and delete that code.
Copy the API hostname (api-xxxxxxxx.duosecurity.com), integration key, and secret key. Save them under Help desk settings → Identity provider → Duo, then tap a security key. Run check. The secret is sealed and is not shown again.
Password behind Duo
Recovery requires Duo as a second factor behind a password. The password can come from Active Directory, Entra, Okta, or Duo Directory with passwords. Passwordless Duo is not supported. An Admin API bypass code is for two-factor authentication only. It cannot satisfy passwordless sign-in or endpoint verification.
Re-enroll policy
The policy on the application where employees re-enroll must allow 2FA bypass codes. For the Duo Self-Service Portal, that is the Default Self-Service Portal Policy, or whichever policy that application actually uses. Allowing bypass codes only on a passwordless policy does not make this work.
Two recoveries, two different people
Path B is lost-key recovery, and it comes first. The employee cannot tap a key. A branch supervisor, in person, and a different HQ help-desk agent each tap a registered FIDO2 security key.
Path A is supervised key replacement, not lost-key recovery. The employee still has a working FIDO2 key and taps it, then one help-desk agent taps a registered FIDO2 security key.
The employee sees one bypass code on their own screen, enrolls a new security key, and tells the help desk.
After the code is used
Finish recovery checks Duo for a new security key by key id, user id, and enrollment time. It records a new authenticator only when one is found and the bypass code is gone. Duo cannot confirm who enrolled the key or its maker. If Duo cannot be read, the screen asks you to try again.
Approver sign-in (Web SDK)
A branch supervisor or HQ help-desk agent signs in with Duo before registering a VerifiedKnock security key. That sign-in uses a Web SDK application (Universal Prompt). It is not the Admin API application, and it must not use that application's integration key.
- Duo Admin Panel → Applications → Application Catalog → Web SDK (the entry labeled 2FA). Add the application.
- Copy the client id, client secret, and API hostname. The API hostname is the same one as the Admin API application (
api-xxxxxxxx.duosecurity.com). - Set the redirect URI to the value VerifiedKnock shows under Help desk settings → Approver company sign-in. Register exactly one of these:
- Staging, including the vk-staging host:
https://staging.verifiedknock.com/v1/helpdesk/approver-oidc/callback - The product host:
https://pass.verifiedknock.com/v1/helpdesk/approver-oidc/callback
- Staging, including the vk-staging host:
- Grant user access to the supervisors and HQ help-desk agents who will accept invites. Do not grant it to everyone. Employees do not need this application.
- Under Universal Prompt, choose Show new Universal Prompt, then save.
Help desk settings → Identity provider → Approver company sign-in. Enter the Web SDK client id, client secret, and a short policy note, then tap your security key. The secret is sealed and is not shown again. VerifiedKnock refuses the client id if it is the Admin API integration key.
The invited person's Duo email must match the invite (capitalization does not matter), unless the invite names that person's Duo user id. The Duo user must be Active. Bypass, disabled, locked out, and pending deletion are refused. A Duo administrator can be a branch supervisor. A Duo administrator cannot be the HQ help-desk agent. After sign-in, the person registers their own VerifiedKnock security key. VerifiedKnock does not enroll a Duo security key for them.
If a secret is exposed
Rotate the Admin API secret key and the Web SDK client secret in the Duo Admin Panel, then save the new values in VerifiedKnock. Disconnect in VerifiedKnock deletes the copy stored there. Delete the Admin API application in the Duo Admin Panel to revoke that application's access.
Approver invite and sign-in errors
The invite page shows the code in parentheses and says what to do next. When company sign-in returns an email, the page names that account and the invite email. It does not show tokens, user ids, or another person's email. Server logs record which check failed, without tokens or secrets.
| Code | What happened | What to do |
|---|---|---|
IDP_IDENTITY_MISMATCH (email differs) | The identity provider session is a different person than the invite. A reused Okta or Microsoft session is the usual cause. | Sign out of Okta or Microsoft, or open a private window, then sign in as the invited email. |
IDP_IDENTITY_MISMATCH (email missing) | Company sign-in did not include an email address. | Confirm the approver sign-in app requests openid, profile, and email, assign the person to that app, then sign in again. |
IDP_IDENTITY_MISMATCH (email not confirmed) | Okta sent email_verified=false, or Microsoft Entra sent an email without a work sign-in name (UPN). | In Okta, verify the email. In Microsoft Entra, sign in with the UPN on the invite. |
IDP_IDENTITY_MISMATCH (account locked on the invite) | The invite was issued for one company account, and a different account signed in. | Sign in as that company account, or ask an admin to send a new invite. |
IDP_IDENTITY_MISMATCH (invite already linked) | This invite is already linked to a company account, and a different account signed in. | Sign in with the account that was used first, or ask an admin to send a new invite. |
IDP_IDENTITY_MISMATCH (already linked elsewhere) | This company account is already the sign-in for a different approver, or this person is already linked to a different company account. | Ask an admin to check Approver Security. Sign in with the invited person's own company account. |
IDP_TENANT_MISMATCH | Sign-in came from a different Okta organization or Microsoft tenant, including a personal Microsoft account. | Sign out or open a private window, then sign in to this organization's directory with the work account. |
IDP_USER_NOT_ACTIVE | The Okta user is not ACTIVE, or Okta could not be checked. | In Okta, set the user to ACTIVE, assign them to the approver sign-in app, then try again. |
IDP_USER_NOT_ACTIVE (Duo) | The Duo user is not Active, is set to Bypass, is locked out, is pending deletion, or could not be checked. | In Duo, set the user to Active (not Bypass) and grant them access to the Web SDK application, then try again. |
IDP_APP_NOT_ASSIGNED | The company account is not assigned to the approver sign-in app. | Assign that person to the VerifiedKnock Approver Sign-In app. Do not assign the app to everyone. Employees do not need it. |
IDP_CONSENT_REQUIRED | An admin has not granted consent for the approver sign-in app. | An Okta admin or a Microsoft Entra administrator grants consent, then the invited person signs in again. |
OIDC_SIGNIN_CANCELLED | Company sign-in was cancelled before it finished. | Return to the invite and choose Sign in with your company account again. |
OIDC_AUTHORIZE_FAILED | The identity provider did not complete sign-in. | Start again from the invite. If it keeps failing, confirm the redirect URI and client id on the approver sign-in app. |
OIDC_STATE_INVALID | The sign-in step expired (10 minutes), was already used, or did not include a code. | Start again from the invite in this browser. |
OIDC_STATE_BROWSER_MISMATCH | Sign-in finished in a different browser than the one that started it. | Open the invite in one browser and finish sign-in there. |
OIDC_TOKEN_EXCHANGE_FAILED | The identity provider did not return a sign-in token. | Start again. If it keeps failing, ask an admin to check the approver sign-in app secret and assignment. |
OIDC_TOKEN_EXPIRED | The company sign-in token expired. | Start again from the invite. |
OIDC_TOKEN_AUDIENCE | Sign-in was issued for a different application. | Use the VerifiedKnock approver sign-in app. Ask an admin to confirm the client id saved in VerifiedKnock. |
OIDC_NONCE_MISMATCH | Sign-in did not match this invite attempt. | Close old sign-in tabs and start again from the invite. |
OIDC_SUBJECT_MISSING | Company sign-in did not include a user id. | Start again. The app must request openid, profile, and email. |
IDP_NOT_CONFIGURED | The organization has no directory connection or no approver sign-in app. | An admin connects the directory and saves the approver sign-in app, then the invited person opens the invite again. For Duo, that app is a Web SDK application, not the Admin API application. |
IDP_SIGNIN_REQUIRED | A security key was offered before company sign-in. | On the invite page, choose Sign in with your company account first. |
DUPLICATE_IDP_SUBJECT | This company account is already linked to another approver. | Ask an admin to check Approver Security. Use the invited person's own company account. |
INVITE_INVALID | The invite link is missing, expired, already accepted, or revoked. The page names which of those the server could see. | Open the link from the invite email. If it is expired, accepted, or revoked, ask an admin to send a new invite. |
KEY_NOT_GENUINE | The key could not be confirmed as a hardware security key. | Use any FIDO2 security key, then try again. |
PASSKEY_TYPE_REFUSED | The passkey can sync or be backed up. | Use a hardware security key that stays on one device, then try again. |
CREDENTIAL_CLASS_UNKNOWN | The security key did not report enough information to register. | Try the hardware key again. If it still fails, ask an admin to confirm the key works with this invite. |
WEBAUTHN_VERIFY_FAILED | The security key could not be verified. | Try again, and enter the PIN or fingerprint if the key asks. If this key is already registered, use a different key. |
RECOVERY_TOKEN_INVALID | The Console recovery link is not valid. | Paste the full link, or ask another Console owner to issue a new one. |
RECOVERY_TOKEN_USED | The Console recovery link was already used. | Ask another Console owner to issue a new link. |
RECOVERY_TOKEN_EXPIRED | The Console recovery link expired. | Ask another Console owner to issue a new link. |
RECOVERY_CODE_INVALID | The email and offline recovery code do not match. | Check the offline code and the Console owner email, then try again. |
APPROVER1_NOT_BRANCH_SUPERVISOR | The person starting recovery is not the branch supervisor for this employee. | Ask that branch supervisor to start it, or use HQ fallback if it is turned on. |
SELF_SERVICE_FORBIDDEN | An approver tried to approve their own recovery. | Ask a different approver to continue. |
PRIVILEGED_TARGET | The employee is an organization owner or admin. | Use your organization's privileged-access process for this account. |
Support
- Setup for an organization that already has Duo connected: [email protected]
- Security reports: [email protected]
- More on the Support page.