Generic OIDC and GitLab

Any OpenID Connect provider with discovery can log people in to the Studio from a browser. The CLI and the remote MCP need more of it. This page says what works with another provider than Keycloak, GitLab included, and what does not.

What you get

Browser logins to the Studio through your provider (GitLab, Authentik or another), with the same roles and invitations as with Keycloak. With a provider that issues JWT access tokens for the Studio's audience, the CLI and the remote MCP too.

Context and versions

• A hosted Studio on Clever Cloud, from 4.2.3 (D44: GitLab for the studio-oidc-generic pass).
• Verified on: not verified on a live installation. The studio-oidc-generic pass (login, roles, a revoked member refused, on a real GitLab) is not-run for 4.4.0. What this page says comes from the code and the guide.

Prerequisites

• Domains and TLS done: you know publicUrl.
• An account on the provider allowed to create an OAuth / OpenID Connect application.

Where to run the commands

The application is created in the provider's console. clever env set: on your machine, in the engine repository where the studio app is linked.

Steps

1. At the provider, create the studio application as for Keycloak: a confidential client, the scopes openid profile email, Authorization Code with PKCE S256, the redirect URI <publicUrl>/auth/callback, the post-logout redirect <publicUrl>, and the back-channel logout to <publicUrl>/auth/backchannel if the provider offers it.

2. Save its secret in a 0600 file and set it on the studio app:

   # on your machine, in the engine repository
   clever env set --alias my-game-studio -- STUDIO_OIDC_CLIENT_SECRET "$(cat ~/secrets/my-game/oidc-client-secret)"

   copy

3. Write the provider in the configuration's oidc. For GitLab the issuer is https://gitlab.com; clientId is the application's id; audience is any name other than clientId (the server refuses the same):

   { "issuer": "https://gitlab.com", "clientId": "<application id>", "audience": "studio-api" }

   copy

   Leave out cliClientId when the provider cannot serve the CLI (below): GET /auth/cli then answers client_id: null.

Expected result, and how to check it

The Studio starts (it reads the issuer's discovery at start); an invited member logs in from a browser with the verified email of the invitation; GET /auth/me gives their role. An invitation is consumed only by the verified email it names: a provider that does not say the email is verified cannot accept invitations.

Common errors

Symptom	Cause	Fix
The member logs in but is "not a member of this project"	The provider does not report email_verified, or another email	Check the email is verified at the provider; invite that email
the access token is not valid from the CLI	Opaque access tokens, or no audience	Not supported with this provider (limit above)
oidc.maxTokenSeconds is between 30 and 900	A value out of range	Set 300 to 900, or leave it out (300)
oidc.issuer must be an http(s) URL	The issuer missing its scheme	The full URL

Files or data changed

The application at the provider; STUDIO_OIDC_CLIENT_SECRET and STUDIO_CONFIG_JSON on the studio app.

Recovery or going back

Switching between providers changes everyone's identity: Changing domain or OIDC provider.

Reference: the oidc fields

Field	Required	Value	Default
issuer	yes	the provider's issuer, an http(s) URL (its discovery is read at start)	—
clientId	yes	the browser client (studio)	—
audience	yes	the audience the access tokens must carry; must differ from clientId	—
cliClientId	no	the public client of the device flow, given to the CLI by GET /auth/cli	none
scopes	no	the scopes of a browser login	openid email profile
maxTokenSeconds	no	the longest access token accepted, 30 to 900	300
allowInsecure	no	a provider over plain http, for a local test only; never in production	false

With oidc set, the server also requires worker, trustProxy (when it listens beyond the loopback), STUDIO_OIDC_CLIENT_SECRET and STUDIO_SESSION_KEY (Configuration). An unknown key at the top of the configuration is refused at start; inside oidc, an unknown field is ignored. Since 4.2.1.

References

• studio-server/src/server/auth/oidc.ts, studio-server/src/server/config.ts.
• ADR 0027; the Keycloak setup: Keycloak; revocation: Security.