mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-01-05 07:23:42 +01:00
Re-write for OpenID auth
This commit is contained in:
David Baker
parent
2c09580e27
commit
6f374dc981
|
|
@ -6,16 +6,15 @@ documents before being permitted to use the service. This proposal introduces a
|
|||
corresponding method that can be used with Identity Servers and Integration
|
||||
Managers.
|
||||
|
||||
The challenge here is that Identity Servers do not require any kind of user
|
||||
login to access the service and so are unable to track what users have agreed
|
||||
to what terms in the way that Homeservers do. We thereforce cannot re-use the
|
||||
same method for Identity Servers without fundamentally changing the Identity
|
||||
Service API.
|
||||
|
||||
Requirements for this proposal are:
|
||||
* ISs and IMs should be able to give multiple documents a user must agree to
|
||||
abide by
|
||||
* Each document shoud be versioned
|
||||
* ISes and IMs must, for each request that they handle, know that the user
|
||||
making the request has agreed to their data being used. This need not be
|
||||
absolute proof (we will always have to trust that the client actually
|
||||
showed the document to the user) but it must be reasonably demonstrable that
|
||||
the user has given informed consent for the client to use that service.
|
||||
* ISs and IMs must be able to prevent users from using the service if they
|
||||
have not provided agreement.
|
||||
* A user should only have to agree to each version of each document once for
|
||||
|
|
@ -27,16 +26,61 @@ Requirements for this proposal are:
|
|||
(bearing in mind that the user must be able to opt-out of components of a
|
||||
service whilst still being able to use the service without that component).
|
||||
|
||||
Identity Servers do not currently require any kind of user login to access the
|
||||
service and so are unable to track what users have agreed to what terms in the
|
||||
way that Homeservers do.
|
||||
|
||||
## Proposal
|
||||
|
||||
Throuhgout this proposal, $prefix will be used to refer to the prefix of the
|
||||
API in question, ie. `/_matrix/identity/api/v1` for the IS API and
|
||||
API in question, ie. `/_matrix/identity/v2` for the IS API and
|
||||
`/_matrix/integrations/v1` for the IM API.
|
||||
|
||||
Note the removal of the `/api` prefix and migration to v2 in the IS API
|
||||
following convention from
|
||||
[MSC2134](https://github.com/matrix-org/matrix-doc/issues/2134).
|
||||
|
||||
This proposal introduces:
|
||||
* The `$prefix/terms` endpoint
|
||||
* The `m.accepted_terms` section in account data
|
||||
* The `X-TERMS-TOKEN` HTTP header
|
||||
|
||||
This proposal relies on both Integration Managers and Identity Servers being
|
||||
able to identity users by their mxid and store the fact that a given mxid has
|
||||
indicated that they accept the terms given. Integration Managers already
|
||||
identity users in this way by authenticating them using the OpenID endpoint on
|
||||
the Homeserver. This proposal introduces the same mechanism to Identity Servers
|
||||
and adds authentication to accross the Identity Service API.
|
||||
|
||||
### IS API Authentication
|
||||
|
||||
All current endpoints within `/_matrix/identity/api/v1/` will be duplicated
|
||||
into `/_matrix/identity/v2`.
|
||||
|
||||
Any request to any endpoint within `/_matrix/identity/v2`, with the exception of
|
||||
`/_matrix/identity/v2` and the new `/_matrix/identity/v2/account/register` may
|
||||
return an error with `M_UNAUTHORIZED` errcode with HTTP status code 401. This
|
||||
indicates that the user must authenticate with OpenID and supply a valid
|
||||
`access_token`.
|
||||
|
||||
The existing endpoints under `/_matrix/identity/api/v1/` continue to be unauthenticated.
|
||||
ISes may support the old v1 API for as long as they wish. Clients must update to use
|
||||
the v2 API as soon as possible.
|
||||
|
||||
OpenID authentication in the IS API will work the same as in the Integration Manager
|
||||
API, as specified in [MSC1961](https://github.com/matrix-org/matrix-doc/issues/1961).
|
||||
|
||||
### IS Register API
|
||||
|
||||
The following new APIs will be introduced to support OpenID auth as per
|
||||
[MSC1961](https://github.com/matrix-org/matrix-doc/issues/1961):
|
||||
|
||||
* `/_matrix/identity/v2/account/register`
|
||||
* `/_matrix/identity/v2/account`
|
||||
* `/_matrix/identity/v2/account/logout`
|
||||
|
||||
Note again the removal of the `/api` prefix and migration to v2 following
|
||||
convention from
|
||||
[MSC2134](https://github.com/matrix-org/matrix-doc/issues/2134).
|
||||
|
||||
### Terms API
|
||||
|
||||
|
|
@ -71,7 +115,7 @@ that the URL contains the version number of the document. The name
|
|||
and version keys, however, are used only to provide a human-readable
|
||||
description of the document to the user.
|
||||
|
||||
In the IM API, the client should provide authentication for this endpoint.
|
||||
The client should provide authentication for this endpoint.
|
||||
|
||||
#### `POST $prefix/terms`:
|
||||
Requests to this endpoint have a single key, `user_accepts` whose value is
|
||||
|
|
@ -84,7 +128,7 @@ the user has agreed to:
|
|||
}
|
||||
```
|
||||
|
||||
In the IM API, the client should provide authentication for this endpoint.
|
||||
The client should provide authentication for this endpoint.
|
||||
|
||||
The clients MUST include the correct URL for the language of the document that
|
||||
was presented to the user and they agreed to. How servers store or serialise
|
||||
|
|
@ -95,24 +139,6 @@ any one language of each document as sufficient, regardless of what language a
|
|||
client is operating in: users should not have to re-consent to documents if
|
||||
they change their client to a different language.
|
||||
|
||||
The response MAY contain a `acceptance_token` which, if given, is an
|
||||
opaque string that the client must store for use in subsequent requests
|
||||
to any endpoint to the same server.
|
||||
|
||||
If the server has stored the fact that the user has agreed to these terms,
|
||||
(which implies the user is authenticated) it can supply no `acceptance_token`.
|
||||
The server may instead choose to supply an `acceptance_token`, for example if,
|
||||
as in the IS API, the user is unauthenticated and therefore the server is
|
||||
unable to store the fact a user has agreed to a set of terms.
|
||||
|
||||
The `acceptance_token` is an opaque string contining characters
|
||||
`[a-zA-Z0-9._-]`. It is up to the server how it computes it, but the server
|
||||
must be able to, given an `acceptance_token`, compute whether it constitutes
|
||||
agreement to a given set of terms. For example, the simplest (but most verbose)
|
||||
implemenation would be to make the `acceptance_token` the JSON array of
|
||||
documents as provided in the request. A smarter implementation may be a simple
|
||||
hash, or even cryptograhic hash if desired.
|
||||
|
||||
### Accepted Terms Account Data
|
||||
|
||||
This proposal also defines the `m.accepted_terms` section in User Account
|
||||
|
|
@ -138,12 +164,17 @@ to this list.
|
|||
|
||||
### Terms Acceptance in the API
|
||||
|
||||
Any request to any endpoint in the IS and IM APIs, with the exception of
|
||||
`/_matrix/identity/api/v1` may return a `M_TERMS_NOT_SIGNED` errcode. This
|
||||
indicates that the user must agree to (new) terms in order to use or continue
|
||||
to use the service. The `_matrix/identity/api/v1/3pid/unbind` must also not
|
||||
return the `M_TERMS_NOT_SIGNED` if the request has a valid signature from a
|
||||
Homeserver.
|
||||
Any request to any endpoint in the IM API, and the `_matrix/identity/v2/`
|
||||
namespace of the IS API, with the exception of `/_matrix/identity/v2` itself,
|
||||
may return:
|
||||
|
||||
* `M_UNAUTHORIZED` errcode with HTTP status code 401. This indicates that
|
||||
the user must authenticate with OpenID and supply a valid `access_token`.
|
||||
* `M_TERMS_NOT_SIGNED` errcode. This indicates that the user must agree to
|
||||
(new) terms in order to use or continue to use the service.
|
||||
|
||||
The `_matrix/identity/v2/3pid/unbind` must not return either of these
|
||||
errors if the request has a valid signature from a Homeserver.
|
||||
|
||||
The client uses the `GET $prefix/terms` endpoint to get the latest set of terms
|
||||
that must be agreed to. It then cross-references this set of documents against
|
||||
|
|
@ -153,25 +184,17 @@ agreement. Once the user has indicated their agreement, then, and only then,
|
|||
must the client use the `POST $prefix/terms` API to signal to the server the
|
||||
set of documents that the user has agreed to.
|
||||
|
||||
If the server returns an `acceptance_token`, the client should include this
|
||||
token in the `X-TERMS-TOKEN` HTTP header in all subsequent requests to an
|
||||
endpoint on the API with the exception of `/_matrix/identity/api/v1`.
|
||||
|
||||
The client must also include the X-TERMS-TOKEN on any request to the Homeserver
|
||||
where it specifies an Identity Server to be used by the Homeserver. Homeservers
|
||||
must read this header from the request headers of any such endpoint and add it
|
||||
to the request headers of any request it makes to the Identity Server.
|
||||
|
||||
Both making the `POST $prefix/terms` request and providing an `X-TERMS-TOKEN`
|
||||
header signal that the user consents to the terms contained within the
|
||||
corresponding documents. That is to say, if a client or user obtains an
|
||||
acceptance token via means other than a response to the `POST $prefix/terms`
|
||||
API, inclusion of the acceptance token in an `X-TERMS-TOKEN` header in a
|
||||
request still constitutes agreement to the terms in the corresponding
|
||||
documents.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
The Identity Service API previously did not require authentication, and OpenID
|
||||
is reasonably complex, adding a significant burden to both clients and servers.
|
||||
A custom HTTP Header was also considered that could be added to assert that the
|
||||
client agrees to a particular set of terms. We decided against this in favour
|
||||
of re-using existing primitives that already exist in the Matrix ecosystem.
|
||||
Custom HTTP Headers are not used anywhere else within Matrix. This also gives a
|
||||
very simple and natural way for ISes to enforce that users may only bind 3pids
|
||||
to their own mxids.
|
||||
|
||||
This introduces a different way of accepting terms from the client/server API
|
||||
which uses User-Interactive Authentication. In the client/server API, the use
|
||||
of UI auth allows terms acceptance to be integrated into the registration flow
|
||||
|
|
@ -189,21 +212,15 @@ the document, but:
|
|||
|
||||
## Potential issues
|
||||
|
||||
If the server does not authentcate users, some mechanism is required to track
|
||||
users agreement to terms. The introduction of an extra HTTP header on all
|
||||
requests adds overhead to every request and complexity to the client to add a
|
||||
custom header.
|
||||
|
||||
This change is not backwards compatible: clients implementing older versions of
|
||||
the specification will expect to be able to access all IS API endpoints without
|
||||
authentication. Care should be taken to manage the rollout of authentication
|
||||
on IS APIs.
|
||||
|
||||
## Security considerations
|
||||
|
||||
The `acceptance_token` is, in effect, a cookie and could be used to identify
|
||||
users of the service. Users of the Integration manager must be authenticated
|
||||
anyway, so this is irrelevant for the IM API. It could allow an Identity Server
|
||||
to identify users where it may otherwise not be able to do so (if a client was
|
||||
careful to mask other identifying HTTP headers). Given most requests to the IS
|
||||
API, by their nature, include 3pids which, even if hashed, will make users
|
||||
easily identifiable, this probably does not add any significant concern.
|
||||
Requiring authentication on the IS API means it will no longer be possible to
|
||||
use it anonymously.
|
||||
|
||||
It is assumed that once servers publish a given version of a document at a
|
||||
given URL, the contents of that URL will not change. This could be mitigated by
|
||||
|
|
|
|||
Loading…
Reference in a new issue