Module oidc

Available on crate feature experimental-oidc only.

High-level OpenID Connect API using the Authorization Code flow.

The OpenID Connect 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.

OpenID Connect specification compliance

The OpenID Connect client used in the SDK has not been certified for compliance against the OpenID Connect specification.

It implements only parts of the specification and is currently limited to the Authorization Code flow. It also uses some OAuth 2.0 extensions.

Setup

To enable support for OpenID Connect on the Client, simply enable the experimental-oidc cargo feature for the matrix-sdk crate. Then this authentication API is available with Client::oidc().

Homeserver support

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

Registration

Registration is only required the first time a client encounters an issuer.

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

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

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 Oidc::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 OIDC, logging into a Matrix account is simply logging in with a predefined scope, part of it declaring the device ID of the session.

Oidc::login() constructs an OidcAuthCodeUrlBuilder that can be configured, and then calling OidcAuthCodeUrlBuilder::build() will provide the URL to present to the user in a web browser. After authenticating with the OIDC provider, the user will be redirected to the provided redirect URI, with a code in the query that will allow to finish the authorization process by calling Oidc::finish_authorization().

When the login is successful, you must then call Oidc::finish_login().

Persisting/restoring a session

A full OIDC session requires two parts:

• The client ID obtained after client registration with the corresponding client metadata,
• 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 issuer, while the user session is unique.

Note that the type returned by Oidc::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 provider across with different user sessions.

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

Refresh tokens

The use of refresh tokens with OpenID Connect Providers 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 Oidc::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 Oidc::login(), using the device ID from the session. Note that in this case Oidc::finish_login() must NOT be called after Oidc::finish_authorization().

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

Account management.

The homeserver or provider might advertise a URL that allows the user to manage their account, it can be obtained with Oidc::account_management_url().

Logout

To log the Client out of the session, simply call Oidc::logout(). If the provider supports it, it will return a URL to present to the user if they also want to log out from their account on the provider’s website.

Examples

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

Re-exports

pub use self::error::OidcError;

Modules

error

Error types used in the Oidc API.

qrcodee2e-encryption and non-WebAssembly

Types for the QR code login support defined in MSC4108.

registrations

OpenID Connect client registration management.

requests

Methods to interact with OpenID Connect and OAuth2.0 endpoints.

types

OAuth 2.0 and OpenID Connect types.

Structs

AuthorizationCode

The data returned by the provider in the redirect URI after a successful authorization.

AuthorizationError

The data returned by the provider in the redirect URI after an authorization error.

CsrfToken

Value used for CSRF protection via the state parameter.

Oidc

A high-level authentication API to interact with an OpenID Connect Provider.

OidcAuthCodeUrlBuilder

Builder type used to configure optional settings for authorization with an OpenID Connect Provider via the Authorization Code flow.

OidcAuthorizationData

The data needed to perform authorization using OpenID Connect.

OidcSession

A full session for the OpenID Connect API.

UserSession

A user session for the OpenID Connect API.

Enums

AuthorizationResponse

The data returned by the provider in the redirect URI after a successful authorization.