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
-
Add a SAML v2.0 identity provider in Keycloak and collect the Keycloak service provider values.
-
Create a Custom SAML application in miniOrange.
-
Enter the Keycloak Redirect URI and Service Provider Entity ID in the miniOrange application.
-
Configure NameID and required user attributes in miniOrange.
-
Import the IdP metadata into Keycloak.
-
Set up the DEFAULT policy in miniOrange.
-
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 miniOrange 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:
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.
-
Sign in to miniOrange at https://login.xecurify.com/.
-
In the left navigation menu, select Apps.
-
Click Add App.
-
Search for Custom SAML App and select it.
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 |
|
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.
Step 4: Configure SAML NameID and user attributes
Use the following settings where miniOrange supports them.
-
Open the Attribute tab of the miniOrange SAML application.
-
Set Name ID to E-mail Address.
-
Set Name ID Format to
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
-
Enable Enable Multi-Valued Attributes. This option returns multiple values as a list. Add multiple values separated by commas, for example
admin, editor, viewer.
Required and recommended attributes
Configure miniOrange to send the user attributes that Apporto NextGen needs.
|
Attribute name |
miniOrange attribute type |
Description |
|---|---|---|
|
|
E-mail Address |
User email address |
|
|
First Name |
User first name |
|
|
Last Name |
User last name |
|
|
Username |
Optional username attribute, if required by the tenant. |
|
|
User Groups |
Optional group membership claim. |
|
|
Custom Profile Attribute → Roles |
Optional role claim. |
Under Attribute Mapping, click Add Attribute and configure each required mapping using the exact names above.
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
-
Open the Custom SAML App in miniOrange.
-
Select the Metadata tab.
-
Copy the Metadata URL.
-
In Keycloak, paste the Metadata URL into SAML entity descriptor.
-
Click Add or Save. Keycloak imports the miniOrange SAML IdP metadata automatically.
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 |
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.
-
Select the DEFAULT group policy.
-
Verify that the First Factor is set to Password.
-
Confirm whether 2FA and Adaptive authentication are required for your setup, then edit the policy if changes are needed.
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.
-
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 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 |
|---|---|---|---|
|
|
Attribute Importer |
|
|
|
firstName |
Attribute Importer |
|
|
|
lastName |
Attribute Importer |
|
|
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 |
|
|
Mapper Type |
|
|
Attribute or Claim |
|
|
Attribute or Claim Value |
Example: |
|
Role |
Example: |
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
-
Open the Apporto NextGen sign-in flow for the configured tenant.
-
Choose the miniOrange SAML identity provider option if prompted.
-
Sign in with a user assigned to the Custom SAML App.
-
Confirm miniOrange redirects the browser back to the Keycloak broker endpoint successfully.
-
Confirm the user profile includes the expected email, username, 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 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.