matrix/authentication-service
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-authentication-service.git synced 2025-07-28 11:02:02 +03:00
Code Activity

Document the admin API (#3038)

Browse Source 
Co-authored-by: Hugh Nimmo-Smith <hughns@matrix.org>
This commit is contained in:
Quentin Gliech
2024-08-07 17:41:46 +02:00
committed by GitHub
parent b4eb93558d
commit eb4072f3c3
7 changed files with 302 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/configuration.md
View File

@ -44,6 +44,8 @@ http:
# Serve the given folder on the /assets/ path
- name: assets
path: ./share/assets/
# Serve the admin API on the /api/admin/v1/ path. Disabled by default
#- name: adminapi
# List of addresses and ports to listen to
binds:

27
docs/reference/graphql.md
View File

@ -1,27 +0,0 @@
# GraphQL API
MAS provides a GraphQL API which serves two purposes:
- it is used by the self-service user interface (usually accessible on `/account/`), for users to manage their own account.
- it can be used with external tools to manage the service.
The endpoint for this API can be discovered through the OpenID Connect discovery document, under the `"org.matrix.matrix-authentication-service.graphql_endpoint` key.
Though it is usually hosted at `https://<mas-host>/graphql`.
GraphQL uses [a self-describing schema](https://github.com/matrix-org/matrix-authentication-service/blob/main/frontend/schema.graphql), which means that the API can be explored in tools like the GraphQL Playground.
If enabled, MAS hosts an instance of the playground at `https://<mas-host>/graphql/playground`.
## Authorization
There are two ways to authorize a request to the GraphQL API:
- if you are requesting from the self-service user interface (or the MAS-hosted GraphQL Playground), it will use the session cookies to authorize as the current user. This mode only allows the user to access their own data, and will never provide admin access.
- else you will need to provide an OAuth 2.0 access token in the `Authorization` header, with the `Bearer` scheme.
The access token must have the [`urn:mas:graphql:*`] scope to be able to access the GraphQL API.
With only this scope, the session will be authorized as the user who owns the access token, and will only be able to access their own data.
To get full access to the GraphQL API, the access token must have the [`urn:mas:admin`] scope in addition to the [`urn:mas:graphql:*`] scope.
[`urn:mas:graphql:*`]: ./scopes.md#urnmasgraphql
[`urn:mas:admin`]: ./scopes.md#urnmasadmin

27
docs/reference/scopes.md
View File

@ -8,8 +8,8 @@ The [default policy](../topics/policy.md#authorization-requests) shipped with MA
- [`urn:matrix:org.matrix.msc2967.client:device:[device id]`](#urnmatrixorgmatrixmsc2967clientdevicedevice-id)
- [`urn:matrix:org.matrix.msc2967.client:guest`](#urnmatrixorgmatrixmsc2967clientguest)
- [`urn:synapse:admin:*`](#urnsynapseadmin)
- [`urn:mas:graphql:*`](#urnmasgraphql)
- [`urn:mas:admin`](#urnmasadmin)
- [`urn:mas:graphql:*`](#urnmasgraphql)
## OpenID Connect scopes
@ -79,19 +79,9 @@ It allows:
MAS also has a few scopes that are specific to the MAS implementation.
### `urn:mas:graphql:*`
This scope grants access to the whole MAS [GraphQL API].
What permission the session has on the API is determined by the entity that the session is authorized as.
When [authorized as a user](../topics/authorization.md#authorized-as-a-user-or-authorized-as-a-client) (and without the `mas:urn:admin` scope), this will usually allow querying and mutating the user's own data.
The default policy allows any client and any user to request this scope.
### `urn:mas:admin`
This scope allows full access to the MAS [GraphQL API].
It requires the `urn:mas:graphql:*` scope to be present in the request.
This allows the authenticated entity to perform any operation on the API, regardless of whether the entity owns the data or not.
This scope grants full access to the MAS [Admin API].
The default policy doesn't allow everyone to request this scope.
It allows:
@ -102,9 +92,20 @@ It allows:
- for the "client credentials" grant:
- clients that are listed in the [`policy.data.admin_clients`](../reference/configuration.md#policy) configuration option
### `urn:mas:graphql:*`
This scope grants access to the whole MAS [Internal GraphQL API].
What permission the session has on the API is determined by the entity that the session is authorized as.
When [authorized as a user](../topics/authorization.md#authorized-as-a-user-or-authorized-as-a-client) (and without the `mas:urn:admin` scope), this will usually allow querying and mutating the user's own data.
The default policy allows any client and any user to request this scope.
However, as noted in the [Internal GraphQL API] documentation, access to the Internal GraphQL API from outside of MAS itself is deprecated in favour of the [Admin API].
[authorization code]: ../topics/authorization.md#authorization-code-grant
[device authorization]: ../topics/authorization.md#device-authorization-grant
[GraphQL API]: ./graphql.md
[Internal GraphQL API]: ../development/graphql.md
[Admin API]: ../topics/admin-api.md
[Synapse admin API]: https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html
[OpenID Connect Core 1.0]: https://openid.net/specs/openid-connect-core-1_0.html
[MSC2967]: https://github.com/matrix-org/matrix-spec-proposals/pull/2967