Overview
Microsoft Entra ID is an identity management platform. It helps organizations manage secure access to applications and resources. When you integrate Microsoft Entra ID with Persona, you can use Persona identity verification in the Microsoft ecosystem. Use it to manage employee authentication and account recovery workflows, including password resets, MFA method revocation, and passkey (FIDO2) registration.
Prerequisites
To set up the Microsoft Entra ID integration with Persona, you need:
- A Microsoft Entra tenant.
- If you use delegated permissions, a dedicated Entra service account that has the roles in Roles for the service account.
- A test user who is not the service account.
- A completed onboarding process with Persona. To create an account, register through the Persona Dashboard.
Before you connect: create a dedicated service account
Connect the integration with a dedicated Entra service account. Do not use the personal account of a named administrator. A dedicated account is necessary for these reasons:
- Microsoft does not let an account reset its own password or create its own Temporary Access Pass (TAP).
- If the connection uses the account of an administrator, the connection stops when that administrator leaves, changes their password, or loses a role.
- Password expiry and Conditional Access policies can interrupt the service.
- A service account keeps a clean audit trail.
A Global Administrator creates the service account. We recommend that you exclude the service account from interactive MFA, or that you restrict it with Conditional Access.
The service account applies to delegated permissions, where an account signs in to connect the integration. We recommend that you always connect the integration with a dedicated service account and delegated permissions. Delegated permissions support all operations, including password reset. Thus, if you add password reset to your workflow later, you do not have to connect the integration again.
With application permissions, no account signs in. Use application permissions only if your security policy does not allow a service account that a person signs in to. Read Which connection type should I choose?.
Always test with a user who is not the service account. If you test on the account that connected the integration, the operation fails with the error “Self-service operations are currently not supported for user…”.
Roles for the service account
Give the service account the roles that your workflow needs:
| Role or permission | When the service account needs it |
|---|---|
| Authentication Administrator | To manage TAP, MFA, and passkeys for users who are not administrators. |
| Privileged Authentication Administrator | If administrators are in scope. Read the FAQ about administrative units. |
| User Administrator | If the workflow updates user profiles or passwords. |
| Global Reader | Only to list passkeys, if the workflow does no other passkey operation. |
CustomSecAttributeAssignment.Read.All permission and the Attribute Assignment Reader role | If you store date of birth or legal name in Custom Security Attributes. |
These Entra roles apply only to the service account for delegated permissions. With application permissions, no account signs in, so the app does not need the Attribute Assignment Reader role. If you store date of birth or legal name in Custom Security Attributes, add CustomSecAttributeAssignment.Read.All as an application permission instead.
Make each role assignment permanent (active). Do not use a temporary or “eligible” assignment in Privileged Identity Management (PIM). When that assignment expires, the connection stops. If the role is eligible but not active, TAP and MFA operations fail with an access denied error until someone activates the role.
The Global Administrator role also works, but it gives more access than the integration needs. Use it only as a fallback.
Connect Microsoft Entra ID to your Persona account
Go to the Marketplace integrations in your Persona dashboard and select Microsoft Entra ID.
Microsoft Entra ID supports two authentication methods:
- Delegated permissions (default) — lets you manage all user authentication methods.
- Application permissions (app-only) — lets you do a limited set of authentication method operations.
For more information about the differences between these permission types, read the Microsoft documentation on delegated and application permissions.
Which connection type should I choose?
| Feature | Delegated permissions (recommended) | Application permissions (app-only) |
|---|---|---|
| How Persona connects | A service account signs in. | Persona uses its own identity (client credentials). |
| Password reset | Supported | Not supported |
| TAP and MFA reset | Supported | Supported |
| Use it when | Always, unless your security policy prevents it. It supports all operations, including password reset. | Your security policy does not allow service accounts that a person signs in to. |
We recommend delegated permissions with a dedicated service account. Delegated permissions are necessary for password reset. Application permissions support TAP and MFA reset, but not password reset, because Microsoft does not support password reset with app-only access.
Option 1: Delegated permissions
With delegated permissions, Persona acts for a signed-in user and accesses a range of Microsoft Graph authentication methods APIs. The permissions of the authorizing user control which Microsoft Entra ID operations Persona can do for the user.
Supported operations and associated permissions:
- Get user -
User.Read.All,CustomSecAttributeAssignment.Read.All - Get user by email -
User.Read.All - Create a user -
User.ReadWrite.All - Update a user -
User.ReadWrite.All,User-PasswordProfile.ReadWrite.All - List authentication methods -
UserAuthenticationMethod.ReadWrite.All - Delete authentication method -
UserAuthenticationMethod.ReadWrite.All - Reset password -
UserAuthenticationMethod.ReadWrite.All - Create temporary access pass -
UserAuthenticationMethod.ReadWrite.All - List passkeys -
UserAuthenticationMethod.Read.All - Get passkey creation options -
UserAuthenticationMethod.ReadWrite.All - Register a passkey -
UserAuthenticationMethod.ReadWrite.All
Setup steps:
- Select + Add credential. Select Microsoft Entra Authorization.
- Give this credential a name (for example, “Persona”).
- Sign in to your Microsoft account.
Note: Persona needs the offline_access permission to keep access to Graph APIs.
Option 2: Application permissions (app-only)
With application permissions, Persona authenticates with its own identity (client credentials), not for a user. This is useful for automated scenarios that run with no person present. The permissions of the app control which Microsoft Entra ID operations Persona can do.
Supported operations and associated permissions:
- Get user -
User.ReadWrite.All,CustomSecAttributeAssignment.Read.All(only if you store date of birth or legal name in Custom Security Attributes) - Get user by email -
User.ReadWrite.All - Create a user -
User.ReadWrite.All - Update a user -
User.ReadWrite.All,User-PasswordProfile.ReadWrite.All - List authentication methods -
UserAuthenticationMethod.ReadWrite.All - Delete authentication method -
UserAuthenticationMethod.ReadWrite.All - Create temporary access pass -
UserAuthenticationMethod.ReadWrite.All - List passkeys -
UserAuthMethod-Passkey.Read.All - Get passkey creation options -
UserAuthMethod-Passkey.ReadWrite.All - Register a passkey -
UserAuthMethod-Passkey.ReadWrite.All
Unsupported operations:
- Reset password — Microsoft does not support this operation with application-only permissions
If your use case requires password resets, you can use the Update a user request to update the password profile of a user.
Setting up app-only permissions
- In the Azure/Entra portal, go to App registrations (not Enterprise Applications).
- Select your Persona application or create a new app registration.
- Under Certificates & secrets, create a new client secret. Keep it in a secure location.
- Under API permissions, add the applicable Application permissions (not Delegated). If you store date of birth or legal name in Custom Security Attributes, also add
CustomSecAttributeAssignment.Read.All. - Click Grant admin consent for your tenant.
- In your Persona dashboard, go to Marketplace Integrations. Search for Microsoft Entra.
- Select + Add credential.
- Give this credential a name (for example, “Persona App-Only”).
- Enter your:
- Tenant ID
- Client ID (Application ID)
- Client Secret
If you do not select Grant admin consent, the app does not get the permissions that you added.
Recommended matching attributes
Persona recommends that you match on legal first name, legal last name, and date of birth. The built-in user profile in Microsoft Entra ID does not include a date of birth field that most organizations populate. Thus, organizations usually do one of these two things:
- Store it in a Custom Security Attribute. Custom Security Attributes are custom attributes that only specifically authorized roles and apps can read. They are a good fit for sensitive data, such as date of birth and legal name. Organizations often populate them automatically from their HR system.
- Get it from the HR system (HRIS) directly, and compare it during verification.
If you use Custom Security Attributes, grant Persona the CustomSecAttributeAssignment.Read.All permission when you connect. This applies to delegated permissions and to application permissions. Then contact your Persona account team to map your attributes in your workflow.
Your employee’s experience
To help an employee reset their password, put their Entra ID in the inquiry URL before you send it. The Entra ID is usually their work email address. Your helpdesk can generate a Persona inquiry link that includes the Entra ID of the employee in the URL.
Persona uses this ID to get employee data from Microsoft Entra. Persona gets the name of the employee from the standard user profile fields. Persona gets the date of birth only if you store it in a Custom Security Attribute or get it from your HR system. Read Recommended matching attributes. Persona can then verify that it is the correct person before it makes account updates.
After verification, Persona shows the employee a temporary password. The employee uses it to sign in at https://entra.microsoft.com. Entra then tells them to set a new password.
For more information about what the employee sees, read What to expect when verifying your identity with Persona to reset your Microsoft Entra ID password.
Resetting an employee’s MFA
The integration can also reset the multi-factor authentication (MFA) of an employee. To do this, it deletes a registered authentication method. This revokes that factor. The employee must then enroll it again at the next sign-in. Microsoft Graph does not have one “reset all factors” endpoint, as Okta does. Thus, MFA reset in Entra works one method at a time, with two operations in sequence:
- List authentication methods — gets the registered methods of the employee, so you can find the method to reset. The response includes the
@odata.type(which maps to the method type) and theidof each method. - Delete authentication method — deletes the specific method with its type and ID. This revokes that factor. At the next sign-in, Entra tells the employee to enroll it again, as your Entra policies specify.
The Method Type parameter selects the type of method to delete. It accepts one of these values:
softwareOathMethodsemailMethodsfido2MethodsmicrosoftAuthenticatorMethodsphoneMethodsplatformCredentialMethodstemporaryAccessPassMethodswindowsHelloForBusinessMethods
Both operations require the UserAuthenticationMethod.ReadWrite.All permission. You can use both operations with delegated permissions or with application permissions. Unlike password reset, Microsoft Graph supports the deletion of all of the method types above with application-only permissions.
You cannot undo the deletion of an authentication method. The deletion revokes that factor immediately. Before you continue, make sure that you delete the correct method for the correct user. Before you revoke a factor, we recommend that you verify the identity of the employee with a Persona inquiry.
Managing an employee’s passkeys
The integration can list the passkeys (FIDO2) of an employee, register a new passkey for them, and remove a passkey. Use these operations, for example, to give a verified employee a new security key after they lose their old one.
Before you start
The passkey operations need more configuration in your Microsoft Entra tenant:
- In the Microsoft Entra admin center, go to Entra ID > Authentication methods > Policies and select Passkey (FIDO2).
- On Enable and Target, turn on the method. Include the employees who can get a passkey this way, or All users.
- On Configure, set Allow self-service set up to Yes. The provisioning operations fail without this setting, although only an administrator can use them. This is a known issue in Microsoft Graph.
- If Enforce attestation is on, make sure that your security keys are on the Microsoft list of attested vendors.
- Select Save.
For delegated permissions, the service account needs the passkey roles in Roles for the service account. To register or remove a passkey, it needs an administrator role. To only list passkeys, a reader role is sufficient.
List passkeys
List passkeys gets the passkeys that are registered to an employee. For each passkey, the response includes:
- The ID of the passkey
- The display name and the date that it was created
- The model of the authenticator
- The attestation level (
attestedornotAttested) - The passkey type: device-bound (
deviceBound) or synced (synced)
This operation works on the global, GCC High, and DoD clouds.
Register a passkey for an employee
To register a passkey for an employee, you do three steps. Persona does the first step and the last step. A provisioning client that your organization controls does the middle step on the security key.
-
Get passkey creation options. Persona gets the WebAuthn options for the employee from Entra. The options include a challenge. The challenge expires after 5 minutes, so you must complete step 3 before then.
-
Create the credential on the security key. Give the creation options to a CTAP or WebAuthn provisioning client that your organization controls. The client creates the credential on the security key of the employee. Persona cannot do this step, because the credential must be created on the security key itself.
Each
excludeCredentialsID in the creation options ends with one extra digit. The digit is the number of padding characters that Entra removed. Your client must remove this digit before it decodes the ID. -
Register a passkey. Persona sends the credential from the client to Entra. The request body contains a
displayNameand thepublicKeyCredential. Encode each binary value as Base64URL without padding.{ "displayName": "Security key", "publicKeyCredential": { "id": "CREDENTIAL_ID", "response": { "clientDataJSON": "CLIENT_DATA_JSON", "attestationObject": "ATTESTATION_OBJECT" } } }If the registration is successful, the response includes the ID, model, and attestation level of the new passkey.
Entra trusts the public key that Register a passkey sends. Whoever holds the authenticator that created the credential can sign in as the employee without their password, and Entra counts that sign-in as phishing-resistant MFA. To prevent account takeover:
- Send only a credential from a provisioning client that your organization controls.
- Register a passkey only after Persona verifies that the person is the account owner.
- Take the user ID from the Entra data that is stored on the Persona account. Do not take it from data that the end user enters.
Remove a passkey
To remove a passkey, use Delete authentication method. Set Method Type to FIDO2 Methods (fido2Methods), and set the method ID to the passkey ID from List passkeys.
This operation works with delegated permissions and with application permissions. With application permissions, UserAuthMethod-Passkey.ReadWrite.All is sufficient to remove a passkey, so you do not need UserAuthenticationMethod.ReadWrite.All for this method type.
Passkey limits
- Get passkey creation options and Register a passkey work only on the global cloud. Microsoft does not supply passkey creation options in GCC High or DoD.
- Entra accepts only the
packedandnoneattestation formats. - Pre-registered passkeys (security keys that have credentials on them before delivery) are not supported.
- Guest users and B2B users are not supported.
Frequently Asked Questions
What minimum permissions and scopes are required?
You must create a Microsoft Entra API credential with the applicable scopes. These include User.Read.All and UserAuthenticationMethod.ReadWrite.All. If you do not give these permissions, the integration setup fails with the message “Need admin approval: Persona needs permission to access resources in your organization that only an admin can grant.”
For delegated permissions: The signed-in user must have these delegated permissions and the applicable admin privileges.
For app-only permissions: Grant these application permissions to the application in the App registration. Then an administrator must select Grant admin consent for your tenant.
These permissions do not let Persona manage users in a restricted management administrative unit. For those users, you also need roles that are scoped to the unit. Read How do I let Persona manage users in a restricted administrative unit?.
How do I look up a user with application permissions?
With application permissions, no user signs in. Thus, the Get current user profile operation does not work. To find a user, use Get user with the user principal name (UPN) of the user.
The UPN can be different from the email address of the user. When you test, use the UPN of the test user.
Why does issuing a TAP or resetting MFA fail with a 403 or access denied error?
Check these causes:
- The user is in a restricted management administrative unit. Tenant-wide permissions and roles do not apply to these users. Read Can Persona manage users in an administrative unit?.
- The PIM role of the service account is not active. With delegated permissions, an eligible role does not work until someone activates it. Give the service account a permanent (active) role assignment. Read Roles for the service account.
- Permissions are missing, or nobody granted admin consent. Read What minimum permissions and scopes are required?.
- The user is the account that connected the integration. Self-service operations are not supported. Read Before you connect: create a dedicated service account.
- The Temporary Access Pass policy is not enabled for the group of the user. Read Issue Microsoft Entra Temporary Access Passes with Persona.
The Entra audit logs show which account did the operation. Use them to find the cause.
Can Persona manage users in an administrative unit?
Some organizations put privileged accounts, for example administrator accounts, in an Entra administrative unit. The type of administrative unit controls if Persona can manage these users:
- Regular administrative units do not limit tenant-wide application permissions. An app-only connection can manage the users in a regular administrative unit.
- Restricted management administrative units block tenant-wide administrators and apps that have tenant-wide permissions. They cannot change the members of the unit. Thus, Persona operations on these users fail with a 403 or access denied error. This includes issuing a TAP and resetting MFA. The operations fail even if you granted all API permissions correctly. Operations on users outside the unit continue to work.
Many organizations want this behavior. Often, a privileged account must not get a TAP through self-service. Keep these accounts in the restricted management administrative unit, and recover them through an internal process.
How do I check if an administrative unit is restricted?
- In the Microsoft Entra admin center, go to Identity > Roles & admins > Admin units.
- Find the administrative unit. If Restricted management shows Yes, the unit is restricted. If it shows No, the unit is a regular administrative unit.
You can set Restricted management only when you create an administrative unit.
How do I let Persona manage users in a restricted administrative unit?
If you want Persona to manage these users, assign roles that are scoped to the restricted management administrative unit:
| Connection type | Assign the roles to | Roles |
|---|---|---|
| Application permissions | The app registration | Privileged Authentication Administrator, scoped to the administrative unit. Directory Readers, at tenant scope. |
| Delegated permissions | The service account | Privileged Authentication Administrator, scoped to the administrative unit. |
Microsoft requires the Directory Readers role at tenant scope before an app can use a role that is scoped to an administrative unit. The Authentication Administrator role covers only users who are not administrators, so it is not sufficient for privileged accounts.
A Global Administrator in a restricted management administrative unit may stay out of reach of roles that are scoped to that unit.
Can I reset all of an employee’s MFA factors at once?
No. Microsoft Graph does not have one endpoint that resets all factors at the same time. Thus, the integration resets MFA one method at a time. First, list the authentication methods of the employee. Then delete each method that you want to revoke. For each deleted method, the employee must enroll again at the next sign-in. Unlike password reset, this works with delegated permissions and with application permissions.
How can I get my user a verification link?
In many cases, employees may contact a helpdesk through ServiceNow or similar tools. The helpdesk can put the Entra ID of the employee in the inquiry URL before it sends the URL. Persona then gets data from Entra to verify the identity. After that, Persona does the configured authentication method operation. If you use password reset, Microsoft Entra makes the employee change their password at the next sign-in.
Plans Explained
Microsoft Entra Integration by plan
| Startup Program | Essential Plan | Growth Plan | Enterprise Plan | |
|---|---|---|---|---|
| Microsoft Entra Integration | Not Available | Not Available | Limited | Available |