This guide explains how to configure Okta as the SAML 2.0 Identity Provider for Apporto NextGen through Keycloak. Use it as an end-to-end setup checklist to create the Keycloak SAML broker, configure the SAML application in Okta, import Okta metadata, map user attributes, and validate sign-in.
Overview
Keycloak acts as the service provider for Apporto NextGen. Okta authenticates users and sends SAML assertions to Keycloak.
|
System |
Purpose |
|---|---|
|
Keycloak |
Hosts the tenant realm and identity provider configuration. |
|
Okta |
Hosts the SAML application, user directory, signing certificate, attribute statements, and optional group-based access assignments. |
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 application integrations.
-
Have a test Okta user available for validation.
-
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 a SAML v2.0 identity provider in Keycloak and collect the Keycloak service provider values.
-
Create a SAML 2.0 application in Okta.
-
Enter the Keycloak Redirect URI and Service Provider Entity ID in the Okta application.
-
Configure SAML signing, NameID, and required user attributes in Okta.
-
Optionally create Okta groups and configure them for authorization.
-
Assign users or groups to the Okta SAML application.
-
Import the IdP metadata into Keycloak.
-
Review advanced Keycloak settings.
-
Create Keycloak mappers for user attributes and optional groups or roles.
-
Test sign-in end to end.
Instructions
Step 1: Add the Okta SAML provider in Keycloak
-
Sign in to the Keycloak administration console.
-
Select the customer realm.
-
Go to Identity Providers.
-
Click Add provider.
-
Select SAML v2.0.
Set the provider alias
Enter a short, unique alias for the provider. Do not use spaces.
Example:
okta-saml
Keep this Keycloak page open. You will need the Redirect URI and Service provider entity ID when setting up the SAML application in Okta.
Collect Keycloak service provider values
|
Okta field |
Use this Keycloak value |
|---|---|
|
Single sign-on URL |
Redirect URI |
|
Audience URI (SP Entity ID) |
Service provider entity ID |
Example Redirect URI:
https://<keycloak-host>/realms/<realm-name>/broker/<alias>/endpoint
Example Service Provider Entity ID:
https://<keycloak-host>/realms/<realm-name>
The provider alias becomes part of the Keycloak ACS or Redirect URI. If the alias is okta-saml, Okta must post the SAML response to /broker/okta-saml/endpoint exactly.
Step 2: Create the SAML application in Okta
Create a new SAML 2.0 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 SAML 2.0 and click Next.
-
Enter an application name such as Apporto SAML Login.
-
Optionally add a logo.
-
Click Next to continue to the SAML configuration screen.
Step 3: Enter Keycloak details in the Okta application
In Okta, enter the Keycloak values collected in Step 1.
|
Okta setting |
Value to enter |
|---|---|
|
Single sign-on URL |
Keycloak Redirect URI |
|
Use this for Recipient URL and Destination URL |
Enabled |
|
Audience URI (SP Entity ID) |
Keycloak service provider entity ID |
|
Default RelayState |
Leave blank unless your environment requires it |
|
Name ID format |
EmailAddress |
|
Application username |
|
|
Update application username on |
Create and update |
The Single sign-on URL must exactly match the Keycloak Redirect URI, including the broker alias. A mismatch can result in a Keycloak page not found or invalid destination error after Okta authentication.
Step 4: Configure SAML security, NameID, and user attributes
Use the following settings where Okta supports them.
|
Setting |
Recommended value |
|---|---|
|
SAML response |
Signed |
|
Assertion Signature |
Signed |
|
Signature Algorithm |
RSA-SHA256 |
|
Digest Algorithm |
SHA-256 |
|
Assertion encryption |
Optional |
Enable signed SAML responses or signed assertions so Keycloak can verify that the sign-in response came from Okta.
Required and recommended attributes
Configure Okta to send the user attributes that Apporto NextGen needs.
|
Attribute name |
Okta expression |
Description |
|---|---|---|
|
|
|
User email address |
|
|
|
User first name |
|
|
|
User last name |
To add these attributes in Okta:
-
Open the SAML application and go to the Sign On tab.
-
Scroll to Attribute statements.
-
Click Add expression.
-
Add each attribute using the exact names and expressions shown above.
email, firstName, and lastName are standard Okta user profile attributes. They do not need to be added to the SAML app profile when the claims reference user.profile.* directly.
At minimum, send a unique NameID and an email address. First name and last name are recommended.
Step 5: Optional group and role mapping in Okta
Complete this section only if Okta groups or claims will be used for authorization.
Group mapping
-
In Okta, go to Directory > Groups.
-
Create the required group, such as Apporto Admin.
-
Add the appropriate users to the group.
If group membership must be sent to Keycloak, configure the Okta SAML application to emit a group attribute such as groups. The SAML assertion must contain the exact group names that Keycloak will map.
Role mapping
If your environment uses direct role claims instead of groups, configure Okta to send a role attribute such as roles.
Supported role names are:
-
msp-admin -
administrator -
sub-admin -
faculty -
tech-support
Okta group membership and SAML application assignment are different. Adding a user to a group does not automatically send that group in SAML, and it does not automatically grant access to the application.
Step 6: Assign users or groups to the SAML application
Okta requires the user or a group containing the user to be assigned to the application before the user can sign in through the SAML integration.
-
Open the Okta SAML application.
-
Select Assignments.
-
Click Assign.
-
Select Assign to People, or assign a group if that better matches your access model.
-
Confirm the application username and save the assignment.
-
Verify the user appears under Assignments.
If you assign a group to the application instead, all eligible members of that group can receive access according to the Okta assignment.
Step 7: Import Okta metadata into Keycloak
Return to the SAML Identity Provider configuration in Keycloak and import the metadata from Okta.
Option A: Use a metadata URL
-
In Okta, open the SAML application and select the Sign On tab.
-
Locate Metadata details and copy the Metadata URL.
-
In Keycloak, paste the Metadata URL into SAML entity descriptor.
-
Click Add or Save.
Option B: Use a metadata XML file
If needed, download the metadata XML from Okta and import the file into Keycloak.
After importing, confirm that Keycloak has populated the Identity Provider entity ID, Single Sign-On Service URL, and signing certificate.
Option C: Enter values manually
If metadata is not available, enter the values manually.
|
Keycloak field |
Okta value |
|---|---|
|
Identity Provider entity ID |
Okta IdP Entity ID or Issuer |
|
Single Sign-On Service URL |
Okta SAML Login URL |
|
Single Logout Service URL |
Logout URL, if supported |
|
Validating X509 certificate |
Okta signing certificate |
Use a Metadata URL or Metadata XML file where available. Metadata import automatically imports the required SAML configuration and reduces manual configuration errors.
Step 8: Review advanced Keycloak settings
After the metadata is imported, review the SAML Identity Provider settings in Keycloak. Configure only the following fields unless your tenant requires something different.
-
Open the SAML Identity Provider configuration in Keycloak.
-
In the SAML settings, set NameID policy format to Email and Principal type to Subject NameID.
-
Keep HTTP-POST binding response, HTTP-POST binding for AuthnRequest, HTTP-POST binding logout, and Validate Signatures turned on.
-
Leave Want AuthnRequests signed off unless required.
-
Leave Want Assertions encrypted off unless required.
-
In Advanced settings, turn on Trust Email.
-
Set First login flow override to Apporto first broker login. This flow is already provisioned with the realm.
-
Leave Post login flow as None, Sync mode as Import, and Case-sensitive username turned off.
-
Click Save after reviewing the configuration.
For the principal, use the email attribute or the email NameID according to your realm standard. The SAML assertion must contain a stable, unique user identifier.
Step 9: Map user attributes in Keycloak
Create mappers so Keycloak can read the user attributes sent in the SAML assertion.
-
In Keycloak, go to Identity Providers → Your Okta Provider → Mappers.
-
Click Add mapper.
-
Create the recommended mappers listed below.
|
User field |
Mapper type |
Okta attribute name |
Keycloak user attribute name |
|---|---|---|---|
|
|
Attribute Importer |
|
|
|
firstName |
Attribute Importer |
|
|
|
lastName |
Attribute Importer |
|
|
Attribute names are case-sensitive. They must exactly match the names sent by Okta.
Step 10: Optional group and role mapping in Keycloak
Complete this section only if Okta sends groups or roles in the SAML response.
Group mapping
If Okta sends group memberships, the SAML assertion 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
Creating an Okta group alone is not enough. The group must be included in the SAML assertion before Keycloak can map it to a role.
Step 11: Test the configuration
-
Open the Apporto NextGen sign-in flow for the configured tenant.
-
Choose the Okta SAML identity provider option if prompted.
-
Sign in with a user assigned to the SAML application.
-
Confirm Okta redirects the browser back to the Keycloak broker endpoint successfully.
-
Confirm the user profile includes the expected email, first name, and last name.
-
If groups or roles are configured, confirm the expected Keycloak or Apporto role is applied.
Troubleshooting
|
Issue |
What to check |
|---|---|
|
Page not found or invalid destination |
The Okta Single sign-on URL, Recipient, and Destination must exactly match the Keycloak Redirect URI, including the broker alias. |
|
Invalid audience |
The Okta Audience URI must exactly match the Keycloak service provider entity ID. |
|
Invalid signature |
Keycloak must trust the signing certificate contained in the current Okta metadata. |
|
Missing email address |
The Okta assertion must include an email attribute, and the Keycloak email mapper must use the same attribute name. |
|
User is not assigned |
Assign the user or an eligible group to the Okta SAML application. |
|
Group is not in the assertion |
Okta group membership alone does not emit a SAML claim. Configure a groups attribute or group claim in the SAML application. |
|
Group or role mapping does not work |
The SAML attribute name and value in Keycloak must exactly match the values sent by Okta. |
|
Invalid NameID |
Confirm the NameID is present, unique, and uses the format expected by Keycloak. |
Final checklist
- SAML v2.0 identity provider created in Keycloak
- Provider alias added without spaces
- Keycloak Redirect URI copied to the Okta Single sign-on URL
- Keycloak service provider entity ID copied to the Okta Audience URI field
- SAML response or assertion signing enabled
- NameID and required user attributes configured
- Optional groups configured and emitted in SAML if role mapping is required
- Users or groups assigned to the Okta SAML application
- Okta metadata imported into Keycloak or values entered manually
- Advanced Keycloak settings reviewed and saved
- User attribute mappers created in Keycloak
- Optional group or role mappers created, if required
- Sign-in tested successfully
The Okta SAML 2.0 Identity Provider is configured when users assigned to the SAML application can sign in to Apporto NextGen through Okta and receive the expected profile and authorization values.