SAML Configuration Guide¶

SAML is configured through the Keycloak Admin UI. Altair SLC Hub uses Keycloak as its identity broker, and SAML identity providers are managed directly in Keycloak without requiring a Altair SLC Hub restart or re-bootstrap.

Tip

For detailed information on protocol mappers and SAML configuration in Keycloak, see the official Keycloak documentation.

To access the Keycloak Admin UI, navigate to:

<hub-url>/keycloak/admin/slchub/console

Log in with your Keycloak admin credentials.

Step 1 — Configure SAML in Keycloak¶

In the Keycloak Admin UI, select the slchub realm.
In the left menu, click Identity Providers.
Click Add provider and select SAML v2.0.
Fill in the basic details:
- Alias: A unique identifier for this IdP (e.g., okta-saml, azure-ad-saml). This becomes part of the ACS URL, so choose something stable. Changing it later requires updating the IdP.
- Display name: What users see on the login page (e.g., "Log in with Okta", "Company SSO").
Import SAML Metadata:
- Enable the Use entity descriptor toggle.
- Paste your IdP's SAML metadata URL into the SAML entity descriptor field.
- Keycloak will fetch the signing certificate and SSO endpoints automatically.

Note

If your IdP does not publish a metadata URL, disable the Use entity descriptor toggle and fill in the endpoint fields manually.

Click Save.

Common SAML metadata URL formats¶

Provider	Metadata URL Format
Okta	`https://<org>.okta.com/app/<app-id>/sso/saml/metadata`
Azure AD / Microsoft Entra	`https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml`
AWS IAM Identity Center	`https://portal.sso.<region>.amazonaws.com/saml/metadata/<app-id>`
Other SAML 2.0 providers	Check your provider's documentation or "Single Sign-On" / "Security" settings

Step 2 — Register Altair SLC Hub as a Service Provider in your IdP¶

Now your IdP needs to know about Altair SLC Hub.

After saving the identity provider in Keycloak, go to its Settings tab and copy the ACS URL shown there:
```
<hub-url>/keycloak/realms/slchub/broker/<alias>/endpoint
```
Log into your external IdP's admin console and find the application you created for Altair SLC Hub.
Register this in your IdP application as the ACS URL (also called Callback URL or Reply URL).
Also set the SP Entity ID (Audience URI) to:
```
<hub-url>/keycloak/realms/slchub
```
Save the changes in your IdP.

Step 3 — Configure attribute mappers¶

Why attribute mappers needed

Your IdP sends user information (email, name, etc.) in a SAML assertion, but it may use different attribute names than Altair SLC Hub expects. Mappers translate these names so Altair SLC Hub understands the user's data.

Without correct mappers: Users can log in successfully, but their user attributes will be missing or incorrect, and they may not have the right permissions or home directories to run workloads.

For detailed instructions, see Mapping claims and assertions in the official Keycloak documentation.

Altair SLC Hub requires the following user attributes:

Altair SLC Hub attribute	Default SAML attribute name	Description
`email`	`email`	Email Address
`firstName`	`firstName`	Given name
`lastName`	`lastName`	Family name
`displayName`	`displayName`	User's display name
`unixUserName`	`unixUserName`	Linux OS username on Altair SLC Hub server and workers
`unixHomeDirectory`	`unixHomeDirectory`	Linux home directory path
`userPrincipalName`	`userPrincipalName`	Windows UPN (required for Windows workers only)

Add an Attribute Importer mapper in Keycloak for each one.

Finding IdP attribute names

Different IdPs use different attribute naming conventions:

Okta: Attributes are often named user.email, user.firstName, user.lastName
Azure AD: Uses claim URIs like http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
AWS IAM Identity Center: Commonly email, name, givenName, surname

Check your IdP's SAML metadata URL or admin documentation.

For each mapper:

In the identity provider, go to the Mappers tab.
Click Add mapper.
Set Mapper type to Attribute Importer.
Set Attribute to the name sent by the IdP.
Set User Attribute to the Altair SLC Hub attribute name from the table above.
Click Save.

Hub ExternalIdp Mapper¶

There's an additional mapper named Hub ExternalIdp Mapper. This mapper does not need to be created manually. It is created automatically whenever an IdP is created and is used to mark users as external by setting the IdP alias value by default.

Step 4 — Add a Group Mapper¶

SAML users who authenticate successfully are created in Keycloak but have no Altair SLC Hub permissions by default. You must add a hardcoded group mapper to automatically assign them to the HubUsers group (and/or other groups) on first login.

In the identity provider, go to the Mappers tab.
Click Add mapper.
Set Mapper type to Hardcoded Group.
Set Group to /HubUsers (or other groups).
Click Save.

This grants SAML users the base User role. To grant additional roles (e.g. admin access), add users to the appropriate groups in Keycloak after their first login, or add further hardcoded group mappers for groups.

Step 5 — Set the Sync Mode¶

The Sync mode determines how often Keycloak updates user attributes from your IdP.

In the identity provider Settings tab, set Sync mode to control how user attributes are updated on subsequent logins:

Mode	Behaviour
`Import`	Creates the local user on first login; does not re-import attributes on subsequent logins.
`Force`	Re-imports all mapped attributes on every login, keeping the local user in sync with the IdP.

Use Force if you want the IdP to remain the source of truth for user attributes (e.g. name changes in the IdP are reflected in Hub on next login).

Step 6 — Test the integration¶

Log out of Altair SLC Hub.
Click Log in and select your IdP name (e.g., "Log in with Okta").
You should be redirected to your IdP's login page. Enter your credentials.
After authenticating, you should be redirected back to Altair SLC Hub and logged in.
Check that you can access the portal and see your user details (click the profile icon in the top-right).

Tip

See the Troubleshooting Guide if you experience issues.