VerifiedKnock Pass · Documentation

Microsoft Entra ID setup

Single sign-on (OpenID Connect) and help-desk permissions for VerifiedKnock Pass.

What VerifiedKnock Pass does with Microsoft Entra ID

Sign in with Microsoft (SSO). Console staff can start sign-in with their work account. Protocol: OpenID Connect, authorization code flow with PKCE, Microsoft identity platform v2.0, multitenant (/organizations endpoint), confidential client. Scopes: openid profile.
A security key is always required. After Microsoft sign-in, the person must also tap their enrolled FIDO2 security key, with PIN or fingerprint. Microsoft sign-in alone never opens the console. People who only use their security key can keep doing that.
Account matching. VerifiedKnock matches people by the immutable Microsoft Entra tenant ID and object ID (tid + oid claims). Email address and UPN are never used to match.
Help-desk actions (optional). After a verified Match for one account and one action, and after the final policy checks, the agent can issue one Temporary Access Pass or remove one lost authenticator in your tenant. Path A (the employee has their FIDO2 key; required for high-risk accounts): the employee taps that key, then an authorized help-desk agent taps theirs. Path B (the key is lost or was never issued): an in-person branch supervisor taps their own key, then a different authorized help-desk agent taps theirs. No employee key is required on Path B, and Path B is not permitted for high-risk accounts. A Match is evidence, not permission to run the action. This needs one-time admin consent to the application permissions below.

Supported: work or school accounts in any Microsoft Entra tenant. Not supported for the console: personal Microsoft accounts. User provisioning (SCIM) is not offered. VerifiedKnock is sold by subscription; Microsoft Entra ID licensing is your own. Temporary Access Pass availability depends on your Microsoft licensing and authentication-method policy.

VerifiedKnock does not check ID documents. Your organization decides how supervisors identify employees in person.

Roles you need

Task	Microsoft Entra role
Staff sign-in (`openid profile`) when your tenant allows user consent	None. Each user consents for themselves.
Staff sign-in when user consent is restricted	Cloud Application Administrator, Application Administrator, or Global Administrator grants consent once
Connect help-desk actions (Graph application permissions)	Privileged Role Administrator or Global Administrator
Enable Temporary Access Pass and set its lifetime	Authentication Policy Administrator
VerifiedKnock console	An owner or admin in your VerifiedKnock organization

Step 1: Turn on Sign in with Microsoft for a staff member

Your VerifiedKnock admin invites the person. They enroll a FIDO2 security key during the invite.
The person signs in at pass.verifiedknock.com/platform/login with their security key, opens Security keys, and selects Link Microsoft account.
They sign in with their work account. Microsoft may ask them to consent to “Sign you in and read your profile”.
Next time: Sign in with Microsoft → work account → tap security key. Unlink any time from Security keys.

Someone signing in with Microsoft for the first time who has not been invited and linked is turned away with the code MS_NOT_LINKED. VerifiedKnock never creates console accounts from a Microsoft sign-in.

Two help-desk recovery paths

Help-desk recovery uses one path or the other. The verification session lasts 10 minutes and is bound to one account and one action.

Path A: the employee has their key

Required for high-risk accounts. The employee’s FIDO2 key is required. First approval: the employee taps their own key. Second approval: an authorized help-desk agent taps their own key.

Path B: the key is lost or was never issued

The employee’s FIDO2 key is not required, and Path B does not ask the employee to tap a key. First approval: an authorized branch supervisor, with the employee in person, taps their own key. Second approval: a different authorized help-desk agent taps their own key. High-risk accounts use Path A only. This policy does not permit Path B for high-risk accounts.

Either path

One verified Match allows at most one recovery action: issue one Temporary Access Pass, or remove one lost method, after the final policy checks.
A Match is evidence. It is not permission to run the action. Your staff and your policy decide.
A QR code only starts or joins the session. It does not authorize the recovery on its own.
The recovery credential is shown once, on the employee’s screen. Neither approver sees it. VerifiedKnock does not store it.
Disabled accounts, guest accounts, and directly assigned admin-role accounts are refused. Eligibility is checked before the verification is created and again immediately before the recovery action. If a check cannot run, nothing happens.

Who needs a FIDO2 security key

Supervisors, help-desk agents, and high-risk employees need a FIDO2 security key (security keys are not included). Other employees need a key for Path A. Path B does not require an employee key.

Path A applies when the employee has their FIDO2 key, and it is required for high-risk accounts. The employee taps that key, then an authorized help-desk agent taps theirs. Path B applies when the key is lost or was never issued. No employee key is required on Path B. An in-person branch supervisor taps their own key, then a different authorized help-desk agent taps theirs. High-risk accounts use Path A only. Security keys are not included. If a supervisor or help-desk agent loses their key, they re-enroll at a supervised enrollment. Path B helps an employee whose key is lost or was never issued: the branch supervisor and a different help-desk agent tap their own keys.

Requirement: supervisors, help-desk agents, and high-risk employees need a FIDO2 security key (not included). Other employees need a key for Path A. Path B does not require an employee key.

Step 2: Connect help-desk actions (admin consent)

In the VerifiedKnock console, open Help desk → Settings and select Connect Microsoft Entra ID.
A Privileged Role Administrator or Global Administrator reviews the permissions below and selects Accept.
The same admin signs in once more so VerifiedKnock can confirm the tenant that granted consent.
The console runs a health check. It reports the permissions present, whether they are the least-privilege set, and whether target screening (the two read permissions) is ready. Until it is, every help-desk action is refused with GRAPH_PERMISSION_MISSING.
Enroll FIDO2 keys for branch supervisors, help-desk agents, and high-risk employees before they handle recoveries (see above). Other employees need a key for Path A only.
In Account Recovery → Branches & supervisors, assign at least one branch supervisor and assign your help-desk agents to HQ. Path B needs that branch supervisor plus a different help-desk agent, two different people with two different keys, and cannot be used until a supervisor is assigned. High-risk accounts use Path A only.
Make sure Temporary Access Pass is enabled for the users you want to support (Entra admin center → Authentication methods → Policies → Temporary Access Pass).

Permissions and why we need them

For help desk, VerifiedKnock Pass asks for five application permissions: three narrow write permissions to manage temporary access passes, passkeys, and Microsoft Authenticator methods, and two read-only permissions to screen the target account before the verification is created and again immediately before the recovery action. It cannot read mail, files, calendars or passwords, and it cannot change users, groups or roles.

VerifiedKnock enforces agent roles itself and refuses directly assigned admin, disabled and guest accounts. Before a verification is created, and again immediately before the recovery action, VerifiedKnock resolves the UPN to the Entra object ID and refuses disabled accounts, guest accounts, and directly assigned admin-role accounts. If a check cannot run, nothing happens. Actions are sent to Microsoft Graph by object ID, and a key enrolled for one object ID never authorizes another. The recovery credential is shown once on the employee’s screen. Neither approver sees it. The pass is shown once, on the verified caller's own screen. VerifiedKnock never stores or logs the pass, and the agent never sees it.

Permission	Type	Microsoft Graph call	Business justification
`openid`	Delegated	`OpenID Connect sign-in (ID token)`	Sign in with Microsoft for console staff. Lets VerifiedKnock confirm who signed in.
`profile`	Delegated	`OpenID Connect sign-in (name, preferred_username claims)`	Shows the signed-in person’s name on the security-key step. Not used to match accounts.
Manage temporary access passes `UserAuthMethod-TAP.ReadWrite.All`	Application	`POST /users/{id}/authentication/temporaryAccessPassMethods`	Issue one Temporary Access Pass only after a verified Match for one account and one action, and only after the final policy checks. Path A (the employee has their FIDO2 key; required for high-risk accounts): the employee taps that key, then an authorized help-desk agent taps theirs. Path B (the key is lost or was never issued; not permitted for high-risk accounts): an in-person branch supervisor taps their own key, then a different authorized help-desk agent taps theirs. No employee key is required on Path B. The pass is shown once on the employee’s screen. Neither approver sees it, and VerifiedKnock does not store it. A Match is evidence, not permission to run the action. The pass is shown once, on the verified caller's own screen. VerifiedKnock never stores or logs the pass, and the agent never sees it.
Manage passkeys `UserAuthMethod-Passkey.ReadWrite.All`	Application	`GET /users/{id}/authentication/fido2Methods; DELETE /users/{id}/authentication/fido2Methods/{id}`	List a verified caller’s security keys so the agent can pick the right one, and remove one lost or compromised key after a verified Match and the final policy checks. One Match allows at most one recovery action. A Match is evidence, not permission to run it.
Manage Microsoft Authenticator methods `UserAuthMethod-MicrosoftAuthApp.ReadWrite.All`	Application	`GET /users/{id}/authentication/microsoftAuthenticatorMethods; DELETE …/microsoftAuthenticatorMethods/{id}`	List Microsoft Authenticator registrations and remove one lost or replaced registration after a verified Match and the final policy checks. One Match allows at most one recovery action. A Match is evidence, not permission to run it.
Read all users’ basic profiles (read-only) `User.Read.All`	Application	`GET /users/{upn}?$select=id,userPrincipalName,accountEnabled,userType`	Before a verification is created, and again immediately before the recovery action, resolve the caller’s work sign-in (UPN) to their immutable Entra object ID and refuse disabled and guest accounts. VerifiedKnock reads only these fields and stores only the object ID.
Read your directory’s role assignments (read-only) `RoleManagement.Read.Directory`	Application	`GET /roleManagement/directory/roleAssignments`	Before a verification is created, and again immediately before the recovery action, refuse accounts with a directly assigned Microsoft Entra admin role. Read-only: VerifiedKnock can never change roles.

Why application (app-only) rather than delegated permissions? The recovery action follows the two-person security-key verification for the path in use. Path A is the employee and an authorized help-desk agent. Path B is a branch supervisor and a different authorized help-desk agent. It does not follow the agent’s directory role. A verified Match is evidence for that one account and one action. It allows at most one recovery action, and only after the final policy checks. With delegated permissions every agent would need an Entra admin role such as Authentication Administrator, which is exactly the kind of standing privilege help-desk attackers target, and the checks would depend on who happens to be signed in. App-only lets VerifiedKnock run the same screening for every agent, keep agents out of Entra admin roles, and enforce its own agent roles, deny list and audit trail. VerifiedKnock calls Graph for the recovery action after a verified Match, the agent’s decision, and the final policy checks. Your admin can withdraw consent at any time.

Earlier versions asked for the broader UserAuthenticationMethod.ReadWrite.All. If your tenant consented before this change, reconnect (step 2) to grant the narrower permissions and the two read permissions above. Then remove the old permission in Entra admin center → Enterprise applications → VerifiedKnock Pass → Permissions. Help-desk actions stay blocked until both read permissions are consented.

VerifiedKnock signs in to Microsoft as a confidential (server-side) client. It does not read user mail, files, passwords, or sign-in logs.

Test it

Create or pick a pilot user in a test tenant. Path A uses a user with a FIDO2 key enrolled in VerifiedKnock. Path B uses a user whose key is lost or was never issued, with a branch supervisor and a different help-desk agent. High-risk accounts use Path A only.
Link Microsoft (step 1), sign out, then sign in with Microsoft and tap the key. You should land in the console.
Try Sign in with Microsoft with an unlinked user. You should see MS_NOT_LINKED.
For help desk: run the health check in Help desk → Settings, then issue a Temporary Access Pass for the pilot user after a verified Match.

Disconnect or remove

One person: Security keys → Unlink Microsoft.
Help-desk actions: Help desk → Settings → Disconnect.
Everything: Entra admin center → Enterprise applications → VerifiedKnock Pass → Properties → Delete. This removes consent and all permissions in your tenant.

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_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.
`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 a hardware security key (for example a YubiKey), 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.

Troubleshooting

Code	What it means	What to do
`MS_NOT_LINKED`	The Microsoft account is not linked to a console account.	Sign in with your security key, open Security keys, choose Link Microsoft account. New staff need an invite from your VerifiedKnock admin first.
`MS_PERSONAL_ACCOUNT`	A personal Microsoft account (outlook.com, hotmail.com) was used.	Use your work or school account.
`MS_ACCESS_DENIED`	Sign-in was cancelled, or consent was declined.	Try again. If your tenant blocks user consent, ask an admin to grant consent (see step 1).
`MS_CONSENT_REQUIRED / AADSTS65001 / AADSTS90094`	Your organization requires an administrator to approve the app.	An Application Administrator or Global Administrator grants consent for VerifiedKnock Pass in Microsoft Entra admin center → Enterprise applications.
`MS_STATE_EXPIRED / MS_STATE_REUSED / MS_STATE_BROWSER_MISMATCH`	The sign-in request expired (10 minutes), was already used, or was finished in a different browser.	Start again from the sign-in page in the same browser.
`MS_IDTOKEN_*`	Microsoft’s response could not be verified (signature, audience, issuer, nonce, or expiry).	Try again. Check the device clock. If it persists, contact support with the code and time.
`MS_USER_INACTIVE`	The linked console account is disabled.	Ask your organization admin.
`NO_CREDENTIALS / UV_REQUIRED / WEBAUTHN_VERIFY_FAILED`	The required security-key step failed: no key enrolled, PIN or fingerprint not used, or an unrecognized key.	Use your enrolled FIDO2 key and complete its PIN or fingerprint check. Lost every key? Use Recover access.
`AADSTS50011`	Redirect URI mismatch (VerifiedKnock configuration).	Contact support. No action is needed in your tenant.
`AADSTS700016`	The app is not available in the tenant you signed in to.	Check that you are signing in with the right work account. An admin may need to consent first.
`ENTRA_TENANT_IN_USE`	That Microsoft tenant is already connected to another VerifiedKnock organization.	Disconnect it there first, or contact support.
`tenant_mismatch`	The admin who confirmed the connection signed in to a different tenant than the one that granted consent.	Restart Connect and sign in with an admin of the same tenant.
`ENTRA_STATE_* (connect)`	The connect request expired or was started from another session.	Start Connect again from the console.
`ENTRA_NOT_CONNECTED`	Help-desk actions were attempted before Microsoft Entra was connected.	Complete step 2.
`GRAPH_PERMISSION_MISSING`	User.Read.All or RoleManagement.Read.Directory is not granted, so VerifiedKnock cannot check the target account. Every help-desk action is blocked (fail closed).	An admin grants admin consent to both read permissions (reconnect in step 2), then runs the health check.
`PRIVILEGED_TARGET`	The target account has a directly assigned Microsoft Entra admin role.	Recover directly assigned admin-role accounts through your own privileged-access process, not the help desk.
`TARGET_DISABLED / TARGET_GUEST`	The target account is disabled, or is a guest (B2B) account.	Enable the account first, or send guests to their home organization.
`TARGET_IDENTITY_MISMATCH`	The UPN now points to a different Entra object than the one the caller’s key was enrolled for (for example, a reused UPN).	Do not proceed. Re-enroll the person under supervision.
`TARGET_UPN_REQUIRED`	The agent typed something other than a work sign-in (UPN).	Enter the caller’s UPN, for example [email protected].
`graph_403 Authorization_RequestDenied`	A required Graph permission is not granted in your tenant (for example after a permission update).	Re-grant admin consent (step 2) and run the health check.
`graph_400 (Temporary Access Pass)`	The TAP method is disabled in your tenant, the user is not in scope, or the lifetime is outside your TAP policy.	An Authentication Policy Administrator enables Temporary Access Pass for the target users and checks its minimum and maximum lifetime.
`RATE_LIMITED`	Too many attempts from one network.	Wait a minute and try again.
`IDP_IDENTITY_MISMATCH`	The company account that signed in is not the invited approver. A reused identity-provider session, a user who is not assigned to the approver app, or an email that is not an exact match all end here.	The company account that signed in is not the invited person. Sign out of Okta or Microsoft, or open a private window, then sign in as the invited person. A person who is not assigned to the approver sign-in app cannot complete this step. The email must match the invite exactly, and the account must be active.
`IDP_TENANT_MISMATCH`	Company sign-in came from a different Microsoft tenant, including a personal Microsoft account.	Company sign-in came from a different organization. Sign out of Okta or Microsoft, or open a private window, then sign in to this organization's directory.
`IDP_USER_NOT_ACTIVE`	The directory user is not ACTIVE, so the invite cannot be accepted.	This company account is not active. In Okta, set the user to ACTIVE and assign them to the approver sign-in app, then sign in again. The email must match the invite exactly.

Approver company sign-in

A new branch supervisor or HQ help-desk agent signs in with their company account before registering a security key. That sign-in uses a separate Entra app registration with only the delegated scopes openid, profile and email. It is not the Microsoft Graph help-desk app listed below (0807863f-f137-4a05-aac7-28d170ac4467). Do not add this redirect URI to the Graph app, and do not use the Graph app’s client id for approver sign-in.

On the sign-in app, add a Web platform redirect URI of exactly https://pass.verifiedknock.com/v1/helpdesk/approver-oidc/callback. Then save that app’s client id and secret in VerifiedKnock under Help desk settings, Identity provider. The secret is stored encrypted and is not shown again.

Onboard approvers

Branch supervisors and HQ help-desk agents must sign in with the company account you invited before they can register a security key. Employees do not need the approver sign-in app and stay out of this group. Use one email per role in the organization. The organization admin should not also be an approver.

In Microsoft Entra admin center, create a security group named VerifiedKnock Approvers.
Register a separate app registration for approver sign-in. It is not the Microsoft Graph help-desk app (0807863f-f137-4a05-aac7-28d170ac4467). Delegated scopes are only openid, profile and email. Use authorization code with PKCE. On that app, add a Web platform redirect URI of exactly https://pass.verifiedknock.com/v1/helpdesk/approver-oidc/callback.
Enter that app’s client id in VerifiedKnock under Help desk settings, Identity provider. Do not paste the Graph app’s client id. Assign this sign-in app to the VerifiedKnock Approvers security group. Do not assign it to the whole company.
Entra matches the invite to the user principal name (preferred_username or upn). Invite each supervisor and HQ agent by that exact UPN. A different mailbox does not match.
Add each supervisor and HQ agent to VerifiedKnock Approvers with exactly the invited email. Leave employees out of the group.
The invited person accepts the invite in a fresh private window, signed in to Microsoft Entra as that exact user. Personal Microsoft accounts and Gmail accounts are refused.
An owner or admin then confirms that person in Workforce > Approver Security with their own hardware key.

Technical reference

Application (client) ID	`0807863f-f137-4a05-aac7-28d170ac4467`
Authority	`https://login.microsoftonline.com/organizations/v2.0`
Sign-in redirect URI	`https://pass.verifiedknock.com/v1/platform/auth/microsoft/callback`
Connect (admin consent) redirect URI	`https://pass.verifiedknock.com/v1/helpdesk/entra/callback`
Flow	Authorization code + PKCE (S256), confidential client
Scopes requested at sign-in	`openid profile`
User matching claims	`tid` + `oid`
Sign-in page	https://pass.verifiedknock.com/platform/login

Need help?

Email [email protected]. Security reports: [email protected]. More on the Support page. How we handle data: Privacy Policy and Terms of Service. Include your organization name, the time (with time zone), and the error code. Never send passwords, Temporary Access Passes, or recovery codes.