Okta: 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 Okta as the OIDC provider, define role-based access for agents, and connect the integration in HYPR Control Center.

When configuration is complete, helpdesk agents navigate to the Helpdesk portal URL and are redirected to Okta 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.

Feature Flag Required

The HYPR Affirm Helpdesk portal requires the AFFIRM_HELPDESK_SUPPORT feature flag. Contact your HYPR representative to enable it on your tenant before proceeding.

Prerequisites

• Okta administrator access
• Users in your Okta directory with at least one group identifying 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.

Role	Accepted Claim Values	Access
Viewer	AFFIRM_HELPDESK_VIEWER or HYPR_AFFIRM_HELPDESK_VIEWER	View verification workflows and activity records
Editor	AFFIRM_HELPDESK_EDITOR or HYPR_AFFIRM_HELPDESK_EDITOR	View and initialize verification workflows

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 granted Viewer access by default.
• When a user is assigned both roles, Editor takes precedence and all Editor authorities apply.

Default Access Behavior

Users who authenticate successfully through Okta but whose token contains no role claim are granted Viewer access. To prevent a user from accessing the Helpdesk portal entirely, remove their assignment from the Helpdesk application in Okta.

Create an Okta OIDC Web Application

1. Sign in to your Okta Admin Console.

2. Go to Applications → Applications and click Create App Integration.

   

3. Select OIDC - OpenID Connect as the sign-on method and Web Application as the application type, then click Next.

   

4. Enter a name for the application, then scroll to the Login section before saving.

Configure the Application Login Settings

In the Login section of the new OIDC application:

1. Set Sign-in redirect URIs to:

   {HYPR_TENANT_URL}/login/oauth2/idv/support/code/{HYPR_RELYING_PARTY_APP}

   Replace {HYPR_TENANT_URL} with your HYPR tenant URL and {HYPR_RELYING_PARTY_APP} with the name of your dedicated Helpdesk relying party application in HYPR Control Center.

2. Set Initiate login URI to:

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

3. Set Sign-out redirect URIs to:

   {HYPR_TENANT_URL}/login

   

4. Click Save.

5. From the application's General tab, copy the Client ID and Client secret. You will need these values when configuring HYPR Control Center.

Add a Role Claim to the Authorization Server

HYPR reads the affirm_helpdesk_role claim from the OIDC token to determine each agent's Helpdesk role. Configure this claim in your Okta authorization server.

1. Go to Security → API → Authorization Servers.

2. Click the authorization server you want to use (for example, Default).

3. Go to the Claims tab and click Add Claim.

4. Configure the claim with the following values:

   Field	Value
   Name	affirm_helpdesk_role
   Include in token type	ID Token
   Value type	Expression
   Value	isMemberOfGroup("{YOUR_EDITOR_GROUP}") ? "HYPR_AFFIRM_HELPDESK_EDITOR" : "AFFIRM_HELPDESK_VIEWER"

   Replace {YOUR_EDITOR_GROUP} with the Okta group whose members should receive Editor access in the Helpdesk portal. Members outside this group receive Viewer access.

   

5. Click Create.

Configure IDP Management in HYPR Control Center

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

   

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

   

3. Under Advanced Config, select IDP Management.

   

4. Enter the following values, replacing {OKTA_TENANT_URL} with your Okta tenant base URL:

   Field	Value
   OAuth URL	{OKTA_TENANT_URL}/oauth2/v1/authorize
   Token URL	{OKTA_TENANT_URL}/oauth2/v1/token
   UserInfo URL	{OKTA_TENANT_URL}/oauth2/v1/userinfo
   JWKS URL	{OKTA_TENANT_URL}/oauth2/v1/keys
   HYPR URL	{HYPR_TENANT_URL}
   Client ID	The Client ID from your Okta OIDC application
   Client Secret	The Client Secret from your Okta OIDC application
   User Name Claim Attribute	preferred_username

   

5. Click Save Config.

Add Helpdesk Users in Control Center

After saving the IDP configuration, add the agents who need access to the Helpdesk portal.

1. In HYPR Control Center, go to HYPR Affirm → Helpdesk Users.

   

2. Click Add User, enter the agent's details, and assign the appropriate Helpdesk role.

   

For full instructions on managing Helpdesk users and configuring Helpdesk settings, see HYPR Affirm Helpdesk Support.

Access the Helpdesk Portal

Once configuration is complete, helpdesk agents access the portal at:

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

Navigating to this URL redirects agents to the Okta sign-in page. After authenticating, HYPR reads the affirm_helpdesk_role claim and grants access with the appropriate Viewer or Editor role.