Introduction to Authentication & Authorization

Authorization in Platformatic DB is role-based (see Roles And User Information for further details). A user is supposed to have a list of roles associated. Platformatic delegates authentication and assignment of the roles to an external authentication service. The job of the authentication service is to authenticate users and assign their roles correctly. Supported authentication service integrations are:

• JWT
• Webhook

We refer to the user roles and other informations (like userId) as User Metadata.

To make testing and developing easier, it's possible to bypass these checks if a adminSecret is set. See HTTP Headers.

JWT

JWT is built on top of fastify-jwt.

To configure it, the quickest way is to pass a shared secret, e.g.:

  "authorization": {
    ...

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

    ...
  }

For more complex configurations, please check fastify-jwt options.

JWKS

Platformatic DB supports JWKS. To configure it:

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

More get-jwks options can be specified.

When a JWT token is received, Platformatic DB gets 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 configurations are strictly necessary.

It's also possible to enable JWKS with no options:

  ...

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

In this case, the JWKS 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. For that reason, this configuration should be used only for development, while in every other case the allowedDomains should be specified.

Webhook

Platformatic can use a webhook to authenticate the requests.

In this case, the URL is configured on authorization:

  "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

To make testing and developing easier, it's possible to bypass JWT / WebHook integration if a adminSecret is set. If so, and if a request has X-PLATFORMATIC-ADMIN-SECRET HTTP header set with the configured adminSecret, the JWT/Webhook authentication is skipped, and the role set automatically as platformatic-admin.

Note that setting user roles on HTTP headers is highly insecure and should be used only within protected networks.

Impersonation

If a user is recognized with a platformatic-admin role, can also impersonate users. The users/roles to impersonate are specified by:

• X-PLATFORMATIC-USER-ID: the userId of the authenticated user. Note that this key value is conventional, any key can be used as long that is the same key specified in authorization rules.
• X-PLATFORMATIC-ROLE: comma separated list of roles

User Metadata

In all cases, the roles/user information is passed to Platformatic from the external authentication service as a string (JWT claims or HTTP headers). We can refer to these as user metadata. Platformatic saves the user metadata for each request in a user object. Roles can be set using X-PLATFORMATIC-ROLE as list of comma-separated roles (this key is configurable, see References).

Note that roles are just strings. Some "special roles" are reserved:

• platformatic-admin : this identifies a user who has admin powers
• anonymous: set automatically when no roles are associated