Using the Device Code Grant

The Device Code Grant is a type of OAuth 2.0 grant that is used in contexts where opening the user’s browser is not possible or desirable.

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!

Because we would like to use the Device Code Grant, we need to add the urn:ietf:params:oauth:grant-type:device_code grant type to the list of requested grant types.

The client is now registered with the client ID null

Device authorisation request RFC8628

We are ready to start the authentication process. To do so, we will start a session by sending a request to the device authorization endpoint.

This gave us three values:

A device_code, which we will need to exchange for an access token
A user_code, which we will display to the user for them to enter
A verification_uri, which we will ask the user to visit to complete the flow

https://auth-oidc.element.dev/linkStart the device authorisation flow to get a code

Token request RFC8628

In the background, the client must now poll the token endpoint to exchange the device code for an access token.

To do so, we will send a request to the token endpoint, with the following parameters:

grant_type set to urn:ietf:params:oauth:grant-type:device_code
device_code set to the device code we received from the device authorization endpoint
client_id set to the client ID we registered

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.