Skip to main content
Version: 11.3.0

Entra ID: OIDC Integration for HYPR Affirm Helpdesk

The HYPR Affirm Helpdesk portal uses OpenID Connect (OIDC) to authenticate Helpdesk agents. This article describes how to configure Microsoft Entra ID as the OIDC provider, define role-based access for agents and connect the integration in HYPR Control Center.

When configuration is complete, Helpdesk agents go to the Helpdesk portal URL and are redirected to Entra ID to sign in. HYPR reads the role claim from the returned OIDC token and grants the agent either Viewer or Editor access to the Helpdesk portal.

Enablement Required

The HYPR Affirm Helpdesk portal must be enabled on your tenant. Contact your HYPR representative to enable it before proceeding.

Reuse an Existing HYPR Entra Application

If you already have a HYPR application registered in Entra ID (for example, the registration used for Control Center sign-in or HYPR Enterprise Passkey), you can add the Helpdesk role and claim to that same application instead of creating a new one. Adding the affirm_helpdesk_role claim does not affect the tokens issued for the existing integration.

Prerequisites​

Before you begin, make sure you have the following:

  • Entra ID administrator access (Global Administrator) on an account in your *.onmicrosoft.com tenant
  • Users in your Entra ID directory, and at least one group or a plan for assigning Helpdesk editors
  • A HYPR Control Center account with HYPR Affirm deployed
  • A dedicated Helpdesk relying party application configured in HYPR Control Center

Helpdesk Agent Roles​

The Affirm Helpdesk portal supports two roles. HYPR reads the affirm_helpdesk_role claim from the OIDC token to assign the corresponding role to each agent.

RoleAccepted Claim ValuesAccess
ViewerAFFIRM_HELPDESK_VIEWER or HYPR_AFFIRM_HELPDESK_VIEWERView verification workflows and activity records
EditorAFFIRM_HELPDESK_EDITOR or HYPR_AFFIRM_HELPDESK_EDITORView and initialize verification workflows

HYPR applies the following fallback behavior:

  • If affirm_helpdesk_role is not present, HYPR checks for hypr_role as a secondary claim.
  • If neither claim is present, the user is not authorized for the Helpdesk portal and sees the Access Not Allowed page.
  • When a user is assigned both roles, Editor takes precedence and all Editor authorities apply.
Access Requires a Role Claim

Authenticating with Entra ID is not sufficient on its own. The token must carry a valid affirm_helpdesk_role (or hypr_role) value, or the user is denied access to the Helpdesk portal and sees the Access Not Allowed page. To grant access, assign the user one of the Helpdesk app roles so the claim is populated; to revoke access, remove their app role assignment in Entra ID.

Register an Application in Entra ID​

  1. Sign in to the Microsoft Entra admin center as an administrator.

  2. Go to App registrations and click + New registration.

  3. Enter a name for the application (for example, HYPR Affirm Helpdesk), select Accounts in this organizational directory only (single tenant), and click Register.

    Register an application page in the Microsoft Entra admin center with the Name field and the single tenant account type selected

  4. Go to Authentication → + Add a platform and select Web.

    Select a platform to add redirect URI panel with Web, Single-page application, and mobile and desktop platform options

  5. In the Web platform panel, enter the following values, leave the implicit-grant token options unchecked, and click Configure:

    • Redirect URI: {HYPR_TENANT_URL}/login/oauth2/idv/support/code/{YOUR_RELYING_PARTY}
    • Front-channel logout URL: {HYPR_TENANT_URL}/login

    Replace {HYPR_TENANT_URL} with your HYPR tenant URL. Replace {YOUR_RELYING_PARTY} with the name of your integration as configured in HYPR Control Center, with spaces removed — for example, an integration named HYPR Passkeys becomes HYPRPasskeys.

    Add Redirect URI panel for the Web platform with the Redirect URI and Front-channel logout URL set and implicit grant tokens unchecked

  6. Go to Certificates & secrets → + New client secret, create a secret, and copy its Value to a secure location. You need it when you configure HYPR Control Center.

    Certificates and secrets page with the Add a client secret panel showing Description and Expires fields and an Add button Client secrets tab listing the new secret with its masked Value and the Copy to clipboard control

Add App Roles​

The Helpdesk role values are delivered as Entra ID app roles. In your application, go to App roles and click + Create app role.

App roles page of the application with no app roles added and the Create app role button highlighted

Create the following roles, setting Do you want to enable this app role? to enabled for each. Enter the Value exactly as shown, because it is the string delivered in the affirm_helpdesk_role claim.

Display NameValueAllowed Member TypesDescription
AFFIRM_HELPDESK_EDITORAFFIRM_HELPDESK_EDITORUsers/GroupsHYPR Affirm Helpdesk Editor
AFFIRM_HELPDESK_VIEWERAFFIRM_HELPDESK_VIEWERUsers/GroupsHYPR Affirm Helpdesk Viewer
Create app role panel with Display name and Value set to AFFIRM_HELPDESK_EDITOR, Users/Groups selected and the role enabled

Allow Mapped Claims in the App Manifest​

To deliver the app role values under the custom affirm_helpdesk_role claim name, allow mapped claims in the application manifest.

  1. In your application, go to Manifest.

  2. Set acceptMappedClaims to true. In the Microsoft Graph App Manifest this key is inside the api object; in the older manifest format it appears at the root.

  3. Click Save.

    Manifest editor on the Microsoft Graph App Manifest tab with acceptMappedClaims set to true inside the api object

Assign Users and Groups to Roles​

App role assignments are made on the Enterprise application (the service principal), not on the app registration.

  1. In Entra ID, go to Enterprise applications and select your HYPR application.

  2. Select Users and groups, then click + Add user/group.

  3. Under Users, click None Selected, choose the users (or groups) who need Helpdesk access, and click Select.

    Users selection panel of Add Assignment with two users checked and listed under Selected, and the Select button

  4. Under Select a role, click None Selected, choose AFFIRM_HELPDESK_EDITOR or AFFIRM_HELPDESK_VIEWER, and click Select. Only one role can be selected per assignment.

    Select a role panel listing AFFIRM_HELPDESK_EDITOR and AFFIRM_HELPDESK_VIEWER, with the viewer role selected

  5. Click Assign. A confirmation appears when the assignment completes.

    Application assignment succeeded notification confirming that users have been assigned access

The assigned role determines the value delivered in the affirm_helpdesk_role claim.

Add the Role Claim to the Token​

Add the affirm_helpdesk_role claim so the assigned role values are included in the OIDC ID token.

  1. In the same Enterprise application, select Single sign-on.

  2. In the Attributes & Claims section, click Edit.

    Attributes and Claims section of Single sign-on with no JWT-based claims configured and the Edit link

  3. Click + Add new claim.

  4. Enter the claim details:

    • Name: affirm_helpdesk_role
    • Namespace: leave blank so the claim is emitted as exactly affirm_helpdesk_role
    • Source: Attribute
    • Source attribute: user.assignedroles
    Manage claim panel with Name set to affirm_helpdesk_role, Source set to Attribute and user.assignedroles chosen as the source attribute

  5. Click Save at the top of the Manage claim panel. The affirm_helpdesk_role claim now appears in the Attributes & Claims list.

Restrict Access to Assigned Users​

To limit sign-in to only the users and groups you assigned:

  1. In the Enterprise application, go to Properties.

  2. Set Assignment required? to Yes and save.

    When this is set to No, any user in the directory can sign in to the application.

Retrieve the Entra OIDC Endpoints​

  1. In your Entra ID tenant, open the application from the previous sections and click Endpoints at the top of the Overview page.

    Application Overview page with the Essentials section showing the client and tenant IDs and the Endpoints button in the toolbar

  2. Copy the OpenID Connect metadata document URL and open it in a browser. This document lists the endpoint values you enter in HYPR Control Center: authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri and (optionally) end_session_endpoint.

Configure IDP Management in HYPR Control Center​

  1. In HYPR Control Center, switch to Advanced mode using the toggle in the upper right corner.

    HYPR Control Center home page with the Standard and Advanced mode toggle highlighted in the upper right corner

  2. In the left navigation, select your Helpdesk relying party application.

    HYPR Control Center left navigation with the relying party application drop-down and the Add Application button

  3. Under Advanced Config, select IDP Management.

    HYPR Control Center left navigation with IDP Management selected under Advanced Config

  4. Enter the following values. The endpoint URLs match the Entra OpenID Connect metadata document. Replace {TENANT_ID} with your Entra Directory (tenant) ID:

    • PKCE Enabled: leave unchecked
    • OAuth URL: https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize
    • Token URL: https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token
    • UserInfo URL: https://graph.microsoft.com/oidc/userinfo
    • JWKS URL: https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys
    • Logout URL: https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/logout (optional)
    • Client ID: the Application (client) ID from your Entra application
    • Client Secret: the client secret Value you copied from Entra
    • HYPR URL: your HYPR tenant URL
    • User Name Claim Attribute: email
    • Resource: leave blank
    IDP Management OIDC Connection Settings with PKCE Enabled unchecked and the OAuth, Token, UserInfo, JWKS and Logout URLs entered Lower OIDC Connection Settings with Client ID, Client Secret, HYPR URL, User Name Claim Attribute set to email, and Save Config

  5. Click Save Config.

Access the Helpdesk Portal​

When configuration is complete, Helpdesk agents access the portal at the following URL:

{HYPR_TENANT_URL}/cc/ui/idv/support/helpdesk

Navigating to this URL redirects agents to the Entra ID sign-in page. After authenticating, HYPR reads the affirm_helpdesk_role claim and provisions the agent just in time with the appropriate Viewer or Editor role. No manual user setup is required. An agent whose token carries no valid role claim is redirected to the Access Not Allowed page.

Helpdesk Support activity view with a requester or workflow ID search bar and an empty table with Requester, Date, Type, Workflow ID, Code, Decision and Options columns