MSC2967: API scopes

proposals/2967-api-scopes.md

@@ -0,0 +1,136 @@
+# MSC2967: API scopes
+
+This proposal is part of the broader [MSC3861: Matrix architecture change to delegate authentication via OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/2967).
+
+When a user signs in with a Matrix client, it currently gives the client full access to their Matrix account.
+
+This proposal introduces access scopes to allow restricting client access to only part(s) of the Matrix client API.
+
+## Proposal
+
+[MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) introduces the usage of OAuth 2.0 for a client to authenticate against a Matrix homeserver.
+
+OAuth 2.0 grants have scopes associated to them and provides a framework for obtaining user consent.
+
+The framework encourages the practise of obtaining additional use consent when a client asks for a new scope that was not granted previously.
+
+This MSC does not attempt to define all the scopes necessary to cover all Matrix APIs and use cases, but proposes the structure of a namespace and some specific scopes to cover existing use cases.
+
+Additionally it is proposed that a standard approach to error response representation is adopted across the API. This could replace the UIA based responses that exist on some API endpoints today.
+
+### Scope format
+
+All scopes related to Matrix should start with `urn:matrix` and use the `:` delimiter for further sub-division.
+
+| Prefix | Purpose |
+| - | - |
+| `urn:matrix:client` | For mapping of Client Server API access levels |
+
+For future MSCs that build on this namespace unstable sub divisions should be used whilst in development:
+
+e.g. `urn:matrix:com.example.mscXXXX.foo:something` or `urn:matrix:client:com.example.mscXXXX.something`
+
+### Allocated scopes
+
+#### Legacy use cases
+
+To support existing, pre-MSC2964 use cases the following scopes are assigned:
+
+| Scope | Purpose | Implementation notes |
+| - | - | - |
+| `urn:matrix:client:api:guest` | Grants access as a guest to endpoints in the Client-Server API | The OP can issue a refresh token for grants with this scope. |
+| `urn:matrix:client:api:*` | Grants full access to the Client-Server API | The OP can issue a refresh token for grants with this scope. |
+
+These are referred to as "legacy" because it is envisioned that a client would request more specific actions in future when required. e.g. something like `urn:matrix:client:api:read:*`
+
+#### Device ID handling
+
+Presently a device ID is typically generated by the homeserver and is associated with a specific access token. In OAuth 2.0 there is no such thing as a session and so a mapping cannot be handled using the same mechanism.
+
+MSC2964 proposes that the Matrix client is responsible for generating/allocating a device ID. A client can adopt and rehydrate an existing client by asking for its scope on login.
+
+This also has a nice side-effect: if the device asked was never used by the client making the request, the authorization server will ask for explicit consent from the user.
+
+The client can then bind the device ID to the grant by requesting a scope with the format:
+
+| Scope | Purpose | Implementation notes |
+| - | - | - |
+| `urn:matrix:client:device:<device ID>` | bind the given device ID to the grant/access token | The OIDC Provider must only grant exactly one device scope for a token. |
+
+For the purpose of this MSC we are assuming that device IDs are as per [MSC1597](https://github.com/matrix-org/matrix-spec-proposals/pull/1597) and, as such, are already URL safe and so can be represented as a scope without modification.
+
+### Future scopes
+
+Exact scopes for the whole API are intentionally not specified in this MSC.
+
+It is envisioned that the namespace could be further partitioned to support use cases such as read only, write only, limited to one or more rooms etc.
+
+Some thoughts/ideas for possible scopes are:
+
+- `urn:matrix:client:api:<permission>` or `urn:matrix:client:api:<permission>:*` - grant limited access to the client API in all rooms. Permissions could be read, write, delete, append.
+- `urn:matrix:client:api:read:<resource>` - read-only access to the client API for just the named resource. e.g. `urn:matrix:client:api:read:#matrix-auth`
+
+New MSCs should be created for proposing and discussing such new scopes.
+
+### Insufficient privilege response
+
+It is proposed that a [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) formatted `WWW-Authenticate` response header is used to provide feedback to the client with `error="insufficent_scope"`.
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer error="insufficient_scope", scope="urn:matrix:api:something"
+```
+
+On receipt of such a response the client may then request a new authorization from the issuer as per [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964) requesting the additional scope be granted.
+
+The rest of the response would be as per the [standard error response](https://spec.matrix.org/v1.2/client-server-api/#standard-error-response) spec.
+
+For example:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer error="insufficient_scope", scope="urn:matrix:api:something"
+Content-Type: application/json
+
+{
+  "errcode": "M_FORBIDDEN",
+  "error": "Insufficient scope"
+}
+```
+
+## Potential issues
+
+The Device ID handling involves a change in where device IDs are generated. This is discussed in [MSC2964](https://github.com/matrix-org/matrix-doc/pull/2964). On the OIDC Provider side the device ID proposal requires the use of dynamic scopes. That is, the specific scope is a templated form rather than being static. This is not currently supported by some OpenID Providers (e.g. Okta and Auth0).
+
+The addition of the `WWW-Authenticate` header could cause issue with some clients.
+
+## Alternatives
+
+### Scopes
+
+Scope format could also have an URL format, e.g. `https://matrix.org/api/*/read`.
+
+The URL prefix could either be static (`https://matrix.org`) or dependant on the homeserver (`https://matrix.example.com`).
+In both cases, the URL could be confused with API endpoints and in the second case it would require discovery to know what scopes to ask.
+
+The actual namespace prefix and sub divisions are open to debate.
+
+### Insufficient privilege response
+
+The [standard Client-Server API error response](https://spec.matrix.org/v1.2/client-server-api/#standard-error-response) could be used.
+
+A custom HTTP header could be used instead.
+
+## Security considerations
+
+As we are just representing existing access models there shouldn't be anything special.
+
+## Unstable prefix
+
+While this feature is in development the following unstable scope prefixes should be used:
+
+- `urn:matrix:client` --> `urn:matrix:org.matrix.msc2967.client`
+
+## Dependencies
+
+- [MSC2964: Delegation of auth from homeserver to OIDC Provider](https://github.com/matrix-org/matrix-spec-proposals/pull/2964)