docs: explain allowed-roles/default-role in docs more clearly

1. Explain allowed-roles/default-role in docs more clearly, with the rationale for this design.

2. And why/how it is tricky/hard to do permission merging for multi-roles.

TL;DR for 1 - If you put the x-hasura-role in the JWT then everytime the user has to change role you would have to issue a new JWT. Hence there is a list of allowed-roles (x-hasura-allowed-roles) and a default role (x-hasura-default-role). If no x-hasura-role header is sent then the default role is picked. If a x-hasura-role header is sent then it is validated with the allowed-roles in the JWT.

[chris-hasura]

x-hasura-default-role & x-hasura-allowed-roles, in the JWT claim, are the primary values that are used for permissions. x-hasura-default-role is the role used for the query permissions and it’s value must be included in x-hasura-allowed-roles. These values need to be defined in the JWT claim and the JWT mode needs to be configured in Hasura [docs].

x-hasura-role is actually the secondary or override value for role, which is used for role impersonation. It is defined in an HTTP Header, not in the JWT claim, so that the value can be easily changed in the header, without regenerating the JWT.

In the example below the account has a user role and is able to use/impersonate an admin role. It’s like using sudo in Linux.

JWT Claim

{
...
  "https://hasura.io/jwt/claims": {
    "x-hasura-user-id": "three",
    "x-hasura-default-role": "user",
    "x-hasura-allowed-roles": ["user","admin"]
  }
...
}

HTTP Header x-hasura-role: user

If a JWT is used, session variables will only be read from the JWT claim, not from the HTTP headers (the only exception is x-hasura-role). In addition, if claims_map is used in the configuring the JWT mode, session variables will only be populated from the mapped variables and not from the claims_namespace or the claims_namespace_path.

[codepunkt]

I’m confused as to why a user should switch roles in the first place?