Struct IdentityProvider 

pub struct IdentityProvider {

    pub brand: String,
    pub client_id: String,
    pub client_secret: Option<String>,
    pub client_secret_file: Option<PathBuf>,
    pub issuer_url: Option<Url>,
    pub callback_url: Option<Url>,
    pub default: bool,
    pub name: Option<String>,
    pub icon: Option<OwnedMxcUri>,
    pub scope: BTreeSet<String>,
    pub userid_claims: BTreeSet<String>,
    pub trusted: bool,
    pub unique_id_fallbacks: bool,
    pub registration: bool,
    pub base_path: Option<String>,
    pub discovery_url: Option<Url>,
    pub authorization_url: Option<Url>,
    pub token_url: Option<Url>,
    pub revocation_url: Option<Url>,
    pub introspection_url: Option<Url>,
    pub userinfo_url: Option<Url>,
    pub discovery: bool,
    pub grant_session_duration: Option<u64>,
    pub check_cookie: bool,
    pub extra_authorization_parameters: BTreeMap<String, String>,
}

Fields

brand: String

The brand-name of the service (e.g. Apple, Facebook, GitHub, GitLab, Google) or the software (e.g. keycloak, MAS) providing the identity. When a brand is recognized we apply certain defaults to this config for your convenience. For certain brands we apply essential internal workarounds specific to that provider; it is important to configure this field properly when a provider needs to be recognized (like GitHub for example).

Several configured providers can share the same brand name. It is not case-sensitive. As a convenience for common simple deployments we can identify this provider by brand in addition to the unique client_id if and only if there is a single provider for the brand; see notes for client_id.

client_id: String

The ID of your OAuth application which the provider generates upon registration. This ID then uniquely identifies this configuration instance itself, becoming the identity provider’s ID and must be unique and remain unchanged.

As a convenience we also identify this config by brand if and only if there is a single provider configured for a brand. Note carefully that multiple providers configured with the same brand is not an error and this provider will simply not be found when querying by brand.

client_secret: Option<String>

Secret key the provider generated for you along with the client_id above. Unlike the client_id, the client_secret can be changed here whenever the provider regenerates one for you.

display: sensitive

client_secret_file: Option<PathBuf>

Secret key to use that’s read from the file path specified.

This takes priority over “client_secret” first, and falls back to “client_secret” if invalid or failed to open.

example: “/etc/tuwunel/.client_secret”

issuer_url: Option<Url>

Issuer URL the provider publishes for you. We have pre-supplied default values for some of the canonical public providers, making this field optional based on the brand set above. Otherwise it is required to find self-hosted providers. It must be identical to what is configured and expected by the provider and must never change because we associate identities to it. If the /.well-known/openid-configuration is not found behind this URL see base_path below as a workaround.

callback_url: Option<Url>

The callback URL configured when registering the OAuth application with the provider. Tuwunel’s callback URL must be strictly formatted exactly as instructed. The URL host must point directly at the matrix server and use the following path: /_matrix/client/unstable/login/sso/callback/<client_id> where <client_id> is the same one configured for this provider above.

default: bool

When more than one identity_provider has been configured and single_sso is false and sso_custom_providers_page is false this will determine the behavior of the /_matrix/client/v3/login/sso/redirect endpoint (note the url lacks a trailing client_id).

When only one identity_provider is configured it will be interpreted as the default and this does not need to be set. Otherwise a default must be selected for some clients (e.g. fluffychat) to work properly when the above conditions require it. To operate out-of-the-box we default to one configured provider if none are explicitly default; a warning will be logged on startup for this condition.

(EXPERIMENTAL) Multiple providers can be set to default. All providers configured with this option set to true will associate with the same Matrix account when a client flows through /_matrix/client/v3/login/sso/redirect.

When a user authorizes any provider configured default, the flow will include all other providers configured default as well for association. NOTE: authorization must succeed for ALL default providers.

name: Option<String>

Optional display-name for this provider instance seen on the login page by users. It defaults to brand. When configuring multiple providers using the same brand this can be set to distinguish them.

icon: Option<OwnedMxcUri>

Optional icon for the provider. The canonical providers have a default icon based on the brand supplied above when this is not supplied. Note that it uses an MXC url which is curious in the auth-media era and may not be reliable.

scope: BTreeSet<String>

Optional list of scopes to authorize. An empty array does not impose any restrictions from here, effectively defaulting to all scopes you configured for the OAuth application at the provider. This setting allows for restricting to a subset of those scopes for this instance. Note the user can further restrict scopes during their authorization.

default: []

userid_claims: BTreeSet<String>

Optional list of userinfo claims which shape and restrict the way we compute a Matrix UserId for new registrations. Reviewing Tuwunel’s documentation will be necessary for a complete description in detail. An empty array imposes no restriction here, avoiding generated fallbacks as much as possible.

For simplicity we reserve a claim called “unique” which can be listed alone to ensure only generated ID’s are used for registrations.

Note that listing the claim “sub” has special significance and will take precedence over all other claims, listed or unlisted. “sub” is not normally used to determine a UserId unless explicitly listed here.

As of now arbitrary claims cannot be listed here, we only recognize specific hard-coded claims.

default: []

trusted: bool

Trusted providers can cause username conflicts (i.e. account hijacking) but this is precisely how an existing matrix account can be associated with a provider. When this option is set to true, the way we compute a Matrix UserId from userinfo claims is inverted: we find the first matching user and grant access to it. Whereas by default, when set to false, we skip matching users and register the first available username; falling-back to random characters to avoid conflicts.

Only set this option to true for providers you self-host and control. Never set this option to true for the public providers such as GitHub, GitLab, etc.

Note that associating an existing user with an untrusted provider is still possible but only with the command ‘!admin query oauth associate’.

default: false

unique_id_fallbacks: bool

Setting this option to false will inhibit unique ID’s from being generated as a last-resort when determining a UserId from a provider’s claims. In the case of untrusted providers, when all provided claims conflict with existing user accounts, a unique fallback ID needs to be generated for registration to not be denied with an error.

Set this option to false if you operate a private server or a trusted identity provider where random UserId’s are undesirable; the result of a misconfiguration or other issue where an error is warranted.

This option should be set to true for public servers or some users may never be able to register.

default: true

registration: bool

Controls whether new user registration is possible from this provider. When this option is set to false, authorizations from this provider only affect existing users and will never result in a new registration when the claims fail to match any existing user (in the case of trusted providers) or an available username is found (in the case of untrusted providers).

Setting this option to false is generally not useful unless there is an explicit reason to do so.

default: true

base_path: Option<String>

Optional extra path components after the issuer_url leading to the location of the .well-known directory used for discovery. If the path starts with a slash it will be treated as absolute, meaning overwriting any path in the issuer_url. The path needs to end with a slash. This will be empty for specification-compliant providers. We have supplied any known values based on brand (e.g. login/oauth/ for GitHub).

discovery_url: Option<Url>

Overrides the .well-known location where the provider’s openid configuration is found. It is very unlikely you will need to set this; available for developers or special purposes only.

authorization_url: Option<Url>

Overrides the authorize URL requested during the grant phase. This is generally discovered or derived automatically, but may be required as a workaround for any non-standard or undiscoverable provider.

token_url: Option<Url>

Overrides the access token URL; the same caveats apply as with the other URL overrides.

revocation_url: Option<Url>

Overrides the revocation URL; the same caveats apply as with the other URL overrides.

introspection_url: Option<Url>

Overrides the introspection URL; the same caveats apply as with the other URL overrides.

userinfo_url: Option<Url>

Overrides the userinfo URL; the same caveats apply as with the other URL overrides.

discovery: bool

Whether to perform discovery and adjust this provider’s configuration accordingly. This defaults to true. When true, it is an error when discovery fails and authorizations will not be attempted to the provider.

grant_session_duration: Option<u64>

The duration in seconds before a grant authorization session expires.

default: 300

check_cookie: bool

Whether to check the redirect cookie during the callback. This is a security feature and should remain enabled. This is available for developers or deployments which cannot tolerate cookies and are willing to tolerate the risks.

default: true

extra_authorization_parameters: BTreeMap<String, String>

Extra query parameters appended to every authorization request sent to the identity provider.

E.g. to force re-authentication even if IdP cookies are present:

[[global.identity_provider]]
extra_authorization_parameters = { prompt = "login" }

default: {}

Implementations

impl IdentityProvider

pub fn id(&self) -> &str

pub async fn get_client_secret(&self) -> Result<String>

Trait Implementations

impl Clone for IdentityProvider

fn clone(&self) -> IdentityProvider

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IdentityProvider

fn fmt(&self, __derive_more_f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for IdentityProvider

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for IdentityProvider

fn fmt(&self, out: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.