Configure Okta as a SAML 2.0 Identity Provider in Keycloak

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

  1. Add a SAML v2.0 identity provider in Keycloak and collect the Keycloak service provider values.

  2. Create a SAML 2.0 application in Okta.

  3. Enter the Keycloak Redirect URI and Service Provider Entity ID in the Okta application.

  4. Configure SAML signing, NameID, and required user attributes in Okta.

  5. Optionally create Okta groups and configure them for authorization.

  6. Assign users or groups to the Okta SAML application.

  7. Import the IdP metadata into Keycloak.

  8. Review advanced Keycloak settings.

  9. Create Keycloak mappers for user attributes and optional groups or roles.

  10. Test sign-in end to end.


Instructions

Step 1: Add the Okta SAML provider in Keycloak

  1. Sign in to the Keycloak administration console.

  2. Select the customer realm.

  3. Go to Identity Providers.

  4. Click Add provider.

  5. Select SAML v2.0.

Screenshot 2026-08-03 at 5.24.38 PM.png

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.

  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 SAML 2.0 and click Next.

    Screenshot 2026-08-17 at 3.48.14 PM.png
  5. Enter an application name such as Apporto SAML Login.

  6. Optionally add a logo.

  7. Click Next to continue to the SAML configuration screen.

    Screenshot 2026-08-17 at 3.50.21 PM.png

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

Email

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.

Screenshot 2026-08-17 at 3.52.34 PM.png

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

Screenshot 2026-08-23 at 7.39.25 PM.png

Enable signed SAML responses or signed assertions so Keycloak can verify that the sign-in response came from Okta.

Configure Okta to send the user attributes that Apporto NextGen needs.

Attribute name

Okta expression

Description

email

user.profile.email

User email address

firstName

user.profile.firstName

User first name

lastName

user.profile.lastName

User last name

To add these attributes in Okta:

  1. Open the SAML application and go to the Sign On tab.

  2. Scroll to Attribute statements.

  3. Click Add expression.

    Screenshot 2026-08-17 at 4.04.52 PM.png
  4. Add each attribute using the exact names and expressions shown above.

    Screenshot 2026-08-17 at 4.05.55 PM.png
    Screenshot 2026-08-17 at 4.05.28 PM.png
    Screenshot 2026-08-17 at 4.05.10 PM.png

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

  1. In Okta, go to Directory > Groups.

    Screenshot 2026-08-17 at 5.34.08 PM.png
  2. Create the required group, such as Apporto Admin.

    Screenshot 2026-08-17 at 5.35.37 PM.png
  3. 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.

  1. Open the Okta SAML application.

  2. Select Assignments.

  3. Click Assign.

    Screenshot 2026-08-17 at 5.36.44 PM.png
  4. Select Assign to People, or assign a group if that better matches your access model.

    Screenshot 2026-08-17 at 5.37.17 PM.png
  5. Confirm the application username and save the assignment.

  6. Verify the user appears under Assignments.

    Screenshot 2026-08-17 at 5.37.32 PM.png

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

  1. In Okta, open the SAML application and select the Sign On tab.

  2. Locate Metadata details and copy the Metadata URL.

    1bfdef2a-e3dc-419f-b636-d0b7fe65179e
  3. In Keycloak, paste the Metadata URL into SAML entity descriptor.

  4. Click Add or Save.

    keycloak meta.png


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.

Screenshot 2026-08-03 at 5.25.33 PM.png

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.

  1. Open the SAML Identity Provider configuration in Keycloak.

  2. In the SAML settings, set NameID policy format to Email and Principal type to Subject NameID.

    Screenshot 2026-08-31 at 10.32.05 PM.png
  3. Keep HTTP-POST binding response, HTTP-POST binding for AuthnRequest, HTTP-POST binding logout, and Validate Signatures turned on.

  4. Leave Want AuthnRequests signed off unless required.

  5. Leave Want Assertions encrypted off unless required.

    adv settings 2.png
  6. In Advanced settings, turn on Trust Email.

  7. Set First login flow override to Apporto first broker login. This flow is already provisioned with the realm.

  8. Leave Post login flow as None, Sync mode as Import, and Case-sensitive username turned off.

    adv settings.png
  9. 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.

Screenshot 2026-08-23 at 7.24.45 PM.png
  1. In Keycloak, go to Identity Providers → Your Okta Provider → Mappers.

  2. Click Add mapper.

  3. Create the recommended mappers listed below.

User field

Mapper type

Okta attribute name

Keycloak user attribute name

email

Attribute Importer

email

email

firstName

Attribute Importer

firstName

firstName

lastName

Attribute Importer

lastName

lastName

Screenshot 2026-08-03 at 5.14.05 PM.png
Screenshot 2026-08-03 at 5.13.27 PM.png
Screenshot 2026-08-24 at 4.49.24 PM.png

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

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

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

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

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

  3. Sign in with a user assigned to the SAML application.

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

  5. Confirm the user profile includes the expected email, first name, and last name.

  6. 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.