Skip to main content
Version: Next

User Roles & Metadata

Introduction​

Roles and user information are passed to Platformatic DB from an external authentication service as a string (JWT claims or HTTP headers). We refer to this data as user metadata.

Roles​

Understanding User Roles​

User roles in Platformatic DB are represented as strings and are passed via the X-PLATFORMATIC-ROLE HTTP header. These roles are specified as a list of comma-separated names. The key used to pass roles is configurable, allowing integration with various authentication systems.

For detailed configuration options, refer to our configuration documentation

Reserved roles​

Platformatic DB reserves certain role names for internal use:

  • platformatic-admin: Identifies a user with admin powers.
  • anonymous: Automatically assigned when no other roles are specified.

Anonymous Role​

By default, if a user does not have an assigned role, the anonymous role is applied. You can define specific rules for users with this role as shown below:

{
  "role": "anonymous",
  "entity": "page",
  "find": false,
  "delete": false,
  "save": false
}

This configuration ensures that users with the anonymous role cannot perform find, delete, or save operations on the page entity.

Role Impersonation​

Role impersonation allows an admin to perform actions on behalf of another user by specifying roles to impersonate in the X-PLATFORMATIC-ROLE HTTP header. This feature requires a valid X-PLATFORMATIC-ADMIN-SECRET header.

Role impersonation​

If a request includes a valid X-PLATFORMATIC-ADMIN-SECRET HTTP header it is possible to impersonate a user roles. The roles to impersonate can be specified by sending a X-PLATFORMATIC-ROLE HTTP header containing a comma separated list of roles.

X-PLATFORMATIC-ADMIN-SECRET: <shared-admin-secret>
X-PLATFORMATIC-ROLE: editor,admin
important

Role impersonation is disabled when JWT or Webhook authentication methods are set. In such cases, the role is automatically set to platformatic-admin if the X-PLATFORMATIC-ADMIN-SECRET HTTP header is specified.

Role configuration​

The roles key in user metadata defaults to X-PLATFORMATIC-ROLE. It's possible to change it using the roleKey field in configuration. Same for the anonymous role, which value can be changed using anonymousRole.

 "authorization": {
    "roleKey": "X-MYCUSTOM-ROLE_KEY",
    "anonymousRole": "anonym",
    "rules": [
    ...
    ]
  }

Another option is to use the rolePath field to specify a path to the role in the user metadata. This is useful when the role is nested in the user data extracted from the JWT claims, e.g. if we have a JWT token with:

{
  "user": {
    "roles": ["admin", "editor"]
  }
}

We can specify the rolePath as user.roles:

 "authorization": {
    "rolePath": "user.roles",
    ...
  }

Note that the rolePath has the precedence on roleKey. If both are set, the rolePath will be used and the roleKey will be ignored.

User metadata​

User roles and other user data, such as userId, are referred to by Platformatic DB as user metadata.

User metadata is parsed from an HTTP request and stored in a user object on the Fastify request object. This object is populated on-demand, but it's possible to populate it explicitly with await request.setupDBAuthorizationUser().

await request.setupDBAuthorizationUser();
const userRoles = request.user.roles;

Accessing user metadata in custom GraphQL resolvers​

In a custom mercurius resolver, the Fastify request is available under context.reply.request, so the same pattern applies:

app.graphql.extendSchema(`
  extend type Query {
    whoami: String
  }
`);
app.graphql.defineResolvers({
  Query: {
    whoami: async (source, args, context) => {
      const request = context.reply.request;
      await request.setupDBAuthorizationUser();
      return request.user?.["X-PLATFORMATIC-USER-ID"];
    }
  }
});

Issues

If you run into a bug or have a suggestion for improvement, please raise an issue on GitHub.