In this guide, we will walk through the process of setting up the Enterprise Platform to use Okta directly for user authentication, without an intermediate service. We will log in through the Dashboard or Grafbase CLI using Okta 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 Okta is the authorization server.
As a prerequisite, you will need an Okta account with the necessary permissions to create applications, as well as a running deployment of the Enterprise Platform.
Log in to your Okta account, and go to the Admin interface.
Then on the left, find the "Applications" section, and navigate there.
On the applications screen, click "Create App Integration".
In the creation screen, select "OIDC — OpenId Connect", and "Web Application".
Then give your integration a name, for example "Grafbase Enterprise Platform". Select the "Refresh token" box in "Grant Type", and enter the root URL of your deployment of the Grafbase Dashboard, with /_auth/callback as the path in "Sign-in redirect URIs". The sign-out URI is not as important — you can set it to the root of your Dashboard deployment for example.
In "Assignments", check the box that matches your internal policies, otherwise "Allow everyone in the organization to access". Then save.
You are now on the application screen. You can see a client ID and a client secret. Take note of these values, we will need them later. Then navigate to the "Sign On" tab.
In the "Sign On" tab, we will configure the groups claim inside the "OpenID Connect Token" section. Click "Edit".
There, add the groups you want the Enterprise Platform to be aware of (to provision organization and team memberships), or "matches regex", and ".*" to include all groups.
The Dashboard will need to be configured to use Okta 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 Okta instance or authorization server, for example "https://trial-4034757.okta.com/". OIDC_CLIENT_IDandOIDC_CLIENT_SECRET: the client ID and secret you obtained in the previous section for the Okta application you created.OIDC_SCOPES:"openid profile email groups offline_access"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 Okta.
The API deployment only needs the GRAFBASE_OIDC_ISSUER environment variable to be set. It will discover the JWKS to validate the incoming JWTs with the standard OIDC discovery mechanisms.
If you requested the groups scope in OIDC_SCOPES in the Dashboard, the JWTs returned by Okta will contain the groups 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 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 Okta authentication and automatic organization membership provisioning, without any other third party service involved.