Document the default policy behaviour around admin scopes

[Quentin Gliech]

The default policy is not documented at all, but it is especially tricky to understand how admin scopes (urn:synapse:admin:* and urn:mas:admin) interact with it. This needs to be documented

A few informations to include, in a very brain-dumpy format:

• There are three main ways to get an access token:
  • Interactively, through an authorisation code grant, in which case the token has a user attached to it. This is regulated by the policy engine
  • Programatically, through a client credentials grant, in which case the token has no user attached to it, only an OAuth client. This is regulated by the policy engine
  • Programatically, through MAS' GraphQL API, using the createOauth2Session mutation. This is completely unregulated, arbitrary (including non-existing) scopes can be granted through this. The only restriction is that the token making the API call needs to be admin (= has the urn:mas:admin scope)
• The urn:synapse:admin:* scope grants access to /_synapse/admin/*. Because of some Synapse subtlety, this scope has to be linked to a user, so it can't be requested through the client credentials grant
• The urn:mas:admin scope grants admin access to MAS' GraphQL API, which lets it request and edit resources of other users than the current one, and access a few privileged mutations. When requesting this scope, the urn:mas:graphql:* scope should be requested as well.
• With the default policy, a user can request the urn:synapse:admin:* scope or the urn:mas:admin scope if:
  • their username (aka. localpart of the MXID) is listed in policy.data.admin_users
  • or if their account has the can_request_admin flag in the database set to true (see below about toggling that flag)
• With the default policy, a client can request the urn:mas:admin scope if their client ID is listed in policy.data.admin_clients
• The GraphQL schema is self-documented. A playground can be found in MAS itself, for example: https://auth-oidc.lab.element.dev/graphql/playground
• The URL of the GraphQL endpoint can be discovered with the org.matrix.matrix-authentication-service.graphql_endpoint property in the OIDC discovery document
• The can_request_admin flag can be found on the users table in the database, and can be dynamically toggled using the setCanRequestAdmin mutation. This mutation requires a userId, which can be found on users using the userByUsername query method

[Dirk Klimpel]

I tried to configure a user via policy.data.admin_users as admin.

The user gets always the normal user claims:
Introspection result: {'active': True, 'scope': 'urn:matrix:org.matrix.msc2967.client:api:* urn:matrix:org.matrix.msc2967.client:device:l1qiNGItBF', 'client_id': 'legacy'

Do I understand correctly that the admin claim must be explicitly requested? And does this also work via legacy OIDC login?
_matrix/client/r0/login/sso/redirect?redirectUrl=https%3A%2F%2F...