Auth Rules

Auth rules are global and apply to all queries and mutations.

Grafbase supports the following strategies to control access to data:

Public — Allow public access to data
Signed-in user — Allow access to any signed-in user
Group-based — Allow access to users of a group

The rules below work with all the available auth providers.

Public rule

You can configure public access to everything:

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

export default config({
  schema: g,
  auth: {
    rules: rules => {
      rules.public()
    },
  },
})

Signed-in rules

You can configure signed-in access to data using a valid provider:

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

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

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

Group-based rules

You can configure group-based access to data based on the groups claim of a valid JWT:

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

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

export default config({
  schema: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.groups(['backend', 'admin'])
    },
  },
})

The user only has access if the JWT claims contain one of the allowed groups. The following decoded JWT contains a valid groups value admin:

{
  "exp": 1659646197,
  "groups": ["admin"],
  "iat": 1659559797,
  "iss": "https://clerk.b74v0.5y6hj.lcl.dev",
  "nbf": 1659559792,
  "sub": "user_12345"
}

Custom claims

You can optionally set groupsClaim for group-based auth to use a custom claim path.

Consider the following JWT provided by your issuer:

{
  "header": {
    "typ": "JWT",
    "alg": "RS256"
  },
  "payload": {
    "https://grafbase.com/jwt/claims": {
      "x-grafbase-allowed-roles": ["editor", "user", "mod"]
    }
    // ...
  }
}

Here the groups claim x-grafbase-allowed-roles is nested inside of https://grafbase.com/jwt/claims. This is declared using .. You can provide a groupsClaim path along with the provider:

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

const provider = auth.OpenIDConnect({
  issuer: g.env('ISSUER_URL'),
  groupsClaim: 'https://grafbase\\.com/jwt/claims.x-grafbase-allowed-roles',
})

export default config({
  schema: g,
  auth: {
    providers: [provider],
    rules: rules => {
      rules.groups(['backend', 'admin'])
    },
  },
})

Any . used inside of URLs will need to be escaped for the groupsClaim value.

Global rules

You can configure rules globally for everything in your project:

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

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

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