Configure a SAML 2.0 Identity Provider in Keycloak

This guide explains how to connect an organisation’s SAML 2.0 Identity Provider (IdP) to Apporto NextGen through Keycloak. Use it as an end-to-end setup checklist: create the Keycloak SAML broker, configure the SAML application in the IdP, import IdP metadata, map user attributes, and validate sign-in.


Overview

Keycloak acts as the service provider for Apporto NextGen. Your organisation’s SAML Identity Provider authenticates users and sends SAML assertions to Keycloak.

System

Purpose

Keycloak

Hosts the tenant realm and identity provider configuration.

Organisation SAML Identity Provider

Hosts the SAML application, claims or attributes, signing certificate, and optional group or role assignments.

Before you begin

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

  • Confirm you have administrator access to the organisation’s SAML Identity Provider.

  • Decide the IdP attribute names that will be sent for username, email, first name, last name, and optional groups or roles.

  • Keep both Keycloak and the IdP 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 the organisation’s Identity Provider.

  3. Enter the Keycloak ACS URL and entity ID in the IdP application.

  4. Configure SAML security, NameID, and user attributes in the IdP.

  5. Import the IdP metadata into Keycloak.

  6. Review advanced Keycloak settings.

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

  8. Assign users or groups to the SAML application and test sign-in.


Step 1: Add the 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:

customer-saml

Keep this Keycloak page open. You will need the Redirect URI and Service provider entity ID when setting up the SAML application in the Identity Provider.

Collect Keycloak service provider values

Identity Provider field

Use this Keycloak value

ACS URL, Reply URL, or Callback URL

Redirect URI

Entity ID, Identifier, or Audience

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>

Step 2: Create the SAML application in the Identity Provider

Create a new SAML 2.0 application or Service Provider integration in the organisation’s Identity Provider. This application authenticates users and sends them to Apporto NextGen after successful sign-in.

  1. Sign in to the Identity Provider administration console.

  2. Create a new SAML 2.0 application or Service Provider integration.

  3. The exact menu name varies by provider. Look for options such as Create SAML application, Create app integration, Add enterprise application, Add custom SAML app, or Add relying party trust.

  4. If prompted, choose SAML 2.0 as the sign-in method. If the provider asks for the application type, choose a custom or non-gallery SAML application.

  5. Name the application Apporto NextGen, or use another name that administrators will recognise.

  6. Continue to the SAML configuration screen.


Step 3: Enter Keycloak details in the IdP application

In the Identity Provider, enter the Keycloak values collected in Step 1.

Identity Provider setting

Value to enter

Entity ID, Identifier, or Audience

Keycloak service provider entity ID

ACS URL, Reply URL, or Callback URL

Keycloak Redirect URI

SAML version

SAML 2.0

Response binding

HTTP-POST

Relay State

Leave blank unless your organisation requires it

Sign-on URL

Optional


Step 4: Configure SAML security in the Identity Provider

Use the following settings where the Identity Provider supports them.

Setting

Recommended value

Sign SAML response

Enabled

Sign assertion

Enabled

Encrypt assertion

Optional

Response binding

HTTP-POST

NameID format

Email address

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


Step 5: Configure NameID and user attributes in the IdP

The SAML response must include a NameID that uniquely identifies each user. We recommend using the user’s email address or user principal name.

NameID settings

Setting

Recommended value

NameID format

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress Or Unspecified

NameID value

User email address or user principal name

Configure the Identity Provider to send the user attributes that Apporto NextGen needs.

Attribute name

Description

email

User email address

username

User sign-in name

firstName

User first name

lastName

User last name

groups

Group memberships, if used

roles

Application role, if used

The provider may use different attribute names, such as mail, givenName, surname, memberOf, or role. That is fine, but the same names must be used later when configuring mappers in Keycloak.

At minimum, send a unique username or NameID and an email address. First name and last name are recommended.


Step 6: Import IdP metadata into Keycloak

Return to the SAML Identity Provider configuration in Keycloak and import the metadata from the Identity Provider.

Option A: Use a metadata URL

  1. Paste the metadata URL into SAML entity descriptor.

  2. Click Add.

keycloak meta.png

Option B: Use a metadata XML file

Import the metadata XML file provided by the Identity Provider.

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

Identity Provider value

Identity Provider entity ID

IdP Entity ID or Issuer

Single Sign-On Service URL

SAML Login URL

Single Logout Service URL

Logout URL, if supported

Validating X509 certificate

Identity Provider 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 7: Review advanced Keycloak settings

After the metadata is imported, review the SAML Identity Provider settings in Keycloak. Configure only the following fields unless the Identity Provider requires something different.

  1. Open the SAML Identity Provider configuration in Keycloak.

  2. In the SAML settings, keep HTTP-POST binding response, HTTP-POST binding for AuthnRequest, HTTP-POST binding logout, and Validate Signatures turned on.

  3. Set NameID policy format to Unspecified.

  4. Set Principal type to Attribute [Name].

  5. Set Principal attribute to email.

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

Click Save after reviewing the configuration.


Step 8: Map user attributes in Keycloak

Create mappers so Keycloak can read the user attributes sent in the SAML assertion.

Keycloak Mappers.png
  1. In Keycloak, go to Identity Providers → Your SAML Provider → Mappers.

  2. Click Add mapper.

  3. Create the recommended mappers listed below.

User field

Mapper type

SAML attribute name

Keycloak user attribute name

Username

Attribute Importer

username

username

Email

Attribute Importer

email

email

First Name

Attribute Importer

firstName

firstName

Last Name

Attribute Importer

lastName

lastName

Screenshot 2026-08-03 at 5.14.20 PM.png
Screenshot 2026-08-03 at 5.14.05 PM.png
Screenshot 2026-08-03 at 5.13.27 PM.png
Screenshot 2026-08-03 at 5.13.51 PM.png

If the username is provided only in the NameID, use the appropriate NameID-based mapper instead.

Attribute names are case-sensitive. They must exactly match the names sent by the Identity Provider.


Step 9: Optional group and role mapping

Complete this section only if the Identity Provider sends groups or roles in the SAML response.

Group mapping

If the Identity Provider sends group memberships, the SAML assertion should include a group attribute such as groups.

For a small number of groups, create an attribute-to-group mapper for each group and set Sync Mode Override to FORCE.

If the Group Sync Mapper is available, configure it as follows:

Setting

Value

Sync Mode Override

FORCE

Mapper Type

Group Sync Mapper

Group Claim / Attribute Name

groups

Role mapping

If the Identity Provider sends application roles, configure it to send a role attribute such as roles.

Supported role names are:

  • msp-admin

  • administrator

  • sub-admin

  • faculty

  • tech-support

Create an Attribute to Role mapper in Keycloak for each role value you need.

Setting

Value

Sync Mode Override

FORCE

Mapper Type

Claim to Role

Claim

roles

Claim Value

e.g. msp-admin

Role

e.g. msp-admin


Step 10: Assign users or groups to the SAML application

Some Identity Providers require users or groups to be assigned to the SAML application before they can sign in.

  1. In the Identity Provider, open the SAML application.

  2. Assign the required users or groups.

  3. Confirm that the application is enabled.

If a user is not assigned to the application, they may not be able to sign in.


Step 11: Test the configuration

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

  2. Choose the SAML identity provider option if prompted.

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

  4. Confirm the user is redirected back successfully.

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

  6. If groups or roles are configured, confirm the expected groups or roles are applied.


Troubleshooting

Issue

What to check

Invalid destination

The ACS URL in the Identity Provider must match the Keycloak Redirect URI.

Invalid audience

The Entity ID in the Identity Provider must match the Keycloak service provider entity ID.

Invalid signature

The signing certificate in Keycloak must match the certificate used by the Identity Provider.

Missing email address

The SAML assertion must include an email attribute, and the Keycloak email mapper must use the same attribute name.

User is not assigned

The user must be assigned to the SAML application in the Identity Provider.

Invalid NameID

The NameID must be present, unique, and use a supported format.

Group or role mapping does not work

The attribute name and value in Keycloak must exactly match the values in the SAML assertion.


Final checklist

  • SAML v2.0 identity provider created in Keycloak
  • Provider alias added without spaces
  • Keycloak Redirect URI copied to the IdP ACS, Reply, or Callback URL
  • Keycloak service provider entity ID copied to the IdP Entity ID, Identifier, or Audience field
  • SAML response or assertion signing enabled
  • NameID and required user attributes configured
  • IdP 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
  • Users or groups assigned to the SAML application
  • Sign-in tested successfully

The SAML 2.0 Identity Provider is configured when users assigned to the SAML application can sign in to Apporto NextGen through the organisation’s Identity Provider.