Module matrix_sdk::oidc

source ·
Available on crate feature experimental-oidc only.
Expand description

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 OIDC when Oidc::fetch_authentication_issuer() succeeds.

If the homeserver doesn’t advertise its support for OIDC, but the issuer URL is known by some other method, it can be provided manually during registration.

§Registration

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

If the issuer supports dynamic registration, it can be done by using Oidc::register_client(). If dynamic registration is not available, the homeserver should document how to obtain client credentials.

To make the client aware of being registered successfully, Oidc::restore_registered_client() needs to be called next.

After client registration, the client credentials should be persisted and reused for every session that interacts with that same issuer.

§Login

Before logging in, make sure to call Oidc::restore_registered_client() (even after registering the client), 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 credentials obtained after client registration with the corresponding client metadata,
  • The user session obtained after login.

Both parts are usually stored separately because the client credentials 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 due to some client credentials methods that require a function to generate a JWT. The types of some fields can still be (de)serialized.

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 Oidc::session_tokens_stream() 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.

§Insufficient scope error

Note: This is not fully specced yet.

Some API calls that deal with sensitive data require more privileges than others. In the current Matrix specification, those endpoints use the User-Interactive Authentication API.

The OAuth 2.0 specification has the concept of scopes, and an access token is limited to a given scope when it is generated. Accessing those endpoints require a privileged scope, so a new authorization request is necessary to get a new access token.

When the API endpoint returns an Error with an AuthenticateError::InsufficientScope, the Oidc::authorize_scope() method can be used to authorize the required scope. It works just like Oidc::login().

§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.

Modules§

  • error
    The error types used in this crate.
  • 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.
  • 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.
  • OidcEndSessionData
    Data for the user to log out from their account in the issuer’s interface.
  • OidcEndSessionUrlBuilder
    Builder type used to configure optional settings for constructing an RP-Initiated Logout URL with an OpenID Connect provider.
  • OidcSession
    A full session for the OpenID Connect API.
  • OidcSessionTokens
    The tokens for a user session obtained with the OpenID Connect API.
  • UserSession
    A user session for the OpenID Connect API.

Enums§