In this guide, we will walk through the process of setting up the Enterprise Platform to use GitLab directly for user authentication, without an intermediate service. We will log in through the Dashboard or Grafbase CLI using GitLab as the identity provider (IdP).
In technical terms, we are going to set up the OpenID Connect (OIDC) Authorization Code Grant flow to authenticate users and issue id tokens. The Dashboard is the client, the API is the resource server, and GitLab is the authorization server.
As a prerequisite, you will need a GitLab self hosted or hosted account, as well as a running deployment of the Enterprise Platform.
On GitLab, navigate to "Applications" in user settings.
Click "create application".
Give your application a name. In the "Redirect URI" field, enter the URL of your Dashboard deployment with /_auth/callback as path.
Untick the "confidential" checkbox if your Dashboard deployment is not secured with TLS (https://...).
Select the "openid", "profile" and "email" scopes.
Click "save application". On the next screen, you will see the client ID and secret. Copy these values, we will need them in the next section. Then click "continue".
The Dashboard will need to be configured to use GitLab as the identity provider (IdP). This can be done by setting the following environment variables:
OIDC_PROVIDER_TYPE:generic. Enables generic OIDC authentication mode.- Set
OIDC_ISSUERto the URL of your GitLab instance, or "https://gitlab.com" if you are using the public instance. OIDC_CLIENT_IDandOIDC_CLIENT_SECRET: the client ID and secret you obtained in the previous section for the GitLab application you created.OIDC_SCOPES:"profile email"requests the scopes the Grafbase Enterprise platform needs to function properly.
Before navigating to the Dashboard, we have to set up the Grafbase API deployment to accept the JWTs we will obtain from GitLab.
The API deployment only needs the GRAFBASE_OIDC_ISSUER environment variable to be set. Use the same value we used in the previous section for OIDC_ISSUER. It will discover the JWKS to validate the incoming JWTs with the standard OIDC discovery mechanisms.
Now (re)start the Dashboard and API with the new environment variables. Navigate to the Dashboard, and you should be redirected to the GitLab login screen. Once you log in there, you should be redirected back to the Dashboard and fully logged in.
If you requested the openid scope in OIDC_SCOPES in the Dashboard, the JWTs returned by GitLab will contain the groups_direct claim with the groups the logged in user is a part of.
If you set the "OIDC issuer" and "OIDC group name" settings in organization settings in the Dashboard to values that appear in that claim, the API will automatically add new users to your organization the first time it encounters them, if one of the groups in the groups_direct claim in their JWT matches the "OIDC group name" setting. For security reasons, the "OIDC issuer" setting must also match the iss (issuer) claim in the JWT.
You now have a fully functional Grafbase Enterprise Platform deployment with GitLab authentication and automatic organization membership provisioning, without any other third party service involved.