Configuring miniOrange as a SAML 2.0 Identity Provider in Keycloak

This guide explains how to configure miniOrange 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 miniOrange, import miniOrange metadata, map user attributes, and validate sign-in.

Overview

Keycloak acts as the service provider for Apporto NextGen. miniOrange authenticates users and sends SAML assertions to Keycloak.

System

Purpose

Keycloak

Hosts the tenant realm and identity provider configuration.

miniOrange

Hosts the SAML application, user directory, metadata, attribute mapping, and optional group or role claims.

Before you begin

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

  • Confirm you have a miniOrange administrator account that can create and manage SAML applications.

  • Have a test miniOrange user available for validation.

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

  • Keep both Keycloak and the miniOrange 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 Custom SAML application in miniOrange.

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

  4. Configure NameID and required user attributes in miniOrange.

  5. Import the IdP metadata into Keycloak.

  6. Set up the DEFAULT policy in miniOrange.

  7. Review advanced Keycloak settings.

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

  9. Test sign-in end to end.


Instructions

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

miniorange-saml

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

Collect Keycloak service provider values

miniOrange field

Use this Keycloak value

ACS URL

Redirect URI

SP Entity ID / Issuer

Service provider entity ID

Audience URI

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 miniorange-saml, miniOrange must post the SAML response to /broker/miniorange-saml/endpoint exactly.


Step 2: Create the SAML application in miniOrange

Create a new Custom SAML App in miniOrange. This application authenticates users and sends them to Apporto NextGen after successful sign-in.

  1. Sign in to miniOrange at https://login.xecurify.com/.

  2. In the left navigation menu, select Apps.

  3. Click Add App.

  4. Search for Custom SAML App and select it.

Screenshot 2026-06-25 at 3.28.02 PM.png

Step 3: Enter Keycloak details in the miniOrange application

In miniOrange, enter the Keycloak values collected in Step 1.

miniOrange setting

Value to enter

Display Name

Application name, for example Keycloak or Apporto SAML Login.

SP Entity ID / Issuer

Keycloak service provider entity ID.

ACS URL

Keycloak Redirect URI.

Audience URI

Keycloak service provider entity ID; use the same value as SP Entity ID / Issuer.

Single Logout URL

Optional. Leave blank unless the customer requires SAML single logout.

The ACS 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 miniOrange authentication.

image1_keycloak_basic_redacted-20260708-011423.png

Step 4: Configure SAML NameID and user attributes

Use the following settings where miniOrange supports them.

  1. Open the Attribute tab of the miniOrange SAML application.

  2. Set Name ID to E-mail Address.

  3. Set Name ID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Screenshot 2026-06-25 at 5.05.28 PM.png
  1. Enable Enable Multi-Valued Attributes. This option returns multiple values as a list. Add multiple values separated by commas, for example admin, editor, viewer.

    Screenshot 2026-09-09 at 1.00.35 PM.png

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

Attribute name

miniOrange attribute type

Description

email

E-mail Address

User email address

firstName

First Name

User first name

lastName

Last Name

User last name

adName

Username

Optional username attribute, if required by the tenant.

Groups

User Groups

Optional group membership claim.

Roles

Custom Profile Attribute → Roles

Optional role claim.

Under Attribute Mapping, click Add Attribute and configure each required mapping using the exact names above.

Screenshot 2026-06-25 at 5.06.09 PM.png


At minimum, send a unique NameID and an email address. First name and last name are recommended. Attribute names are case-sensitive and must exactly match the names used in Keycloak mappers.


Step 5: Import miniOrange metadata into Keycloak

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

Option A: Use a metadata URL

  1. Open the Custom SAML App in miniOrange.

  2. Select the Metadata tab.

  3. Copy the Metadata URL.

image2_metadata_redacted-20260708-011551.png
  1. In Keycloak, paste the Metadata URL into SAML entity descriptor.

  2. Click Add or Save. Keycloak imports the miniOrange SAML IdP metadata automatically.

Screenshot 2026-06-25 at 4.47.36 PM.png

Option B: Enter values manually

If metadata is not available, enter the values manually.

Keycloak field

miniOrange value

Identity Provider entity ID

miniOrange IdP Entity ID or Issuer

Single Sign-On Service URL

miniOrange SAML Login URL

Single Logout Service URL

Logout URL, if supported

Validating X509 certificate

miniOrange signing certificate

image3_saml_settings_redacted-20260708-011728.png

Use a Metadata URL where available. Metadata import automatically imports the required SAML configuration and reduces manual configuration errors.


Step 6: Set up the DEFAULT policy in miniOrange

After configuring the SAML settings, open the Policies tab in the miniOrange configuration.

  1. Select the DEFAULT group policy.

  2. Verify that the First Factor is set to Password.

  3. Confirm whether 2FA and Adaptive authentication are required for your setup, then edit the policy if changes are needed.

    Screenshot 2026-09-09 at 12.55.57 PM.png

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 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
  1. Keep HTTP-POST binding response, HTTP-POST binding for AuthnRequest, HTTP-POST binding logout, and Validate Signatures turned on.

  2. Leave Want AuthnRequests signed off unless required.

  3. Leave Want Assertions encrypted off unless required.

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

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

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

    adv settings.png
  7. 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 8: Map user attributes in Keycloak

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

On the Keycloak SAML identity provider, open the Mapper tab and create mappers for the SAML assertion attributes listed below.

User field

Mapper type

SAML 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-03 at 5.13.51 PM.png

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


Step 9: Optional group and role mapping in Keycloak

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

Group mapping

If miniOrange sends group memberships, the SAML assertion should include a group attribute such as Groups.

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 miniOrange 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 a miniOrange group alone is not enough. The group must be included in the SAML assertion before Keycloak can map it to a role.


Step 10: Test the configuration

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

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

  3. Sign in with a user assigned to the Custom SAML App.

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

  5. Confirm the user profile includes the expected email, username, 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 miniOrange ACS URL must exactly match the Keycloak Redirect URI, including the broker alias.

Invalid audience

The miniOrange Audience URI must exactly match the Keycloak service provider entity ID.

Invalid signature

Keycloak must trust the signing certificate contained in the current miniOrange metadata.

Missing email address

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

User is not assigned

Confirm the user can access the miniOrange Custom SAML App.

Group is not in the assertion

miniOrange group membership alone does not help unless the group attribute is included in the SAML response.

Group or role mapping does not work

The SAML attribute name and value in Keycloak must exactly match the values sent by miniOrange.

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 miniOrange ACS URL
  • Keycloak service provider entity ID copied to the miniOrange SP Entity ID / Issuer and Audience URI fields
  • NameID and required user attributes configured
  • Optional groups or roles configured and emitted in SAML if role mapping is required
  • miniOrange 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 miniOrange SAML 2.0 Identity Provider is configured when users can sign in to Apporto NextGen through miniOrange and receive the expected profile and authorization values.