Merge pull request #1961 from matrix-org/travis/msc/integrations/auth

MSC1961: Integration manager authentication APIs

proposals/1961-integrations-auth.md

@@ -0,0 +1,73 @@
+# 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.