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, drive each agent's Helpdesk role from their Okta group membership, 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 token and grants the agent either Viewer or Editor access to the Helpdesk portal.

Confirm your Okta org can create OpenID Connect identity providers

Adding the integration in Control Center returns error E0000015, "You do not have permission to access the feature you are requesting", when the Okta org is not able to create OpenID Connect identity providers:

{"errorCode":"E0000015","errorSummary":"You do not have permission to access the feature you are requesting","errorLink":"E0000015","errorId":"...","errorCauses":[]}

Okta returns this error, not HYPR, and it appears even when the Okta Portal Application Name, Okta Tenant URL, and Okta API Token are all correct.

To confirm the capability is available, sign in to the Okta Admin Console and go to Security > Identity Providers > Add identity provider. OpenID Connect IdP should be listed among the provider types. If it is not, your Okta org cannot create OIDC identity providers yet — ask your Okta administrator or Okta support to enable that capability, then add the integration in Control Center again.

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.

Most of the work happens in Okta. Only the IDP Management fields and the Helpdesk RP app assignment are configured in HYPR Control Center.

Prerequisites

• Okta super administrator access
• Users in your Okta directory
• A HYPR Control Center account with HYPR Affirm deployed

Helpdesk Agent Roles

The Affirm Helpdesk portal supports two roles. HYPR reads the affirm_helpdesk_role claim from the token and grants the matching role.

Role	Claim value	Access
Viewer	affirm_helpdesk_viewer	View verification workflows and activity records
Editor	affirm_helpdesk_editor	View and initialize verification workflows

How the claim value is interpreted:

• The value is not case-sensitive — affirm_helpdesk_editor and AFFIRM_HELPDESK_EDITOR are equivalent.
• A HYPR_ prefix is optional, so HYPR_AFFIRM_HELPDESK_EDITOR is also accepted.
• If an agent's token carries both roles, Editor takes precedence.

The role claim is required

An agent whose token carries no affirm_helpdesk_role value — or a value other than the two above — is denied access to the Helpdesk portal and sees an Access Not Allowed page. There is no default role. To remove an agent's access, remove them from the Helpdesk groups you create below.

Create the Helpdesk Groups in Okta

Each agent's role comes from their Okta group membership, so create the groups first.

1. In the Okta Admin Console, go to Directory → Groups and select Add group.

2. Create a group named Affirm Help Desk Editors.

3. Create a second group named Affirm Help Desk Viewers.

   

4. Assign your agents to whichever group matches the access they need.

Create an Okta OIDC Web Application

1. Go to Applications → Applications and select Create App Integration.

2. Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type, then select Next.

   

3. Enter a name for the application.

   

4. Scroll to the Login section before saving, and continue with the next section.

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 the Helpdesk relying party application. If you use the default web application, that value is HYPRDefaultApplication; if you create a dedicated Helpdesk app as described in Create the Helpdesk Relying Party Application, use the application name you chose there.

2. Set Initiate login URI to:

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

   

3. Save your changes.

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

Add the Role Claim

Add a custom claim that maps each agent's group membership to their Helpdesk role.

1. Go to Security → API → Authorization Servers.

2. Select the authorization server you want to use, for example default.

   Using a custom authorization server

   If you use a custom authorization server rather than the default, its ID becomes part of every endpoint URL you enter in Control Center later — for example {OKTA_TENANT_URL}/oauth2/{AUTH_SERVER_ID}/v1/authorize instead of {OKTA_TENANT_URL}/oauth2/v1/authorize. See Configure IDP Management in HYPR Control Center.

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

4. Configure the claim with the following values:

   Field	Value
   Name	affirm_helpdesk_role
   Include in token type	ID Token, Always
   Value type	Expression
   Include in	Any scope

   Set Value to an expression that returns the role for each group:

   isMemberOfGroupName("Affirm Help Desk Editors") ? "affirm_helpdesk_editor" : (isMemberOfGroupName("Affirm Help Desk Viewers") ? "affirm_helpdesk_viewer" : "")

   

5. Select Create.

An agent in neither group receives an empty value and is denied access to the portal, as described in Helpdesk Agent Roles.

Add an Access Policy Rule

The authorization server needs an active access policy with at least one rule, otherwise token requests fail.

1. On the authorization server, go to Access Policies.

2. Select the policy that applies to your application, then select Add Rule.

3. Name the rule, leave the grant types and scopes at values appropriate for your organization, and create it.

   

Verify the Claim

Confirm the claim reaches the token before configuring Control Center.

1. On the authorization server, go to the Token Preview tab.

2. Set the following, then select Preview Token:

   Field	Value
   OAuth/OIDC client	Your Helpdesk application
   Grant type	Authorization Code
   User	An agent assigned to one of the two Helpdesk groups
   Scopes	openid, profile

3. In the id_token payload, confirm affirm_helpdesk_role is present and carries the value for that agent's group.

   

Create the Helpdesk Relying Party Application

Create a dedicated relying party application in Control Center for the Helpdesk portal. The application name you set here is the relying party name used in the Okta sign-in redirect URI.

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

   

2. Select Add Application.

   

3. Select Web as the channel to decentralize, then select Next.

   

4. Select Custom Solution, then select Next.

   

5. Select No, I don't want to enable push notifications, then select Next.

   

6. Enter the application name, description and contact details, then select DONE.

   
   Match the redirect URI

   The application name becomes the relying party name in the Okta Sign-in redirect URIs value. If you have already saved the Okta application, update that URI so its final path segment matches this name.

Configure IDP Management in HYPR Control Center

1. Select your Helpdesk application from the application list.

   

2. Under Advanced Config, select IDP Management.

   

3. Enter the following values, replacing {OKTA_TENANT_URL} with your Okta tenant base URL. If you use a custom authorization server, include its ID in the path as shown in the second column.

   Field	Default authorization server	Custom authorization server
   OAuth URL	{OKTA_TENANT_URL}/oauth2/v1/authorize	{OKTA_TENANT_URL}/oauth2/{AUTH_SERVER_ID}/v1/authorize
   Token URL	{OKTA_TENANT_URL}/oauth2/v1/token	{OKTA_TENANT_URL}/oauth2/{AUTH_SERVER_ID}/v1/token
   UserInfo URL	{OKTA_TENANT_URL}/oauth2/v1/userinfo	{OKTA_TENANT_URL}/oauth2/{AUTH_SERVER_ID}/v1/userinfo
   JWKS URL	{OKTA_TENANT_URL}/oauth2/v1/keys	{OKTA_TENANT_URL}/oauth2/{AUTH_SERVER_ID}/v1/keys
   HYPR URL	{HYPR_TENANT_URL}	{HYPR_TENANT_URL}
   User Name Claim Attribute	preferred_username	preferred_username

   Set Client ID and Client Secret to the values generated by the Okta OIDC application.

   

   A completed configuration looks like this:

   

4. Select Save Config.

Assign the Relying Party Application to the Helpdesk

1. Switch back to Standard mode.

2. Go to HYPR Affirm → Helpdesk Settings.

3. Under Universal Configuration, set RP App Assignment to the relying party application you configured.

   

For the remaining Helpdesk settings on this tab, see HYPR Affirm Helpdesk Support.

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. Select 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 matching Viewer or Editor role.

Troubleshooting

Invalid redirect URI

Okta reports that the redirect URI is invalid.

This happens when the redirect URI in the Okta application does not match the relying party the HYPR OIDC integration points at. Confirm that:

• The Client ID and Client secret in the relying party's IDP Management match the Okta application.
• Helpdesk Settings → RP App Assignment points at the relying party you configured.
• The final path segment of the Okta Sign-in redirect URIs value matches the relying party application name.
• The relying party uses the authorization server whose endpoints you entered in IDP Management.

Access not allowed

The agent authenticates with Okta, then sees an Access Not Allowed page.

This happens when the role claim is missing, empty, or carries a value other than the two Helpdesk roles. Confirm that:

• The agent belongs to Affirm Help Desk Editors or Affirm Help Desk Viewers.
• The claim reaches the token, using Token Preview as described in Verify the Claim.
• The claim name is affirm_helpdesk_role and it is included in the ID token.

User is not assigned to the client application

Okta reports that the user is not assigned to the client application.

Assign the agent — or a group containing them — to the Okta OIDC application from its Assignments tab.

Policy evaluation failed

Okta returns a 400 Bad Request stating that policy evaluation failed.

This happens when the authorization server cannot evaluate a policy for the request. Confirm that:

• The authorization server is Active.
• The server has an access policy, and that policy is active.
• The policy has at least one active rule, as described in Add an Access Policy Rule.
• The policy and rule apply to the Helpdesk application rather than being restricted to other applications.