OAuth2

Base URL

base_url: Defines the base URL where the Venator oauth paths can be reached.

The following paths must be reachable publicly for this to work:

• /_venator/v0/oauth2/*
• /_matrix/static/* (can safely be cached in a reverse proxy)

This must be provided to enable OAuth2 support. Likewise, it must be a publicly accessible URL, and the domain must be as visible in the browser (otherwise the cookies will point at the wrong domain, and sensitive requests will be bounced for CSRF).

It is recommended that this URL belongs to a domain other than the client-server API, however this is not required. It must be a HTTPS URL, however. Including a trailing slash in the URL may cause weird side effects.

Tip

Some static resources for the web interface, such as CSS are served from /_matrix/static - this is accessed via the client-server base url where possible, but will fall back to this base_url. It is recommended you also set well-known.client in case this changes in future.

Example:

oauth2:
  base_url: "https://account.venator.example"

Access token lifetime

access_token_lifetime: A duration for which access tokens will be valid. Defaults to 1 hour (1h).

Important

This ONLY affects access tokens acquired through OAuth2. Legacy authentication tokens are indefinite regardless, as they cannot be refreshed.

This duration should not be any less than an hour, and should not be any more than a week (although it can be). Access tokens are short-lived and consequently wield a lot of power, but can be refreshed for a very long period afterwards. Refreshing a token generates a new one without impacting the session, meaning access tokens are rotated frequently, making them more secure.

Example:

oauth2:
  access_token_lifetime: 1d

Refresh token lifetime

refresh_token_lifetime: A duration for which refresh tokens will be valid. Defaults to 90 days (90d).

Refresh tokens are intentionally long-lived and allow access tokens to be refreshed. A longer period is essential to ensure clients aren’t logged out if their users go fishing for a few weeks, so a reasonable (on the higher end) expiration for refresh tokens is 90 days. Some servers may wish to raise this to 1 year, however it should never be beyond that, and should never be less than a month.

Refresh tokens dictate the maximum lifespan of a session, and are also regenerated when used. The longer the validity period, the higher the chances of a compromised account being taken over are. Take this into consideration.

Example:

oauth2:
  refresh_token_lifetime: 30d