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

Registration is only required the first time a client encounters a homeserver.

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

If the server supports dynamic registration, it can be done by using OAuth::register_client(). After registration, the client ID should be persisted and reused for every session that interacts with that same server.

If dynamic registration is not available, the homeserver should document how to obtain a client ID.

To provide the client ID and metadata if dynamic registration is not available, or if the client is already registered with the issuer, call OAuth::restore_registered_client().

Login

Before logging in, make sure to register the client or to restore its registration, as it is the first step to know how to interact with the issuer.

With OAuth 2.0, logging into a Matrix account is simply logging in with a predefined scope, part of it declaring the device ID of the session.

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().

Persisting/restoring a session

A full OAuth 2.0 session requires two parts:

• The client ID obtained after client registration,
• The user session obtained after login.

Both parts are usually stored separately because the client ID can be reused for any session with the same server, while the user session is unique.

Note that the type returned by OAuth::full_session() is not (de)serializable. This is done on purpose because the client ID and metadata should be stored separately than the user session, as they should be reused for the same homeserver across different user sessions.

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 be able to restore the session at a later time, otherwise 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 obtained with OAuth::account_management_url().

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 and non-WebAssembly

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.

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.

OAuthRegistrationStoreNon-WebAssembly

An API to store and restore OAuth 2.0 client registrations.

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.

ClientRegistrationMethod

The available methods to register or restore a client.

UrlOrQuery

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