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§
- The error types used in this crate.
- OpenID Connect client registration management.
- Methods to interact with OpenID Connect and OAuth2.0 endpoints.
- OAuth 2.0 and OpenID Connect types.
Structs§
- The data returned by the provider in the redirect URI after a successful authorization.
- The data returned by the provider in the redirect URI after an authorization error.
- A high-level authentication API to interact with an OpenID Connect Provider.
- Builder type used to configure optional settings for authorization with an OpenID Connect Provider via the Authorization Code flow.
- The data needed to perform authorization using OpenID Connect.
- Data for the user to log out from their account in the issuer’s interface.
- Builder type used to configure optional settings for constructing an RP-Initiated Logout URL with an OpenID Connect provider.
- A full session for the OpenID Connect API.
- The tokens for a user session obtained with the OpenID Connect API.
- A user session for the OpenID Connect API.
Enums§
- The data returned by the provider in the redirect URI after a successful authorization.
- An error that happened when interacting with the cross-process store lock during a token refresh.
- All errors that can occur when using the OpenID Connect API.
- An error when trying to parse the query of a redirect URI.