OpenID Connect Configuration
Last updated
Was this helpful?
Last updated
Was this helpful?
explain how to set up a new instance to enable authentication on your datalab.
However, chances are that your organization already has an existing IAM system in place. This guide covers how to integrate Onyxia with various commonly used OIDC providers, including , , and .
Onyxia use Public OpenID Connect client: no client Secret.
The technical term for a public OIDC client is Authorization Code Flow + PKCE.
It's the type of client that you create for Single Page Application (SPA).
Onyxia Login Theme
Each version of Onyxia ships with . You can download it from the . Specific instructions for loading the theme in your Onyxia instance can be found .
If you are deploying Keycloak using Helm, as instructed in the installation guide, in the Onyxia-ops repository.
Choosing the Unique User Identifier Claim
Onyxia requires a unique user identifier. You must specify which claim in the Access Token should be used for this purpose.
Ideally, you can use preferred_username
as an identifier, but this requires ensuring it complies with . This means it must contain only lowercase alphanumeric characters and -
.
Since this format is restrictive, if you already have an existing user base, preferred_username
may not be an option. In that case, you have two alternatives:
Define a custom claim: Configure a Keycloak mapper to generate an RFC 1123-compliant claim in the Access Token.
Use "sub"
: This claim is guaranteed to be unique and always present, but ensure that the sub
values comply with RFC 1123.
If you are starting fresh with no existing users, you can enforce a regex pattern in the User Profile Attributes to require usernames that comply with the restriction.
More details can be found in (search for "pattern").
Configuring Keycloak
Beyond what's covered in the installation guide, if you need a more general tutorial on setting up a public Keycloak OIDC client like Onyxia, refer to the following guide. It includes a test project to validate your configuration.
Here is an overview of what your Onyxia values.yaml
should look like:
Onyxia uses an OIDC client for authentication, but it also connects to other OIDC-enabled services. Each of these services can have its own OIDC configuration, allowing Onyxia to authenticate using a separate client identity.
In the region configuration, you can specify an optional oidcConfiguration
object for
each service:
S3 (MinIO STS) → onyxia.api.regions[].data.S3.sts.oidcConfiguration
Vault → onyxia.api.regions[].vault.oidcConfiguration
Kubernetes API → onyxia.api.regions[].services.k8sPublicEndpoint.oidcConfiguration
Each configuration follows this structure:
If no oidcConfiguration
is provided for a service, Onyxia will reuse its own OIDC client
and the same Access Token for authentication. However, it is recommended to provide
a separate client ID for each service to improve access control and security.
values.yaml
⚠ Important: Consistency of Claims Across Services
When configuring OIDC for Onyxia, you define specific claims that indicate where to find the user identifier, groups, and roles within the Access Token's JWT.
These claims cannot be configured separately for each service Onyxia interacts with (e.g., S3, Vault, Kubernetes API). They must remain consistent across all OIDC-enabled services to ensure proper authentication and authorization.
When a user logs in, the OIDC provider issues an Access Token for the onyxia
client.
This token includes claims such as:
If oidc.username-claim: "preferred_username"
is configured in Onyxia’s main configuration,
then all services it connects to—such as onyxia-minio
, onyxia-vault
, and onyxia-k8s
—
must also receive Access Tokens where the preferred_username
claim exists and holds the same value.
To prevent issues, all OIDC clients (onyxia
, onyxia-minio
, onyxia-vault
, onyxia-k8s
)
should be configured within the same SSO realm in your OIDC provider.
This ensures that every issued Access Token follows the same claim structure and contains
consistent values for the same user.
If you're unsure whether your setup meets this requirement, check the JWT of each Access Token issued for different clients and confirm that the claims are aligned.
If you're using another OIDC provider and need help configuring Onyxia, reach out . We’ll be happy to schedule a call and assist with the integration.
auth.lab.my-domain.net
<KC_RELATIVE_PATH>: /auth
<REALM_NAME>: datalab
<APP_DOMAIN>: datalab.my-domain.net
<BASE_URL>: /
<DEV_PORT>: 5173
✅ Note that Onyxia implement an auto logout countdown that will start to display once minute befor auto logout if you configure your client as "My App"
→ "Onyxia"
"My App - API"
→ "Onyxia - API"
"api://my-app-api"
→ "api://onyxia-api"
"https://my-app.com/"
→ "https://datalab.my-domain.net/"
"My App"
→ "Onyxia"
<APP_DOMAIN> → datalab.my-domain.net
<BASE_URL> → /
<DEV_PORT> → 5173
"My App - API"
→ "Onyxia - API"
https://myapp.my-company.com/api
→ https://datalab.my-domain.net/api
"auth.my-company.com"
→ "auth.my-domain.net"
https://my-app.com/
by https://datalab.my-domain.net/
.