Strategies

Introduction

Platformatic DB supports the following authorization strategies:

• JSON Web Token (JWT) with support for JSON Web Key Sets (JWKS)
• Webhook
• HTTP headers (development only)

JSON Web Token (JWT)

The JSON Web Token (JWT) authorization strategy is built on top of the @fastify/jwt Fastify plugin.

To configure it, the quickest way is to pass a shared secret in your Platformatic DB configuration file, for example:

platformatic.db.json

{
  "authorization": {
    "jwt": {
      "secret": "<shared-secret>"
    }
  }
}

By default @fastify/jwt looks for a JWT in an HTTP request's Authorization header. This requires HTTP requests to the Platformatic DB API to include an Authorization header like this:

Authorization: Bearer <token>

See the @fastify/jwt documentation for all of the available configuration options.

JSON Web Key Sets (JWKS)

The JWT authorization strategy includes support for JSON Web Key Sets.

To configure it:

platformatic.db.json

{
  "authorization": {
    "jwt": {
      "jwks": {
        "allowedDomains": [
          "https://ISSUER_DOMAIN"
        ]
      }
    }
  }
}

When a JSON Web Token is included in a request to Platformatic DB, it retrieves the correct public key from https:/ISSUER_DOMAIN/.well-known/jwks.json and uses it to verify the JWT signature. The token carries all the informations, like the kid, which is the key id used to sign the token itself, so no other configuration is required.

JWKS can be enabled without any options:

platformatic.db.json

{
  "authorization": {
    "jwt": {
      "jwks": true
    }
  }
}

When configured like this, the JWK URL is calculated from the iss (issuer) field of JWT, so every JWT token from an issuer that exposes a valid JWKS token will pass the validation. This configuration should only be used in development, while in every other case the allowedDomains option should be specified.

Any option supported by the get-jwks library can be specified in the authorization.jwt.jwks object.

JWT Custom Claim Namespace

JWT claims can be namespaced to avoid name collisions. If so, we will receive tokens with custom claims such as: https://platformatic.dev/X-PLATFORMATIC-ROLE (where https://platformatic.cloud/ is the namespace). If we want to map these claims to user metadata removing our namespace, we can specify the namespace in the JWT options:

platformatic.db.json

{
  "authorization": {
    "jwt": {
      "namespace": "https://platformatic.dev/"
    }
  }
}

With this configuration, the https://platformatic.dev/X-PLATFORMATIC-ROLE claim is mapped to X-PLATFORMATIC-ROLE user metadata.

Webhook

Platformatic DB can use a webhook to authenticate requests.

In this case, the URL is configured on authorization:

platformatic.db.json

{
  "authorization": {
    "webhook": {
      "url": "<webhook url>"
    }
  }
}

When a request is received, Platformatic sends a POST to the webhook, replicating the same body and headers, except for:

• host
• connection

In the Webhook case, the HTTP response contains the roles/user information as HTTP headers.

HTTP headers (development only)

danger

Passing an admin API key via HTTP headers is highly insecure and should only be used during development or within protected networks.

If a request has X-PLATFORMATIC-ADMIN-SECRET HTTP header set with a valid adminSecret (see configuration reference) the role is set automatically as platformatic-admin, unless a different role is set for user impersonation (which is disabled if JWT or Webhook are set, see below).

Also, the following rule is automatically added to every entity, allowing the user that presented the adminSecret to perform any operation on any entity:

{
  "role": "platformatic-admin",
  "find": false,
  "delete": false,
  "save": false
}