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.

This is covering the Authorization Code Grant flow. To learn about the Device Code Grant flow, see Device code grant.

Useful terminology

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:

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 MSC2964

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.

Client must be registered to get one

This gave us an access token, which we can now use to make authenticated requests to the homeserver.

Refresh token MSC2964

The access token (null) is only valid for a short period of time. It must be refreshed before it expires.

Client must be registered to get one
No refresh token available

Implementation examples