[Platformatic DB] Revise the Authorization documentation

The Authorization documentation for Platformatic DB is currently split between the Platformatic DB Configuration reference page and it’s own reference section. It’s slightly confusing to navigate and is missing examples that explicitly show how roles work in the context of rules.

Tasks

• Review the authorization schema
• Map out topics to cover
• Rename ‘Authorization & Authentication’ section to ‘Authorization’
• Move sections from ‘Configuration: Authorization’ section to ‘Authorization’ section
• Rewrite ‘Configuration: Authorization’ section to be a reference in the same way the other sections on the page are

New structure and topics to cover

• Reference (category)
  • Platformatic DB (category)
    • Configuration (page)
      • Authorization (section)
        • adminSecret
        • roleKey
        • anonymousRole
        • jwt
        • webhook
        • rules
    • Authorization (section + introduction)
      • Introduction (page)
        • Introduction
          • What authorization is in the context of Platformatic DB
          • Authentication is handled by a third-party service (+ examples)
          • Authorization strategies
          • User Roles & Metadata
          • Rules
        • Bypassing authorization in development
      • Authorization Strategies (page)
        • JSON Web Token (JWT)
        • Webhook
        • HTTP headers (development only)
      • User Roles & Metadata (page)
        • Introduction
          • Explain what roles are
          • Explain what User Metadata is
        • Roles
          • Reserved roles
          • Anonymous role
          • Role impersonation (currently: User impersonation)
          • Role configuration
        • User metadata
      • Rules
        • Introduction
          • What rules are and what they do
        • Operation checks (currently: Operation options)
          • GraphQL events and subscriptions (currently: Events and Subscriptions)
        • Restricting access to entity fields (currently: Fields)
        • Setting entity fields from user metadata (currently: Defaults)
        • Programmatic rules
        • Skipping authorization rules (currently: Programmatically skip authorization rules)
      • TODO: Authorization and the ctx object ???

[mcollina]

I don’t think we have any documentation that explains what the ctx object is. What is the ctx object and how is it used in the context of authorization?

This is a fun question to answer. ctx started as the context of graphql-js: https://graphql.org/graphql-js/type/#graphqlobjecttype, which is created in Mercurius at https://github.com/mercurius-js/mercurius/blob/de50db9409dcd9ff67b50163b87cf109fa0876ca/index.js#L235.

Basically it holds two things:

• Fastify reply
• Fastify instance

As well as every other thing we need to pass through the application.

After developing sql-mapper, I quickly noticed I needed a place to pass user metadata to access request and reply and user metadata. So I settled for using the same format for both OpenAPI and GraphQL.

[mcollina]

What are the /_admin routes for?

They are the routes used by the dashboard.

Should we be recommending that an adminSecret is set in production environments to restrict access to the dashboard?

Using an adminSecret is a very crude mechanism of authentication. It’s better if a JWT or a webhook is used.

What is “admin access to REST and GraphQL endpoints with X-PLATFORMATIC-ADMIN-SECRET header”?

Accessing the dashboard with a X-PLATFORMATIC-ADMIN-SECRET set.