Authentication
Each Datalab has one confidential Keycloak client with the same name. For
example, the Datalab s-joe has a client named s-joe and its own service account.
Use that client for browser login, CLI device login, machine access, and
restricted user-token exchange. The same client credentials and Secret
references serve these flows.
Use Keycloak 26.2 or later with Standard Token Exchange V2 and client policies
enabled. Default scopes must not add the unrestricted client-role mapper.
Enable the grant-type, client-scopes, and reject-request client-policy
providers and the built-in Role Name and Realm Roles protocol mappers.
Groups and roles
Users in spec.users must exist in the configured realm. The first user and
users with userOverrides.<user>.role: admin belong to the administrator group.
All listed users belong to the Datalab users group.
| Managed group or account | Assigned Datalab client roles |
|---|---|
<datalab> |
ws_access, ws_api, all explicitly configured additional vcluster profiles |
<datalab>-admin |
ws_admin, ws_api, all additional profiles, each instance's built-in cluster-admin role |
| Datalab service account | ws_api only |
Administrators also inherit the users group's grants. The provider replaces managed group grants on each reconciliation. Profile removal or rename removes its grants. Direct user assignments are unchanged.
Only spec.vclusters.<instance>.groups defines selectable exchange profiles.
The reserved cluster-admin entry never adds an exchange scope, even when
explicitly declared. Empty groups give regular members no vcluster roles;
administrators retain each declared instance's built-in admin role and profile.
Role names remain vcluster_<instance>_<group>.
OAuth scopes and direct login
The Datalab client's dedicated role mapping permits only ws_api. It
appears in a token only if its subject holds that role. Default scopes are
basic, profile, and email; keep these scopes free of role grants and role
mappers. Keycloak includes a client's own roles even with Full Scope Allowed
off. The provider therefore uses Role Name mappers to select held roles for
each request, then a Realm Roles mapper to write that temporary role set under
resource_access.<datalab>.roles. This creates no realm roles or user grants.
For the reason and a worked example, see
Token exchange for downscoping.
| Optional OAuth scope | Permitted roles |
|---|---|
<datalab>:vclusters_<instance>_<group> |
Exactly vcluster_<instance>_<group> for an additional configured profile |
<datalab>:interactive |
ws_access, ws_admin, and each instance's built-in cluster-admin role |
Scopes permit only roles that the subject holds. They are never realm-default
scopes. Scope names differ from role names: bare ws_admin or
vcluster_vc0_namespace-demo are not generated OAuth scopes.
A direct authorization-code request to s-joe can use these parameters:
client_id=s-joe
response_type=code
redirect_uri=http://localhost:8080/callback
scope=openid profile email s-joe:interactive s-joe:vclusters_vc0_namespace-demo
Use the normal state and PKCE checks, then authenticate the confidential client
when redeeming the code. Request only the scopes needed by the application.
For a namespace-only direct login, omit s-joe:interactive.
You can also use a separate login client in the same realm. Its scope mappings control the roles in its tokens. Before exchanging one of those tokens through the Datalab client, check that it contains the Datalab audience and the requested roles. Configure those claims on the separate login client.
CLI device login
The provider enables Device Authorization Grant on the existing confidential
client. The built-in cluster-admin kubeconfig helper uses this flow with a
separate client secret. It requests openid offline_access <datalab>:interactive,
prints a verification URL and user code to stderr, and waits for the user to
approve the login in a browser. No localhost callback is needed.
The resulting access token represents the user who signs in. Only that user's
assigned roles can appear. Possession of the client secret does not grant
cluster-admin. The service account remains assigned only ws_api; the helper
does not use grant_type=client_credentials.
The helper reuses cached tokens and attempts refresh before starting a new login. A valid cached token needs no client secret. Login and refresh require the secret through a private file or a hidden terminal prompt. See human access for commands and cache settings. Additional profiles use a caller-supplied access token and do not start login.
Login lifetime
Keycloak sets these lifetimes; the helper uses the issued expiry values.
| Lifetime | Setting |
|---|---|
| Time to approve a device code | Realm oauth2DeviceCodeLifespan |
| Access token validity | Inherited realm Access Token Lifespan |
| CLI offline session validity | Offline Session Idle/Max and Client Offline Session Idle/Max |
For the CLI cache duration, offline session limits, and revocation, see human login lifetime.
Device and standard flows inherit the realm's access-token lifespan. The device helper requests offline access and can refresh tokens for up to 30 days, subject to realm limits. Exchanged access tokens inherit the same lifespan and have no refresh token in the current setup. See ADR-004 for options for longer delegated access.
User-token exchange
Each Datalab client enables exchange automatically after its scopes, mappers, and policy are ready. No extra setting is required.
Standard Token Exchange V2 uses the existing Datalab client credentials. The caller's
access token remains the subject; exchange does not use the service account's
permissions. A managed client policy combines the grant-type and
client-scopes conditions with reject-request. It rejects
<datalab>:interactive during token exchange, including requests that combine
it with allowed profile scopes. Direct interactive login can still use it.
Send this form to the configured realm's token endpoint. Authenticate with the
existing confidential s-joe client through the approved credential path.
The placeholder below represents the original caller access token.
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<caller access token>
subject_token_type=urn:ietf:params:oauth:token-type:access_token
requested_token_type=urn:ietf:params:oauth:token-type:access_token
scope=s-joe:vclusters_vc0_namespace-demo
audience=s-joe
The caller token must contain s-joe in aud, unless it was issued to
s-joe itself. Keycloak uses this check to confirm that the token was intended
for the Datalab client. The Datalab audience is always available in tokens
issued by that client. The audience parameter filters available audiences;
it does not add missing mappings.
For an eligible caller, the required authorization claims are:
iss: https://identity.acme.com/realms/acme
sub: <same user subject as the caller token>
aud: [s-joe]
resource_access:
s-joe:
roles: [ws_api, vcluster_vc0_namespace-demo]
This applies to both members and administrators selecting the profile. The
result must omit ws_access, ws_admin, built-in cluster-admin, unrequested
profiles, and roles for other Datalabs. Identity claims can remain.
To use tokens issued by the Datalab client with another service, add its client ID to
EnvironmentConfig.data.iam.extraAudiences. For example, for
EOEPCA Workspace API:
iam:
extraAudiences:
- workspace-api
An exchange request can then include both audience=s-joe and
audience=workspace-api to retain those two recipients. Removing the setting
removes its managed audience mapper. For tokens issued by a separate login
client, configure the Datalab audience on that client.
Keycloak checks the user's role grants before applying an optional profile scope. A user without the role can receive a successful response with that scope and role omitted. Consumers must reject a result missing a requested role. This is the documented server behavior; actual issuance must be checked against the deployed server. Render checks do not prove token contents. See Keycloak scope permissions.
Reconciliation removes a deleted or renamed profile's optional association,
role scope mapping, Client Scope, and managed group grants. Instance deletion
removes its profiles too. Already-issued JWTs can retain their claims until
expiry. Downloading a kubeconfig profile neither grants permissions nor
reduces a supplied token's permissions. For delegated access, exchange the
token first, then give the recipient the profile and returned access token.
The additional profile helper reads that token from a file and needs no client
secret. The virtual API still checks the realm issuer, Datalab audience,
signature, validity, and configured Datalab roles.
Its username is sub; groups are datalab:<datalab>:<role>. Existing virtual
RoleBinding and ClusterRoleBinding rules apply without an authentication change.
Credential Secrets and machine access
| Secret | Namespace | Use |
|---|---|---|
<datalab>-oauth-client |
Claim namespace | Source credentials for the existing Datalab client |
<datalab>-oauth2-client |
Runtime namespace | Created only for public Data/S3 OAuth2 proxies; contains client_id, client_secret, and cookie_secret |
The runtime copy is needed only when Data is enabled and exposed through an Ingress or HTTPRoute. It is created after the runtime namespace is known and removed when that proxy is disabled. Token exchange and virtual-cluster access do not need this copy. The aggregate session Secret includes OAuth fields delivered to sessions.
Anyone with the client secret can request a service-account token. Grant read
access only to authorized callers. With grant_type=client_credentials and no
optional scopes, the Datalab service account receives only
ws_api.
Virtual API profile Secrets contain public settings and no credentials. See virtual API access for credential files. Permission to download a profile is separate from permission to read service credentials.
Exchange caller checks
A service that exchanges tokens for users must:
- Accept full profile scope names, or translate short names with the Datalab name.
- Allow only currently configured additional profiles and check each requested role against the caller's validated token.
- Retain the original caller access token for
subject_tokenand authenticate exchange with the existing Datalab client credentials. - Validate the returned signature, validity, issuer, exact audiences, user subject, requested roles, and absence of unexpected authorization permissions.
- Reject missing requested roles even when the token endpoint returns success.
- Check that the caller is allowed to request token issuance through that service, in addition to the token and role checks above.
OAuth2 discovery
The provider publishes the existing client in status.oauth2, separately from
service connections:
status:
oauth2:
- name: s-joe
type: client
issuerUrl: https://identity.acme.com/realms/acme
secretRef:
name: s-joe-oauth-client
namespace: workspace
ready: true
name is the actual OAuth2 client ID, not Keycloak's internal UUID. Names are
unique and type is always client. Entries contain only metadata and Secret
references; credentials stay in the referenced Secret.
Readiness requires the observed client and credential Secret to be ready, with matching client credentials. Removed sources clear stale entries. Discovery does not grant permission to read a Secret or authorize a service request.
Session ingress
Configure sign-in before users start a session. The examples use Kyverno to configure NGINX or APISIX session Ingress objects.
Set the shared ingress settings
Set the ingress class, domain, and TLS Secret in the EnvironmentConfig. Use the same values in the session runtime installation, for example:
clusterIngressDomain: lab.acme.com
clusterIngressClass: apisix
tlsCertificateRef:
name: wildcard-tls
namespace: workspace
Use a wildcard certificate for *.lab.acme.com.
Generated session resources
For a Datalab named s-jane with a default session, set ingress.domain to
lab.acme.com. The session ingress hosts include:
s-jane-default.lab.acme.com
editor-s-jane-default.lab.acme.com
s-jane-default-editor.lab.acme.com
data-s-jane-default.lab.acme.com
s-jane-default-data.lab.acme.com
The generated ingresses carry labels that are suitable for platform policy:
training.educates.dev/application: workshop
training.educates.dev/component: session
training.educates.dev/environment.name: s-jane
For s-jane, the generated client includes redirect and web-origin entries
for the Datalab root and each declared session host:
https://s-jane.lab.acme.com/*
https://s-jane-default.lab.acme.com/*
https://editor-s-jane-default.lab.acme.com/*
https://s-jane-default-editor.lab.acme.com/*
https://data-s-jane-default.lab.acme.com/*
https://s-jane-default-data.lab.acme.com/*
http://localhost:*
A service that belongs to s-jane can use this client. Shared browser ingress
can use a central platform client and check the generated Datalab roles.
Apply ingress policy
Apply controller settings through platform policy so they cover every session
Ingress. The examples use Kyverno CEL policies. They need CRDs that serve
MutatingPolicy and GeneratingPolicy in policies.kyverno.io/v1.
Kyverno is required for these policies, not for Provider Datalab itself.
Adapt the domains, issuer, and controller settings in the linked manifests.
NGINX Ingress with OAuth2 Proxy
Run OAuth2 Proxy as a shared service with its own OAuth client. Use a redirect
URI such as https://auth.lab.acme.com/oauth2/callback. Its authorization
policy must check access to the Datalab named in the requested host.
Apply the NGINX policy
to add external-auth annotations to matching session Ingress objects.
Set the proxy cookie domain to cover the session hosts, for example
.lab.acme.com, and allow redirects only to that domain.
APISIX Ingress configured by Kyverno
The APISIX manifest
gives Kyverno permission to create ApisixPluginConfig resources, generates
one in each session namespace, and attaches it to matching Ingress objects.
APISIX checks incoming requests; Kyverno configures the resources.
The example uses openid-connect with a central public client named
datalab-sessions. Its opa entry points to an external OPA service.
The manifest does not deploy that service or supply its policy. Configure
both for your platform so that the authorizer checks access to the requested
Datalab. OPA is needed only for this example.
The policies do not read Secrets. For a confidential central client, use the ingress controller's supported Secret mechanism to supply its credential.
The plugin forwards the access token in Authorization and disables ID token,
userinfo, and refresh token forwarding. Check that your authorizer and
upstream service accept these settings.
Kyverno generates the plugin's session secret once. Synchronization is disabled to keep it stable. After changing the template, recreate an existing generated plugin config or restart its session to apply the change.
For another ingress controller, match session Ingress objects by label and domain, then attach its authentication and authorization settings.