You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/proposals/1961-integrations-auth.md

74 lines
2.7 KiB
Markdown

# MSC1961: Integration manager authentication
A set of common APIs needs to be defined for clients to be able to interact with an integration
manager. This proposal covers the authentication portion of that API.
**Note**: this proposal is part of a larger "Integrations API" which has not yet been defined.
See [MSC1956](https://github.com/matrix-org/matrix-doc/pull/1956) for details.
## Proposal
All specified APIs (except `/register`) will take an `Authorization` header with a `Bearer` token returned
from a call to `/register`. This token is used to authorize the request and to identify who is making the
request. The token may also be specified as the `access_token` query string parameter, similar to the
Client-Server API.
#### POST `/_matrix/integrations/v1/account/register`
Exchanges an OpenID object for a token which can be used to authorize future requests to the manager.
Request body is an OpenID object as returned by `/_matrix/client/r0/user/:userId/openid/request_token`.
Response is:
```json
{
"token": "OpaqueString"
}
```
The token should consist of URL-safe base64 characters. Integration managers should be careful to validate
the OpenID object by ensuring the `/_matrix/federation/v1/openid/userinfo` response has a `sub` which belongs
to the `matrix_server_name` provided in the original OpenID object.
Applications which register for a token are responsible for tracking which integration manager they are for.
This can usually be done by tracking the hostname of the integration manager and matching a token with it.
#### GET `/_matrix/integrations/v1/account`
Gets information about the token's owner, such as the user ID for which it belongs.
Besides a token, no other information is required for the request.
Response is:
```json
{
"user_id": "@alice:example.org"
}
```
The `user_id` is the user ID which was represented in the OpenID object provided to `/register`. Integration
managers may be interested in also supplying information about the user's credit balance for paid integrations
here. Preferably, custom information is stored under a namespaced key like so:
```json
{
"user_id": "@alice:example.org",
"org.example.paid.integrations": {
"credit": 20000
}
}
```
#### POST `/_matrix/integrations/v1/account/logout`
Logs the token out, rendering it useless for future requests.
Request body is an empty object. Response body is also an empty object if successful.
## Security considerations
Clients should be sure to call `/logout` where possible when the user is logging out or no longer needs access
to a given manager. Clients should additionally be cautious about which managers they register for tokens with,
as some integration managers may be untrusted.