Tweak some identity_provider example config doc comments.

Signed-off-by: Jason Volk <jason@zemos.net>

src/core/config/mod.rs

@@ -2549,6 +2549,15 @@ pub struct IdentityProvider {
 	/// example: "/etc/tuwunel/.client_secret"
 	pub client_secret_file: Option<PathBuf>,
 
+	/// 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.
+	pub issuer_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
@@ -2592,31 +2601,25 @@ pub struct IdentityProvider {
 	#[serde(default)]
 	pub scope: BTreeSet<String>,
 
-	/// List of userinfo claims which shape and restrict the way we compute a
+	/// Optional list of userinfo claims which shape and restrict the way we
-	/// Matrix UserId for new registrations. Reviewing Tuwunel's documentation
+	/// compute a Matrix UserId for new registrations. Reviewing Tuwunel's
-	/// will be necessary for a complete description in detail. An empty array
+	/// documentation will be necessary for a complete description in detail. An
-	/// imposes no restriction here, avoiding generated fallbacks as much as
+	/// empty array imposes no restriction here, avoiding generated fallbacks as
-	/// possible. For simplicity we reserve a claim called "unique" which can be
+	/// much as possible. For simplicity we reserve a claim called "unique"
-	/// listed alone to ensure *only* generated ID's are used for registrations.
+	/// which can be listed alone to ensure *only* generated ID's are used for
+	/// registrations.
 	///
 	/// default: []
 	#[serde(default)]
 	pub userid_claims: BTreeSet<String>,
 
-	/// Issuer URL the provider publishes for you. We have pre-supplied default
+	/// Optional extra path components after the issuer_url leading to the
-	/// values for some of the canonical providers, making this field optional
+	/// location of the `.well-known` directory used for discovery. This will be
-	/// based on the `brand` set above. Otherwise it is required for OIDC
+	/// empty for specification-compliant providers. We have supplied any known
-	/// discovery to acquire additional provider configuration, and it must be
+	/// values based on `brand` (e.g. `/login/oauth` for GitHub).
-	/// correct to pass validations during various interactions.
-	pub issuer_url: Option<Url>,
-
-	/// Extra path components after the issuer_url leading to the location of
-	/// the `.well-known` directory used for discovery. This will be empty for
-	/// specification-compliant providers. We have supplied any known values
-	/// based on `brand` (e.g. `/login/oauth` for GitHub).
 	pub base_path: Option<String>,
 
-	/// Overrides the `.well-known` location where the provider's OIDC
+	/// 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.
 	pub discovery_url: Option<Url>,

src/service/oauth/sessions.rs

@@ -170,7 +170,7 @@ pub async fn put(&self, sess_id: &str, session: &Session) {
 	}
 }
 
-/// Fetch database state for a session from its associated `sub`, in case
+/// Fetch database state for a session from its associated `(iss,sub)`, in case
 /// `sess_id` is not known.
 #[implement(Sessions)]
 #[tracing::instrument(level = "debug", skip(self), ret(level = "debug"))]
@@ -213,7 +213,7 @@ pub async fn get_sess_id_by_user(&self, user_id: &UserId) -> Result<String> {
 		.deserialized()
 }
 
-/// Resolve the `sess_id` from an associated provider subject id.
+/// Resolve the `sess_id` from an associated provider issuer and subject hash.
 #[implement(Sessions)]
 #[tracing::instrument(level = "debug", skip(self), ret(level = "debug"))]
 pub async fn get_sess_id_by_unique_id(&self, unique_id: &str) -> Result<String> {

tuwunel-example.toml

@@ -2168,6 +2168,16 @@
 #
 #client_secret_file =
 
+# 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.
+#
+#issuer_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
@@ -2212,31 +2222,24 @@
 #
 #scope = []
 
-# List of userinfo claims which shape and restrict the way we compute a
+# Optional list of userinfo claims which shape and restrict the way we
-# Matrix UserId for new registrations. Reviewing Tuwunel's documentation
+# compute a Matrix UserId for new registrations. Reviewing Tuwunel's
-# will be necessary for a complete description in detail. An empty array
+# documentation will be necessary for a complete description in detail. An
-# imposes no restriction here, avoiding generated fallbacks as much as
+# empty array imposes no restriction here, avoiding generated fallbacks as
-# possible. For simplicity we reserve a claim called "unique" which can be
+# much as possible. For simplicity we reserve a claim called "unique"
-# listed alone to ensure *only* generated ID's are used for registrations.
+# which can be listed alone to ensure *only* generated ID's are used for
+# registrations.
 #
 #userid_claims = []
 
-# Issuer URL the provider publishes for you. We have pre-supplied default
+# Optional extra path components after the issuer_url leading to the
-# values for some of the canonical providers, making this field optional
+# location of the `.well-known` directory used for discovery. This will be
-# based on the `brand` set above. Otherwise it is required for OIDC
+# empty for specification-compliant providers. We have supplied any known
-# discovery to acquire additional provider configuration, and it must be
+# values based on `brand` (e.g. `/login/oauth` for GitHub).
-# correct to pass validations during various interactions.
-#
-#issuer_url =
-
-# Extra path components after the issuer_url leading to the location of
-# the `.well-known` directory used for discovery. This will be empty for
-# specification-compliant providers. We have supplied any known values
-# based on `brand` (e.g. `/login/oauth` for GitHub).
 #
 #base_path =
 
-# Overrides the `.well-known` location where the provider's OIDC
+# 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.
 #