Module oauth

High-level OAuth 2.0 API.

The OAuth 2.0 interactions with the Matrix API are currently a work-in-progress and are defined by MSC3861 and its sub-proposals. And more documentation is available at areweoidcyet.com.

This authentication API is available with Client::oauth().

Homeserver support

After building the client, you can check that the homeserver supports logging in via OAuth 2.0 when OAuth::server_metadata() succeeds.

Registration

Clients must register with the homeserver before being able to interact with an OAuth 2.0 server.

The registration consists in providing client metadata to the authorization server, to declare the interactions that the client supports with the homeserver. This step is important because the client cannot use a feature that is not declared during registration. In return, the server assigns an ID and eventually credentials to the client, which will allow to identify the client when authorization requests are made.

Note that only public clients are supported by this API, i.e. clients without credentials.

The registration step can be done automatically by providing a ClientRegistrationData to the login method.

If the server supports dynamic registration, registration can be performed manually by using OAuth::register_client(). If dynamic registration is not available, the homeserver should document how to obtain a client ID. The client ID can then be provided with OAuth::restore_registered_client().

Login

Currently, two login methods are supported by this API.

Login with the Authorization Code flow

The use of the Authorization Code flow is defined in MSC2964 and RFC 6749.

This method requires to open a URL in the end-user’s browser where they will be able to log into their account in the server’s web UI and grant access to their Matrix account.

OAuth::login() constructs an OAuthAuthCodeUrlBuilder that can be configured, and then calling OAuthAuthCodeUrlBuilder::build() will provide the URL to present to the user in a web browser.

After authenticating with the server, the user will be redirected to the provided redirect URI, with a code in the query that will allow to finish the login process by calling OAuth::finish_login().

If the login needs to be cancelled before its completion, OAuth::abort_login() should be called to clean up the local data.

Login by scanning a QR Code

Logging in via a QR code is defined in MSC4108. It uses the Device authorization flow specified in RFC 8628.

This method requires to have another logged-in Matrix device that can display a QR Code.

This login method is only available if the e2e-encryption cargo feature is enabled. It is not available on WASM.

After scanning the QR Code, OAuth::login_with_qr_code() can be called with the QR Code’s data. Then the different steps of the process need to be followed with LoginWithQrCode::subscribe_to_progress().

A successful login using this method will automatically mark the device as verified and transfer all end-to-end encryption related secrets, like the private cross-signing keys and the backup key from the existing device to the new device.

Persisting/restoring a session

The full session to persist can be obtained with OAuth::full_session(). The different parts can also be retrieved with Client::session_meta(), Client::session_tokens() and OAuth::client_id().

To restore a previous session, use OAuth::restore_session().

Refresh tokens

The use of refresh tokens with OAuth 2.0 servers is more common than in the Matrix specification. For this reason, it is recommended to configure the client with ClientBuilder::handle_refresh_tokens(), to handle refreshing tokens automatically.

Applications should then listen to session tokens changes after logging in with Client::subscribe_to_session_changes() to persist them on every change. If they are not persisted properly, the end-user will need to login again.

Unknown token error

A request to the Matrix API can return an Error with an ErrorKind::UnknownToken.

The first step is to try to refresh the token with OAuth::refresh_access_token(). This step is done automatically if the client was built with ClientBuilder::handle_refresh_tokens().

If refreshing the access token fails, the next step is to try to request a new login authorization with OAuth::login(), using the device ID from the session.

If this fails again, the client should assume to be logged out, and all local data should be erased.

Account management.

The server might advertise a URL that allows the user to manage their account. It can be used to replace most of the Matrix APIs requiring User-Interactive Authentication.

An AccountManagementUrlBuilder can be obtained with OAuth::account_management_url(). Then the action that the user wants to perform can be customized with AccountManagementUrlBuilder::action(). Finally you can obtain the final URL to present to the user with AccountManagementUrlBuilder::build().

Logout

To log the Client out of the session, simply call OAuth::logout().

Examples

Most methods have examples, there is also an example CLI application that supports all the actions described here, in examples/oauth_cli.

Re-exports

pub use self::error::OAuthError;

Modules

error

Error types used in the OAuth API.

qrcodee2e-encryption

Types for the QR code login support defined in MSC4108.

registration

Types and functions for OAuth 2.0 Dynamic Client Registration (RFC 7591).

Structs

AccountManagementUrlBuilder

Builder for the URL for accessing the account management capabilities, as defined in MSC4191.

ClientId

Client identifier issued to the client during the registration process described by Section 2.2.

ClientRegistrationData

Data to register or restore a client.

CsrfToken

Value used for CSRF protection via the state parameter.

OAuth

A high-level authentication API to interact with an OAuth 2.0 authorization server.

OAuthAuthCodeUrlBuilder

Builder type used to configure optional settings for authorization with an OAuth 2.0 authorization server via the Authorization Code flow.

OAuthAuthorizationData

The data needed to perform authorization using OAuth 2.0.

OAuthSession

A full session for the OAuth 2.0 API.

UserSession

A user session for the OAuth 2.0 API.

Enums

AccountManagementActionFull

An account management action that a user can take, including a device ID for the actions that support it.

UrlOrQuery

A full URL or just the query part of a URL.