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
- 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
Now that we have our issuer (
), we can fetch the OIDC Discovery Document, at
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
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.
Once the authorization is complete, you’ll get a code
back, which you can paste bellow and exchange.
This gave us an access token, which we can now use to make authenticated requests to the homeserver.
Refresh token MSC2964
The access token (
) is only valid for a short period of time.
It must be refreshed before it expires.