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:
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 is built on top of fastify-jwt.
To configure it, the quickest way is to pass a shared
For more complex configurations, please check fastify-jwt options.
Platformatic DB supports JWKS. To configure it:
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:
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.
Platformatic can use a webhook to authenticate the requests.
In this case, the URL is configured on authorization:
"url": "<webhook url>"
When a request is received, Platformatic sends a
POST to the webhook, replicating the same body and headers, except for:
In the Webhook case, the HTTP response contains the roles/user information as 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
Note that setting user roles on HTTP headers is highly insecure and should be used only within protected networks.
If a user is recognized with a
platformatic-admin role, can also impersonate users.
The users/roles to impersonate are specified by:
userIdof 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
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
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