Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC1961: Integration manager authentication APIs #1961

Merged
merged 6 commits into from
Aug 23, 2019
Merged

MSC1961: Integration manager authentication APIs #1961

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d6d0f97
Proposal for basic integration manager authentication APIs
turt2live Apr 9, 2019
0bab70c
Assign MSC number
turt2live Apr 9, 2019
d8283b9
Add option to use query string
turt2live Jun 28, 2019
bfd8e52
Formatting
turt2live Jun 28, 2019
a2a7b7f
Merge branch 'master' into travis/msc/integrations/auth
turt2live Jun 28, 2019
475c64d
Disclose origin story
turt2live Aug 17, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions proposals/1961-integrations-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# 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.


## Proposal

All specified APIs (except `/register`) will take an `Authorization` header with a `Bearer` token returned
turt2live marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this say that all tokens associated with the user should be logged out, not just the token this request was made with?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nope, just the token that was requested. This MSC does not propose an equivalent for /logout/all

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess the follow-up question is then; should IM's have a /account/deactivate? When a user deactivates their account, it would be good for clients to pass that information to the IM, to tell it that this user will no longer exist and that all possible tokens and user information should be deleted. Or should this be a different MSC?

Pinging @lampholder for the privacy side re IM's.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd make that a separate MSC. I'm trying to keep these integration manager MSCs tightly scoped to avoid creeping features, given they are all trying to introduce a whole new API surface. This particular MSC is scoped to just authentication: deactivation is a feature which affects authentication but is not required for authentication. For instance, an integration manager could just delete everything after the last token is logged out. Similarly, there is no API for listing how many tokens you have assigned to you (and logging them out).


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.