[Platformatic DB] Revise the Authorization documentation

[simonplend]

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 ???

[simonplend]

@marcopiraccini I have some questions about authorization with Platformatic DB. Here are the first ones, which are related to adminSecret:

Configuration reference: Authorization)

adminSecret (string, optional) — If defined, it will be the password used to access the dashboard and the string to send within the x-platformatic-admin-secret header when performing GraphQL/REST API calls.

• What are the /_admin routes for?
• Should we be recommending that an adminSecret is set in production environments to restrict access to the dashboard?
• What is “admin access to REST and GraphQL endpoints with X-PLATFORMATIC-ADMIN-SECRET header”?

[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.

[simonplend]

Thanks @mcollina. I have some more questions for you/the team:

• Can you share an example of using a webhook for authorization? I’ve not come across this approach before.
• How can you configure Platformatic DB to use JWT and Webhook authorization? This section is unclear.
• 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?
• The Programmatic Rules page doesn’t explain what auth in the code example is and how to add programmatic rules in the context of Platformatic DB.
  • Is auth the @pltaformatic/db-authorization module?
  • Would auth be registered as a plugin inside the root plugin to set rules programmatically?
• “Platformatic saves the user metadata for each request in a user object” (source) — is there a way to access that user object in a plugin?

[ivan-tymoshenko]

• Can you share an example of using a webhook for authorization? I’ve not come across this approach before.
• How can you configure Platformatic DB to use JWT and Webhook authorization? This section is unclear.

"authorization": {
    "jwt": {
      "namespace": "https://platformatic.auth/",
      "jwks": {
        "allowedDomains": [ "{PLT_AUTH0_JWKS_DOMAIN}" ]
      }
    },
    "webhook": {
      "url": "https://auth.server.dev/verify"
    },
    "rules": [
      {
        "role": "user",
        "entity": "movie",
        "find": true
      },
      {
        "role": "user",
        "entity": "book",
        "find": true
      },
      {
        "role": "api-key",
        "entity": "movie",
        "find": true,
        "save": true
      }
    ]
  }

• user role comes from jwt
• api-key role comes from webhook api-key auth

[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.