diff --git a/docs/topics/admin-api.md b/docs/topics/admin-api.md index 75d5e2b0a..8aa992c76 100644 --- a/docs/topics/admin-api.md +++ b/docs/topics/admin-api.md @@ -46,7 +46,9 @@ If admin API is enabled, MAS will also serve the specification at `/api/spec.jso ## Authentication -All requests to the admin API are gated using access tokens obtained using OAuth 2.0 grants. +All requests to the admin API are gated either using access tokens obtained using OAuth 2.0 grants, +or using personal access tokens (which must currently be issued through the Admin API). + They must have the [`urn:mas:admin`](../reference/scopes.md#urnmasadmin) scope. ### User-interactive tools diff --git a/docs/topics/authorization.md b/docs/topics/authorization.md index d2d7ab29c..1bdeb8207 100644 --- a/docs/topics/authorization.md +++ b/docs/topics/authorization.md @@ -129,6 +129,33 @@ It may also be used in the future as a foundation for a new Application Service This works by presenting the client credentials to get back an access token. The simplest type of client credentials is a client ID and client secret pair, but MAS also supports client authentication with a JWT ([RFC 7523]), which is a robust way to authenticate clients without a shared secret. +## Personal sessions (personal access tokens) + +Personal access tokens are a credential that can be issued to give access to a user, +with predefined scopes and a predefined expiry time. +Either before or after expiry, the owner of the token can regenerate it, which produces a new +access token with the same scopes but a new expiry time. + +Personal access tokens are intended to fulfill two basic use cases: + +1. an easy way to obtain a clean token for your own user, for use in automation and scripts; +2. a way to obtain a token for administrative access of another user, either for ad-hoc administrative operations or to set up a bot or similar service. + +In the future, users will be able to create their own personal access tokens, but this is currently not implemented +so (1) is currently not supported. + +For now, personal access tokens must be created, regenerated and revoked by administrators through the [Admin API], satisfying use case (2). +[Element Admin](https://github.com/element-hq/element-admin), available by default in Element Server Suite, can be used to do this interactively. +You can also use the online beta deployment at [admin-beta.element.dev](https://admin-beta.element.dev/). + +### Validity + +Personal sessions can be used so long as: + +- the owner (creator) of the token is still an active and unlocked user (or static OAuth 2 client); and +- the actor (target user, or user being controlled by the token) has not been deactivated. Though the actor is allowed to be locked. + + [MSC4108]: https://github.com/matrix-org/matrix-spec-proposals/pull/4108 [RFC 6749]: https://datatracker.ietf.org/doc/html/rfc6749 [RFC 7523]: https://datatracker.ietf.org/doc/html/rfc7523 @@ -140,3 +167,4 @@ The simplest type of client credentials is a client ID and client secret pair, b [`urn:synapse:admin:*`]: ../reference/scopes.md#urnsynapseadmin [`urn:mas:graphql:*`]: ../reference/scopes.md#urnmasgraphql [`urn:mas:admin`]: ../reference/scopes.md#urnmasadmin +[Admin API]: ./admin-api.md