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
-
Add an OpenID Connect v1.0 provider in Keycloak and copy the generated Redirect URI.
-
Create an OIDC Web Application in Okta.
-
Enable Authorization Code and register the Keycloak Redirect URI.
-
Configure Okta application access and save the app.
-
Collect the Okta Client ID, Client Secret, and OIDC discovery endpoint.
-
Configure the Okta discovery endpoint and client authentication in Keycloak.
-
Review OIDC endpoints, signature validation, scopes, and advanced Keycloak settings.
-
Assign users or groups to the Okta application.
-
Configure the Okta OIDC user profile mapping.
-
Create Keycloak identity provider mappers for username, email, first name, and last name.
-
Optionally configure Okta group claims and Keycloak claim-to-role mappings.
-
Test sign-in end to end.
Instructions
Step 1: Add the Okta OpenID Connect provider in Keycloak
-
Sign in to the Keycloak administration console.
-
Select the customer tenant realm.
-
Go to Identity Providers.
-
Click Add provider.
-
Select OpenID Connect v1.0.
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.
-
Sign in to the Okta Admin Console.
-
Go to Applications and Resources > Applications.
-
Click Create App Integration.
-
Select OIDC - OpenID Connect.
-
For Application type, select Web Application.
-
Click Next.
-
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 |
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.
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 |
|
|
Discovery endpoint |
|
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 |
|
|
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.
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 |
|
|
Token URL |
|
|
User Info URL |
|
|
Issuer |
|
|
JWKS URL |
|
|
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
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 |
|
|
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.
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.
-
Open the Apporto OIDC Login application.
-
Select Assignments.
-
Assign the required people or groups according to the access model selected during app creation.
-
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.
Select the mapping direction Okta User to Apporto OIDC Login. Okta creates the standard OIDC App User profile fields automatically.
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.
|
Okta user attribute |
OIDC app profile field |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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_usernameclaim to the Keycloakusernameuser attribute.
-
Email: map the
emailclaim to the Keycloakemailuser attribute.
-
First Name: map the
given_nameclaim to the KeycloakfirstNameuser attribute.
-
Last Name: map the
family_nameclaim to the KeycloaklastNameuser attribute.
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 |
|
|
Mapper Type |
|
|
Attribute or Claim |
|
|
Attribute or Claim Value |
Example: |
|
Role |
Example: |
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
-
Open the Apporto NextGen sign-in flow for the configured tenant.
-
Choose the Okta OIDC identity provider option if prompted.
-
Sign in with an Okta user that is allowed to access the OIDC application.
-
Confirm Okta redirects the browser back to the Keycloak broker endpoint successfully.
-
In Keycloak, verify that the user was created or linked with the expected username, email, first name, and last name.
-
If group or role mapping is configured, verify the expected Keycloak client role and resulting Apporto role.
-
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 |
|
First or last name missing |
Confirm the |
|
Email missing |
Confirm the |
|
Group claim missing |
Creating an Okta group alone is not enough. Add a |
|
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.emailtouserName - 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.