From d6d0f9780dc3948f25bac7880adea6602650ec4e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Apr 2019 21:36:16 -0600 Subject: [PATCH 1/5] Proposal for basic integration manager authentication APIs --- proposals/0000-integrations-auth.md | 69 +++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 proposals/0000-integrations-auth.md diff --git a/proposals/0000-integrations-auth.md b/proposals/0000-integrations-auth.md new file mode 100644 index 00000000..1a491790 --- /dev/null +++ b/proposals/0000-integrations-auth.md @@ -0,0 +1,69 @@ +# MSC0000: 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 +from a call to `/register`. This token is used to authorize the request and to identify who is making the +request. + +#### 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. From 0bab70c14e84ff71146cc9a8dce7071e1021d75f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 8 Apr 2019 21:37:35 -0600 Subject: [PATCH 2/5] Assign MSC number --- .../{0000-integrations-auth.md => 1961-integrations-auth.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{0000-integrations-auth.md => 1961-integrations-auth.md} (98%) diff --git a/proposals/0000-integrations-auth.md b/proposals/1961-integrations-auth.md similarity index 98% rename from proposals/0000-integrations-auth.md rename to proposals/1961-integrations-auth.md index 1a491790..863ea325 100644 --- a/proposals/0000-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -1,4 +1,4 @@ -# MSC0000: Integration manager authentication +# 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. From d8283b9cdf15f3b37990f67f2d7c49d5b863f9af Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Jun 2019 20:44:49 -0600 Subject: [PATCH 3/5] Add option to use query string --- proposals/1961-integrations-auth.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1961-integrations-auth.md b/proposals/1961-integrations-auth.md index 863ea325..cf69af27 100644 --- a/proposals/1961-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -8,7 +8,8 @@ manager. This proposal covers the authentication portion of that API. 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. +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 From bfd8e52c234d367c9adc4ec686fc77b3b2f02c1d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 27 Jun 2019 20:45:23 -0600 Subject: [PATCH 4/5] Formatting --- proposals/1961-integrations-auth.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/1961-integrations-auth.md b/proposals/1961-integrations-auth.md index cf69af27..7f735607 100644 --- a/proposals/1961-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -11,7 +11,7 @@ from a call to `/register`. This token is used to authorize the request and to i 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 +#### POST `/_matrix/integrations/v1/account/register` Exchanges an OpenID object for a token which can be used to authorize future requests to the manager. @@ -31,7 +31,7 @@ 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 +#### GET `/_matrix/integrations/v1/account` Gets information about the token's owner, such as the user ID for which it belongs. @@ -56,7 +56,7 @@ here. Preferably, custom information is stored under a namespaced key like so: } ``` -#### POST /_matrix/integrations/v1/account/logout +#### POST `/_matrix/integrations/v1/account/logout` Logs the token out, rendering it useless for future requests. From 475c64de8c2827b772372ba0b6c53051b9d94e27 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 16 Aug 2019 19:52:35 -0600 Subject: [PATCH 5/5] Disclose origin story --- proposals/1961-integrations-auth.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/1961-integrations-auth.md b/proposals/1961-integrations-auth.md index 7f735607..1f868e4c 100644 --- a/proposals/1961-integrations-auth.md +++ b/proposals/1961-integrations-auth.md @@ -3,6 +3,9 @@ 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