Configure Okta as an OpenID Connect Identity Provider in Keycloak

This guide explains how to configure Okta as the OpenID Connect (OIDC) Identity Provider for Apporto NextGen through Keycloak. Use it as an end-to-end setup checklist to create the Keycloak OIDC broker, configure the Okta Web Application, exchange client credentials and discovery metadata, map user profile claims, and validate sign-in.

Overview

Keycloak acts as the identity broker for Apporto NextGen. Okta authenticates the user through OpenID Connect, and Keycloak imports the returned identity claims into the tenant realm.

System

Purpose

Keycloak

Hosts the tenant realm, OIDC identity provider configuration, user mapping, and optional claim-to-role mapping.

Okta

Hosts the OIDC Web Application, user directory, client credentials, application assignments, and profile mappings.

Before you begin

  • Confirm you have administrator access to the Keycloak realm for the customer tenant.

  • Confirm you have an Okta administrator account that can create and manage OIDC application integrations.

  • Have a test Okta user available for validation.

  • Know the Keycloak host and customer tenant realm name.

  • Decide whether authorization will be driven by Okta groups, direct role claims, or only by the user profile.

  • Keep both Keycloak and the Okta administration consoles open during setup so you can copy values between them.

Configuration flow

  1. Add an OpenID Connect v1.0 provider in Keycloak and copy the generated Redirect URI.

  2. Create an OIDC Web Application in Okta.

  3. Enable Authorization Code and register the Keycloak Redirect URI.

  4. Configure Okta application access and save the app.

  5. Collect the Okta Client ID, Client Secret, and OIDC discovery endpoint.

  6. Configure the Okta discovery endpoint and client authentication in Keycloak.

  7. Review OIDC endpoints, signature validation, scopes, and advanced Keycloak settings.

  8. Assign users or groups to the Okta application.

  9. Configure the Okta OIDC user profile mapping.

  10. Create Keycloak identity provider mappers for username, email, first name, and last name.

  11. Optionally configure Okta group claims and Keycloak claim-to-role mappings.

  12. Test sign-in end to end.


Instructions

Step 1: Add the Okta OpenID Connect provider in Keycloak

  1. Sign in to the Keycloak administration console.

  2. Select the customer tenant realm.

  3. Go to Identity Providers.

  4. Click Add provider.

  5. Select OpenID Connect v1.0.

    Screenshot 2026-08-24 at 4.13.51 PM.png

Set the provider alias

Enter a short, unique alias for the provider. Do not use spaces.

Example:

okta-oidc

Keep this Keycloak page open. You will need the generated Redirect URI when setting up the OIDC application in Okta.

Collect the Keycloak redirect URI

Copy the Redirect URI generated by Keycloak. The provider alias becomes part of the callback URI.

Example Redirect URI:

https://<keycloak-host>/realms/<realm-name>/broker/<alias>/endpoint

If the alias is okta-oidc, Okta must redirect the user back to /broker/okta-oidc/endpoint exactly.


Step 2: Create the OIDC Web Application in Okta

Create a new OIDC Web Application in Okta. This application authenticates users and sends them to Apporto NextGen after successful sign-in.

  1. Sign in to the Okta Admin Console.

  2. Go to Applications and Resources > Applications.

    Screenshot 2026-08-17 at 3.47.37 PM.png
  3. Click Create App Integration.

    Screenshot 2026-08-17 at 3.47.57 PM.png
  4. Select OIDC - OpenID Connect.

  5. For Application type, select Web Application.

    Screenshot 2026-08-24 at 3.58.56 PM.png
  6. Click Next.

  7. Enter an application name such as Apporto OIDC Login.

Use Web Application, not Single-Page Application or Native Application. Keycloak is a server-side confidential OIDC client and stores the Okta client secret.


Step 3: Configure the grant type, redirect URI, and application access

Configure the Okta Web Application with the following values.

Setting

Recommended value

App integration name

Apporto OIDC Login

Proof of possession (DPoP)

Disabled

Client Credentials grant

Disabled

Authorization Code

Enabled

Refresh Token

Disabled unless explicitly required

Sign-in redirect URI

Keycloak Redirect URI copied in Step 1

Allow wildcard in redirect URI

Disabled

Screenshot 2026-08-24 at 4.00.08 PM.png

Under Assignments or Controlled access, choose the access model that fits the customer environment.

Access option

When to use it

Allow everyone in your organization to access

Use when every Okta user should be allowed to authenticate.

Limit access to selected groups

Preferred when access should be restricted to approved Okta groups.

Skip group assignment for now

Use only when assignments will be configured after app creation.

Leave Enable immediate access with Federation Broker Mode unchecked for this setup.

Screenshot 2026-08-24 at 4.12.09 PM.png

Federation Broker Mode is not required for this integration. Leaving it off keeps normal application assignments and management behavior available.


Step 4: Collect the Okta client credentials and discovery endpoint

Collect the Client ID and Client Secret

After saving the Okta application, open the General tab and locate Client Credentials. Copy the Client ID and Client Secret. You will enter both values in Keycloak.

Treat the Client Secret as sensitive. Do not publish it in screenshots, tickets, or customer-facing documentation.

Determine the OIDC discovery endpoint

This guide uses the Okta Org Authorization Server. Its issuer is the Okta organization domain, and the discovery endpoint is derived from that domain.

Value

Format

Okta organization URL

https://<customer-okta-domain>

Discovery endpoint

https://<customer-okta-domain>/.well-known/openid-configuration

Example:

https://trial-8522365.okta.com/.well-known/openid-configuration

Security > API > Authorization Servers lists custom authorization servers such as /oauth2/default. The built-in Org Authorization Server used by this guide is not listed there. Do not switch to /oauth2/default unless the integration is intentionally designed to use a custom authorization server.


Step 5: Configure Okta discovery and client authentication in Keycloak

Return to the OpenID Connect identity provider configuration in Keycloak.

Keycloak field

Value

Use discovery endpoint

On

Discovery endpoint

https://<customer-okta-domain>/.well-known/openid-configuration

Client authentication

Client secret sent as HTTP Basic authentication

Client ID

Client ID from the Okta OIDC application

Client Secret

Client Secret from the Okta OIDC application

Client assertion signature algorithm

Algorithm not specified

HTTP Basic authentication corresponds to the standard client_secret_basic method used by a confidential Okta Web Application. Do not use the deprecated Basic option without URL encoding.

Screenshot 2026-08-24 at 4.25.38 PM.png
Screenshot 2026-08-24 at 4.27.57 PM.png

Step 6: Review OIDC endpoint and advanced Keycloak settings

When discovery is configured, Keycloak should resolve the Okta endpoints automatically. Confirm that the issuer and discovered URLs point to the same Okta organization.

When Use discovery endpoint is enabled, Keycloak may automatically populate the Logout URL from the discovery metadata. Remove the populated Logout URL explicitly before saving the configuration.

Keycloak field

Expected Org Authorization Server value

Authorization URL

https://<okta-domain>/oauth2/v1/authorize

Token URL

https://<okta-domain>/oauth2/v1/token

User Info URL

https://<okta-domain>/oauth2/v1/userinfo

Issuer

https://<okta-domain>

JWKS URL

https://<okta-domain>/oauth2/v1/keys

Validate Signatures

On

Use JWKS URL

On

Use PKCE

Off for the validated confidential-client setup

If Use Discovery endpoint is disabled, Keycloak will no longer populate the OIDC endpoints automatically. Configure each endpoint manually, for example:

Authorization URL = https://<okta-domain>/oauth2/v1/authorize
Token URL         = https://<okta-domain>/oauth2/v1/token
User Info URL     = https://<okta-domain>/oauth2/v1/userinfo
Issuer            = https://<okta-domain>
JWKS URL          = https://<okta-domain>/oauth2/v1/keys
9362f563-c700-4637-85d6-3920b535fb6d

Review the following advanced settings.

Setting

Validated or recommended value

Send 'id_token_hint' in logout requests

On

Send 'client_id' in logout requests

Off

Disable nonce

Off

Disable type claim check

Off

Scopes

openid email profile

Prompt

Unspecified

Accept prompt=none forward from client

Off

Requires short state parameter

Off

Allowed clock skew

0

Trust Email

On

First login flow override

Apporto first broker login

Post login flow

None

Sync mode

Import

Case-sensitive username

Off

The tested trial configuration used Disable User Info set to On and successfully created the Keycloak user with email, first name, and last name. For a reusable customer guide, validate this setting against the customer Okta tenant. The Okta Org Authorization Server can issue a thin ID token in Authorization Code flow. If required profile claims are missing, set Disable User Info to Off so Keycloak can retrieve the full profile from the discovered UserInfo endpoint.

Screenshot 2026-08-24 at 4.32.11 PM.png
adv settings.png

Step 7: Assign users or groups to the Okta application

Okta requires the user or an eligible group to have access to the application before sign-in is allowed.

  1. Open the Apporto OIDC Login application.

  2. Select Assignments.

  3. Assign the required people or groups according to the access model selected during app creation.

  4. Verify the test user appears as eligible for the application.

Okta directory group membership and application assignment are separate concepts. A user can belong to an authorization group without automatically being assigned to the OIDC application, depending on the controlled-access configuration.


Step 8: Configure the Okta OIDC user profile mapping

Open the application Sign On tab and click Configure profile mapping.

Screenshot 2026-08-24 at 4.36.15 PM.png

Select the mapping direction Okta User to Apporto OIDC Login. Okta creates the standard OIDC App User profile fields automatically.

Screenshot 2026-08-24 at 4.38.11 PM.png

Override the application username so the Okta user email becomes the OIDC app username.

user.email -> appuser.userName

For the username mapping, use Apply mapping on user create only, matching the validated setup.

Screenshot 2026-08-24 at 4.38.37 PM.png

Okta user attribute

OIDC app profile field

user.email

userName

user.displayName

name

user.firstName

given_name

user.lastName

family_name

user.email

email

The profile scope supplies standard OIDC profile claims such as preferred_username, given_name, and family_name. The email scope supplies email. The app profile mapping determines which Okta user attributes back those OIDC profile fields.


Step 9: Add identity provider mappers in Keycloak

Create explicit identity provider mappers so Keycloak stores the Okta OIDC claims in the correct built-in user fields.

In Keycloak, open the Okta identity provider and go to the Mappers tab. Click Add mapper for each profile field that Keycloak must import from the Okta OIDC claims.

Use Attribute Importer as the mapper type for the standard profile fields. Keep Sync mode override set to Inherit, and leave Allow null value switched off so missing claims do not overwrite required user details.

  • Username: map the preferred_username claim to the Keycloak username user attribute.

    Screenshot 2026-08-24 at 4.52.44 PM.png
  • Email: map the email claim to the Keycloak email user attribute.

    Screenshot 2026-08-24 at 4.48.24 PM.png
  • First Name: map the given_name claim to the Keycloak firstName user attribute.

    Screenshot 2026-08-24 at 4.48.58 PM.png
  • Last Name: map the family_name claim to the Keycloak lastName user attribute.

    Screenshot 2026-08-24 at 4.49.24 PM.png

Because the Okta application username is mapped from user.email, preferred_username should resolve to the user email for this integration. Mapping preferred_username to the Keycloak username keeps the protocol boundary clean and preserves the intended email-based username.


Step 10: Optional group and role mapping in Keycloak

Complete this section only if Okta sends groups or roles in the response.

Group mapping

If Okta sends group memberships, the token response should include a group attribute such as groups.

For a small number of groups, create an attribute-to-role mapper for each required mapping.

Setting

Value

Sync Mode Override

FORCE

Mapper Type

Attribute to Role or equivalent claim-to-role option

Attribute or Claim

groups

Attribute or Claim Value

Example: Apporto Admin

Role

Example: administrator

Role mapping

If Okta sends direct application roles, configure Keycloak to map the incoming role attribute such as roles.

Supported role names are:

  • msp-admin

  • administrator

  • sub-admin

  • faculty

  • tech-support


Step 11: Test the configuration

  1. Open the Apporto NextGen sign-in flow for the configured tenant.

  2. Choose the Okta OIDC identity provider option if prompted.

  3. Sign in with an Okta user that is allowed to access the OIDC application.

  4. Confirm Okta redirects the browser back to the Keycloak broker endpoint successfully.

  5. In Keycloak, verify that the user was created or linked with the expected username, email, first name, and last name.

  6. If group or role mapping is configured, verify the expected Keycloak client role and resulting Apporto role.

  7. Confirm the user can complete the Apporto sign-in flow successfully.

The validated flow created the Keycloak user with the expected username, email, first name, and last name values after successful Okta sign-in.


Troubleshooting

Issue

What to check

redirect_uri or callback error

The Okta Sign-in redirect URI must exactly match the Keycloak Redirect URI, including the broker alias.

invalid_client

Verify the Client ID and Client Secret are from the same Okta OIDC Web Application and that Keycloak uses HTTP Basic client authentication.

Issuer or signature error

Confirm the discovery endpoint and Issuer are from the same Okta authorization server. Keep Validate Signatures and Use JWKS URL enabled.

User is not assigned

Verify the application Controlled access setting and the user or group assignment in Okta.

Username is not email

Confirm Okta maps user.email to the app userName and Keycloak maps preferred_username to username.

First or last name missing

Confirm the profile scope is requested and given_name and family_name mappings exist. If necessary, turn Disable User Info Off so Keycloak can retrieve the full profile from Okta UserInfo.

Email missing

Confirm the email scope is requested and the Keycloak email mapper reads the email claim.

Group claim missing

Creating an Okta group alone is not enough. Add a groups token claim and confirm the claim expression returns the expected group name.

Group or role mapper does not apply

The Keycloak Claim and Claim Value must exactly match the value sent by Okta. Set Sync Mode Override to Force for role re-evaluation.

Existing user does not update

Sync mode Import does not continuously update all brokered attributes. Use a different sync strategy only when the tenant requires updates on later logins.


Final checklist

  • OpenID Connect v1.0 identity provider created in Keycloak
  • Provider alias added without spaces and Keycloak Redirect URI copied
  • Okta OIDC Web Application created
  • Authorization Code enabled and Keycloak Redirect URI registered exactly
  • Federation Broker Mode left disabled
  • Okta Client ID and Client Secret collected securely
  • Org Authorization Server discovery endpoint identified
  • Keycloak configured with discovery and HTTP Basic client authentication
  • Validate Signatures and Use JWKS URL enabled
  • Scopes set to openid email profile
  • Trust Email and Apporto first broker login reviewed
  • Users or groups allowed to access the Okta application
  • Okta profile mapping configured, including user.email to userName
  • Username, email, first-name, and last-name Keycloak mappers created
  • Optional groups claim configured if authorization mapping is required
  • Optional Claim to Role mapper configured and target client role exists
  • End-to-end sign-in tested successfully
  • Keycloak user profile validated after login

The Okta OpenID Connect Identity Provider is configured when eligible users can sign in to Apporto NextGen through Okta and Keycloak stores the expected profile and authorization values.