OIDC Configuration¶

Before You Start¶

Goal

Connect Altair SLC Hub to an external OIDC Identity Provider (IdP) to allow end users to authenticate via single sign-on (SSO).

Prerequisites

At a minimum, the following information about the OIDC Identity Provider is required:

The Discovery URL (also called the Well-Known Configuration URL) published by the IdP for this application.
A client application created in the IdP, configured to allow Altair SLC Hub as a valid redirect URI.
The Client ID and Client Secret issued by the IdP for that client application.

Upstream TLS proxy

If Altair SLC Hub sits behind a TLS-terminating proxy or load balancer (e.g., AWS ALB) and you haven't enabled TLS termination in Keycloak itself (ingress.tls.enabled: false), you must add the following to your ingress_custom.yaml:

ingress:
  forwardedProto: https

Without this setting, Keycloak generates http:// URLs instead of https://, and the OIDC authentication flow will fail.

Configure OIDC¶

OIDC is an authentication layer built on OAuth 2.0 that enables SSO — for more details, see the OpenID Connect Core 1.0 specification.

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

To access the Keycloak Admin UI, navigate to:

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

Log in with your Keycloak admin credentials.

Step 1 — Add the OIDC Identity Provider¶

In the Keycloak Admin UI, select the slchub realm.
In the left menu, click Identity Providers.
Click Add provider and select OpenID Connect v1.0.

Fill in the General settings:

Field	Value
Alias	A unique identifier for this IdP (e.g., `okta-oidc`). Choose something stable — changing it later requires updating the redirect URI registered in your IdP.
Display name	What users see on the login page (e.g., `Company SSO`). Optional.
Display order	Controls the order of IdP buttons on the login page. Optional.

Copy the Redirect URI shown at the top of the form. You will need this later in Step 2.

The redirect URI has the following format:
```
<hub-url>/keycloak/realms/slchub/broker/<alias>/endpoint
```
Under OpenID Connect settings, the Use discovery endpoint toggle is enabled by default. Paste your IdP's Discovery URL into the Discovery endpoint field. Keycloak will automatically retrieve the authorization, token, and other endpoints from this URL.
Enter the Client ID and Client Secret issued by your IdP for this application.
Click Save.

Common Discovery URL formats¶

Provider	Discovery URL format
Google	`https://accounts.google.com/.well-known/openid-configuration`
Okta	`https://<your-org>.okta.com/.well-known/openid-configuration`
Azure AD / Microsoft Entra	`https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`
AWS IAM Identity Center	`https://<instance>.awsapps.com/start/.well-known/openid-configuration`
Other providers	Check your provider's documentation or SSO/Security settings.

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

Your IdP needs to know where to redirect users after authentication.

Log into your external IdP's admin console and open the client application you created for Altair SLC Hub.
Register the Redirect URI you copied in Step 1 as an allowed redirect URI.
Save the changes in your IdP.

Step 3 — Configure Attribute Mappers¶

Why attribute mappers are needed

Your IdP sends user information as claims inside the OIDC token, but it may use different claim names than Altair SLC Hub expects. Mappers translate these names so Altair SLC Hub can read the user's data correctly.

Without correct mappers: Users can authenticate successfully, but their attributes will be missing or incorrect, and they may lack the permissions or home directories needed to run workloads.

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

The following user attributes can be mapped to Altair SLC Hub. The attributes required to run workloads are marked accordingly.

Altair SLC Hub attribute	Default OIDC claim name	Required	Description
`firstName`	`given_name`	Yes	Given name
`lastName`	`family_name`	Yes	Family name
`displayName`	`name`	Yes	Full display name
`unixUserName`	`unixUserName`	Yes	Linux OS username on Altair SLC Hub server and workers
`unixHomeDirectory`	`unixHomeDirectory`	Yes	Linux home directory path
`userPrincipalName`	`userPrincipalName`	Windows only	Windows UPN (required for Windows workers only)
`email`	`email`	No	Email address. Add a mapper for this attribute if your IdP sends an email claim and you want it stored on the Altair SLC Hub user.

Finding your IdP's claim names

Different IdPs use different claim naming conventions. Check your IdP's token documentation or inspect an actual token to confirm the exact claim names being sent:

Google: Standard OIDC claims — email, given_name, family_name, name
Okta: Configurable; commonly email, given_name, family_name
Azure AD / Microsoft Entra: Uses its own claim names — check your app registration's token configuration

For each required attribute, add a mapper as follows:

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

Hub ExternalIdp Mapper¶

There is an additional mapper named Hub ExternalIdp Mapper. This mapper does not need to be created manually — it is created automatically when the identity provider is saved, and marks users as external by setting the IdP alias value.

Step 4 — Add a Group Mapper¶

OIDC users who authenticate successfully are created in Keycloak but have no Altair SLC Hub permissions by default. A hardcoded group mapper automatically assigns them to the correct group 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.
Click Save.

This grants authenticated OIDC users the base User role in Altair SLC Hub. 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.

Step 5 — Set the Sync Mode¶

The Sync mode controls how Keycloak updates user attributes on subsequent logins.

In the identity provider Settings tab, scroll to Advanced settings and set Sync mode:

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 (for example, so that name changes in the IdP are reflected in Altair SLC Hub on the user's next login).

Step 6 — Test the Integration¶

Log out of Altair SLC Hub.
On the login page, click the button for your IdP (e.g., Company SSO).
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 successfully.
Verify your user details by clicking the profile icon in the top-right corner.