Skip to content
Merged
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
a2e9656
API Scopes MSC
sandhose Jan 14, 2021
544d75b
Proposed insufficient privilege response format
hughns May 16, 2022
d49f2d8
Remove realm as not required
hughns May 18, 2022
23c7638
Clarifications + update on latest device management proposal
hughns Jul 31, 2022
b609c2b
Revised namespace structure + unstable prefixes
hughns Aug 3, 2022
f07b466
Revise prefix for device ID
hughns Aug 3, 2022
1ce049e
Reference to MSC3861 + cleanup
hughns Aug 5, 2022
5c57507
Add scope for guest access and tidy up
hughns Nov 17, 2022
5afb697
No need for UIA scope
hughns Feb 16, 2023
8ec2d7c
Update proposals/2967-api-scopes.md
hughns Jul 28, 2023
8539ab2
Clarification about encoding of device ID within URN scope
hughns May 10, 2024
0666b24
Merge branch 'matrix-org:main' into msc/sandhose/api-scopes
sandhose Sep 3, 2024
f65aef3
Rework MSC
sandhose Sep 4, 2024
660946a
Update proposals/2967-api-scopes.md
sandhose Mar 5, 2025
4dd433f
Reword as dbkr suggested
sandhose Mar 13, 2025
79845f5
Reword how unstable subdivisions are used
sandhose Mar 13, 2025
49550fe
Remove confusing sentence
sandhose Mar 13, 2025
14b962c
Gather all the links at the bottom of the document
sandhose Mar 13, 2025
58f2398
Tyding up, define exactly how device IDs are handled
sandhose Mar 14, 2025
e7531fa
Don't use a table for a single row
sandhose Mar 14, 2025
acc8e91
Typo
sandhose Mar 14, 2025
1304203
Fix math rendering
sandhose Mar 14, 2025
6623b96
Fix the math
sandhose Mar 18, 2025
1ddd733
Minor rewording on device uniqueness
sandhose Mar 18, 2025
a33d1e3
Simplify wording around the ASCII range
sandhose Mar 18, 2025
0800ea6
Typo
sandhose Mar 18, 2025
a7bb99c
Scope vs scope token is confusing
sandhose Mar 18, 2025
abbae1e
Reword how the device ID is requested
sandhose Mar 18, 2025
082625d
Explain why we keep the device ID generation on the client
sandhose Mar 25, 2025
089a789
MSCXXXX is a better placeholder
sandhose Mar 26, 2025
858b7be
The scope MUST have a device ID
sandhose Mar 26, 2025
c9f8690
Clarify that device IDs are still unique per user
sandhose Mar 26, 2025
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
138 changes: 138 additions & 0 deletions proposals/2967-api-scopes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# MSC2967: API scopes

This proposal is part of the broader [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC][MSC3861].

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] introduces the usage of the OAuth 2.0 authorization code grant to authenticate against a Matrix homeserver.

An OAuth 2.0 grant has a scope associated to it which 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 a few scopes to cover existing use cases.

### Scope format

All scopes related to Matrix should start with `urn:matrix:` and use the `:` delimiter for further sub-division.

Scopes related to mapping of Client-Server API access levels should start with `urn:matrix:client:`.

For future MSCs that build on this namespace, unstable subdivisions should be used whilst in development.

For example, if MSCXXXX wants to introduce the `urn:matrix:client:foo` scope, it could use `urn:matrix:client:com.example.mscXXXX.foo` during development.
If it needs to introduce multiple scopes, like `urn:matrix:client:foo` and `urn:matrix:client:bar`, it could use `urn:matrix:client:com.example.mscXXXX:foo` and `urn:matrix:client:com.example.mscXXXX:bar`.

### Allocated scopes

#### Full API read/write access

To support the existing semantic of granting full access to the Matrix C-S API the following scope is assigned:

| Scope | Purpose |
| - | - |
| `urn:matrix:client:api:*` | Grants full access to the Client-Server API |

In the future, a client would request more specific actions when required. e.g. something like `urn:matrix:client:api:read:*`

#### Device ID handling
Copy link
Member

Choose a reason for hiding this comment

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

Hm. I'm surprised that the specifics of the Device ID handling scope is included in this MSC, which otherwise is the framework for defining scopes in general. Is this because this scope is compulsory for OIDC to work? If so, we should say so. If not, at the least, we should say that the scope is defined here as a concrete example of how scopes would work... or failing that, split it into a separate MSC.

If it /is/ primarily intended example of the framework, it just feels a bit weird to also be speccing specific behaviour at the same time - wouldn't it be better to give a fake example, and then clearly separate the Device ID management proposal somehow?

I have a feeling i've missed something here that explains why this isn't completely out of place :D

Copy link
Member Author

Choose a reason for hiding this comment

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

At a high level, this MSC defines two things:

  • a general shape for scopes (including future ones with unstable prefixes)
  • an initial set of scopes: one for wide access to the C-S API, another to specify the device

I have to include somewhere that it is now always the responsibility of the client to allocate a device, but I'm unsure where the right place for this is?

Copy link
Member

Choose a reason for hiding this comment

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

it's fine here imho


Presently a device ID is typically generated by the homeserver and is associated with a specific series of access tokens.

This MSC proposes that the Matrix client is responsible for generating/allocating a device ID.
A client can create a new device ID by generating a random string and asking for its associated scope on login.
A client can adopt and rehydrate an existing device ID by asking for its associated scope on login.
Copy link
Member

Choose a reason for hiding this comment

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

I think this needs some rationale for why we need/want to make this change?

I'm a bit hesitant moving the creation of IDs to clients, as it adds all sorts of edges cases that need to be addressed (clashes, incorrect grammar, etc) and means servers can't encode any information in the device ID (which we don't currently, but you could imagine would be useful).

Copy link
Member

Choose a reason for hiding this comment

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

Talked out of band last Friday morning, and there sounds like there is a bunch of historical context here (that has since become mostly outdated). Conclusion was for @sandhose to comment with the background and a bit or a rationale, and then we can make a final call on whether we want device IDs to be generated on the client or server.

Something that I didn't realise is that the spec currently allows clients to generate device IDs when they log in (mostly for bots and the like).

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've explained why the change isn't bad in practice, and the historical context why it is like that in 082625d

Copy link
Member

Choose a reason for hiding this comment

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

Is it possible for the homeserver to still generate a device ID if a urn:matrix:client:device:<device ID> scope is omitted? Or would that be odd behaviour in the OAuth 2.0 world?

Having the ability for the homeserver to generate the device ID does make very simple matrix clients even simpler (no need to randomly generate a string). But I don't feel strongly that this behaviour must remain; it's only a nice-to-have.

Similarly, I recognise that it's useful for the client to provide a device ID upon login (for device rehydration and other use cases). So I'm happy to see that's still supported.

Copy link
Member

Choose a reason for hiding this comment

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

Thanks for the explanation @sandhose. SCT had a discussion and I believe the conclusion was broadly that this is fine for now, there's not much reason to change it so late in the day.


The client must then add the requested device ID to the grant by including following token in the requested scope:
`urn:matrix:client:device:<device ID>`, where `<device ID>` is the requested device ID.

There MUST be exactly one `urn:matrix:client:device:<device ID>` token in the requested scope.

When generating a new device ID, the client SHOULD generate a random string with enough entropy.
It SHOULD only use characters from the unreserved character list defined by [RFC3986]:

> unreserved = a-z / A-Z / 0-9 / "-" / "." / "_" / "~"

Using this alphabet, a 10 character string is enough to stand a sufficient chance of being unique per user.
The homeserver MAY reject a request for a device ID that is not long enough or contains characters outside the unreserved list.

In any case it MUST only use characters allowed by the OAuth 2.0 scope definition in [RFC6749] section 3.3,
which is defined as the following ASCII ranges: `%x21 / %x23-5B / %x5D-7E`, i.e:

- alphanumeric characters (`A-Z`, `a-z`, `0-9`)
- the following characters: `! # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ \` { | } ~`

### 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.

## Potential issues

### Device ID collision

The Device ID handling involves a change in where device IDs are generated.
Because the device ID is now generated by the client, it is possible to have a device ID collision.

Requiring enough entropy on the device ID ensures that the device ID is unique.
With a 66 character alphabet and a 10 character device ID, the probability of a collision between 100 million devices is around 0.3%:

$$N = 66^{10}$$
$$K = 10^{8}$$
$$P \approx 1 - e^{-\frac{K^2}{2N}}$$
$$P \approx 0.00318$$

This does also restrict the possible alphabet of device IDs, which was not restricted before.

### Generating the device ID on the client

This proposal effectively changes where the device ID is generated, from "most of the time on the server" to "every time on the client."

This doesn't introduce a new mechanism, as clients could already select a device ID instead of letting the server generate one.

One of the original motivation for this change was to adopt existing OAuth 2.0 mechanisms as much as possible.
This meant not introducing Matrix-specific parameters (hence encoding the device ID in the scope) and not relying on non-standard server behaviour (hence the device ID being generated on the client).

In retrospect, because the whole proposal requires a Matrix-specific implementation anyway, compatibility with existing off-the-shelf OAuth 2.0 server implementations isn't a goal anymore:
we could adopt a Matrix-specific parameter to specify the device ID, and let the server generate it if it's not provided.

As generating the device ID on the client hasn't been a problem in practice, this proposal kept it like that to avoid the cost of aligning the implementations.

## Alternatives

### Scopes

Scope 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 subdivisions are open to debate.

## 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`

[MSC1597]: https://github.com/matrix-org/matrix-spec-proposals/pull/1597
[MSC2964]: https://github.com/matrix-org/matrix-spec-proposals/pull/2964
[MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861
[RFC3986]: https://datatracker.ietf.org/doc/html/rfc3986
[RFC6749]: https://datatracker.ietf.org/doc/html/rfc6749