letro/letro-authentication-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Add basic documentation for personal sessions (#5187)

Browse Source
This commit is contained in:
reivilibre
2025-11-05 16:19:10 +00:00
committed by GitHub
parent e4e3c6720b ef73828361
commit c2ea8f7fa1
2 changed files with 31 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/topics/admin-api.md
View File

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

28
docs/topics/authorization.md
View File

@@ -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/). <!--- TODO stable deployment -->
### 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