Next-gen auth client implementation guide

a.k.a. How to implement next-gen auth in your Matrix client

n.b. The plan is that this document will become a doc on matrix.org. Please feel free to make edits/comments/suggestions etc.

When implementing an next-gen auth client you can test against the OIDC Playground where a number of Homeservers are available in different configurations.

Useful terminology

OAuth 2.0 is a set of specifications defined in RFCs by the IETF
OpenID Connect is an identity layer on top of OAuth 2.0 specs
Authorisation server is the server implementing the OAuth 2.0/OpenID Connect server capabilities. In our case, this is effectively the Homeserver
Issuer is the canonical name and URL of an authorisation server in the OpenID Connect specification
Relying party is the party requesting authorisation. In our case, this is effectively the client
Authorisation server metadata is a set of key/values parameters associated with the authorisation server
Client metadata is a set of key/values parameters associated with the client

Sample flow

Discovery MSC2965

To interact with the OAuth 2.0/OIDC APIs of the homeserver, the client first has to discover the authorisation server metadata. This is defined by MSC2965 and works as follow:

determine the issuer through a new Matrix C-S API
get the server metadata through OpenID Connect Discovery

To first determine the issuer, we must fetch the new GET /auth_issuer endpoint. In out case, that will be https://synapse-oidc.element.dev/_matrix/client/unstable/org.matrix.msc2965/auth_issuer

Now that we have our issuer (https://auth-oidc.element.dev/), we can fetch the OIDC Discovery Document, at https://auth-oidc.element.dev/.well-known/openid-configuration

Client registration MSC2966

We know everything about the server, let’s tell them about us now, by sending out set of client metadata values. This includes things like the name of the client, the logo, redirect URI, etc. Have a go and customise a few things!

The client is now registered with the client ID null

Authorization request MSC2965

We are almost ready to start an authentication flow. We still need to gather the a few parameters that will be used to start the flow.

This includes the state parameter, which is a random string that will be useful to distinguish between different authentication requests. It also includes the code_challenge parameter, which is derived from a random string called the code_verifier.

Putting it all together, we can now start the authentication flow.

https://auth-oidc.element.dev/authorize

?response_type = code

&response_mode = fragment

&client_id = <missing>

&redirect_uri = https%3A%2F%2Fareweoidcyet.com%2Fclient-implementation-guide%2Fcallback

&scope = urn%3Amatrix%3Aorg.matrix.msc2967.client%3Aapi%3A*%20urn%3Amatrix%3Aorg.matrix.msc2967.client%3Adevice%3AABCDEFGHIJKL

&state = ieXei8ohb7miesie

&code_challenge_method = S256

&code_challenge = KjgOR3AZvytATpbxHdwNEYRdpwWMF7Va2zfAauJyoYo

Start authorization flow

Once the authorization is complete, you’ll get a code back, which you can paste bellow and exchange.

Implementation examples

Hydrogen - https://github.com/sandhose/hydrogen-web/blob/sandhose/oidc-login/src/matrix/net/OidcApi.ts
files-sdk-demo - https://github.com/element-hq/files-sdk-demo/blob/oidc/src/ClientManager.ts