Federated Authorization

By default, the federated graph is publicly available. It is up to subgraphs to check whether a user has the proper credentials. Alternatively, a federated graph can also validate whether users have proper credentials before the request execution through a authorization provider. Multiple authorization providers can be configured, only one needs to authorize the user.

Currently, we only support JWT provider which validates JWT tokens.

JWT authorization can be configured with as little as the following:

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

export default config({
  graph: graph.Federated(),
  auth: {
    providers: [
      auth.JWT({
        jwks: {
          url: 'https:://example.com/.well-known/jwks.json',
        },
      }),
    ],
  },
})

We follow the JWT (RFC 7519) specification for JWT validation and validate its signature with the JWKs (RFC 7517) provided at jwks.url. The validation consists of the following steps:

  1. The signature of the JWT must be valid with one of the specified JWK.
  2. if the exp claim is present, it must be in the future with a leeway of 60s.
  3. if the nbf claim is present, it must be in the past with a leeway of 60s.
  4. if the iss claim is present and issuer is specified, they must match.
  5. if the aud claim is present and the audience is specified, they must match. If aud is an array audience must be part of it.

While not required, it is strongly recommended to at least specify the audience (aud claim). Otherwise JWTs which weren't meant for your project would still be accepted.

Here is the full configuration with optional fields:

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

export default config({
  graph: graph.Federated(),
  auth: {
    providers: [
      auth.JWT({
        // Only used for logging/error messages/etc.
        name: 'my-jwt',
        jwks: {
          url: 'https:://example.com/.well-known/jwks.json',
          issuer: 'https://example.com',
          audience: 'my-project',
          // Default value
          pollInterval: '60s',
        },
        header: {
          // Default values
          name: 'Authorization',
          valuePrefix: 'Bearer ',
        },
      }),
    ],
  },
})

The pollInternal defines how often the JWKs will be refreshed. It is best left to its default value.

Was this page helpful?