Auth Providers

Configure provider types OIDC, JWT, JWKS or a custom authorizer function that work with Grafbase to authenticate and authorize user requests.

You can use any OpenID Connect provider that adheres to the OpenID Connect Discovery spec with your backend.

We append /.well-known/openid-configuration to the URL to locate the OpenID configuration.

import { auth, config, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const provider = auth.OpenIDConnect({
  issuer: g.env('ISSUER_URL'),
})

export default config({
  graph: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.private()
    },
  },
})

We recommend that you use an environment variable for the issuer value.

Grafbase supports a symmetric JWT provider that you can use to authorize requests using a JWT signed by yourself or a third-party service.

To use the JWT provider you will need to configure the issuer (any valid URL), and a secret value.

import { auth, config, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const provider = auth.JWT({
  issuer: g.env('ISSUER_URL'),
  secret: g.env('JWT_SECRET'),
})

export default config({
  graph: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.private()
    },
  },
})

We recommend that you use an environment variable for the issuer and secret values.

Grafbase supports JSON Web Key Sets that contain public keys to verify any JWT issued by the provider, signed using RS256.

We append /.well-known/jwks.json to the issuer URL to locate the JWKS configuration.

import { auth, config, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const provider = auth.JWKS({
  issuer: g.env('ISSUER_URL'),
})

export default config({
  graph: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.private()
    },
  },
})

If the auth provider does not add the iss claim, you must add the full JWKS endpoint including /.well-known/jwks.json:

import { auth, config, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const provider = auth.JWKS({
  issuer: g.env('ISSUER_URL'),
  jwksEndpoint: g.env('JWKS_ENDPOINT'),
})

export default config({
  graph: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.private()
    },
  },
})

If both issuer and jwksEndpoint is provided, issuer is used for claim verification and jwksEndpoint is used to fetch the keys.

import { auth, config, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const provider = auth.JWKS({
  issuer: g.env('ISSUER_URL'),
  jwksEndpoint: g.env('JWKS_ENDPOINT'),
})

export default config({
  graph: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.private()
    },
  },
})

We recommend that you use an environment variable for the issuer and jwksEndpoint values.

Grafbase allows developers to create a custom authorizer function that will be used to determine the validity of tokens passed with requests.

The custom authorizer works with owner and group-based rules, providing the sub and groups are returned inside of the identity object:

import { auth, config, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const authorizer = auth.Authorizer({
  name: 'my-authorizer-function',
})

export default config({
  graph: g,
  auth: {
    providers: [authorizer],
  },
})

The file my-authorizer-function.(ts|js) must exist inside the folder grafbase/auth:

export default function ({ request }) {
  const { headers } = request

  const jwt = headers['authorization']

  // Verify JWT...

  return { identity: { sub: 'user1', groups: ['g1'] } }
}

There are auth providers that sign tokens with the same iss value.

You should add a clientId value to the provider config. Grafbase will check the aud claim inside the JWT is an array of strings, and the value matches clientId.

import { auth, config, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const provider = auth.OIDC({
  issuer: g.env('ISSUER_URL'),
  clientId: g.env('CLIENT_ID'),
})

export default config({
  graph: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.private()
    },
  },
})

Without a check like this, all APIs using the same issuer would share the same keys, thereby allowing customers to access each other's APIs.

• JWT — HS (HMAC+SHA): HS256, HS384, HS512
• OIDC — RS256,RS384,RS512
• JWKS — RS256,RS384,RS512