FFI: Add support for OIDC login hints

bindings/matrix-sdk-ffi/src/client.rs

@@ -400,10 +400,18 @@ impl Client {
     /// * `prompt` - The desired user experience in the web UI. No value means
     ///   that the user wishes to login into an existing account, and a value of
     ///   `Create` means that the user wishes to register a new account.
+    ///
+    /// * `login_hint` - A generic login hint that an identity provider can use
+    ///   to pre-fill the login form. The format of this hint is not restricted
+    ///   by the spec as external providers all have their own way to handle the hint.
+    ///   However, it should be noted that when providing a user ID as a hint
+    ///   for MAS (with no upstream provider), then the format to use is defined
+    ///   by [MSC4198]: https://github.com/matrix-org/matrix-spec-proposals/pull/4198
     pub async fn url_for_oidc(
         &self,
         oidc_configuration: &OidcConfiguration,
         prompt: Option<OidcPrompt>,
+        login_hint: Option<String>,
     ) -> Result<Arc<OAuthAuthorizationData>, OidcError> {
         let registration_data = oidc_configuration.registration_data()?;
         let redirect_uri = oidc_configuration.redirect_uri()?;
@@ -413,6 +421,9 @@ impl Client {
         if let Some(prompt) = prompt {
             url_builder = url_builder.prompt(vec![prompt.into()]);
         }
+        if let Some(login_hint) = login_hint {
+            url_builder = url_builder.login_hint(login_hint);
+        }
 
         let data = url_builder.build().await?;
 

crates/matrix-sdk/src/authentication/oauth/auth_code_builder.rs

@@ -73,10 +73,34 @@ impl OAuthAuthCodeUrlBuilder {
         self
     }
 
+    /// Set a generic login hint to help an identity provider pre-fill the login
+    /// form.
+    ///
+    /// Note: This is not the same as the [`Self::user_id_hint()`] method, which
+    /// is specifically designed to a) take a `UserId` and no other type of
+    /// hint and b) be used directly by MAS and not the identity provider.
+    ///
+    /// The most likely use case for this method is to pre-fill the login page
+    /// using a provisioning link provided by an external party such as
+    /// `https://app.example.com/?server_name=example.org&login_hint=alice`
+    /// In this instance it is up to the external party to make ensure that the
+    /// hint is known to work with their identity provider. For more information
+    /// see `login_hint` in <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>
+    ///
+    /// The following methods are mutually exclusive: [`Self::login_hint()`] and
+    /// [`Self::user_id_hint()`].
+    pub fn login_hint(mut self, login_hint: String) -> Self {
+        self.login_hint = Some(login_hint);
+        self
+    }
+
     /// Set the hint to the Authorization Server about the Matrix user ID the
     /// End-User might use to log in, as defined in [MSC4198].
     ///
     /// [MSC4198]: https://github.com/matrix-org/matrix-spec-proposals/pull/4198
+    ///
+    /// The following methods are mutually exclusive: [`Self::login_hint()`] and
+    /// [`Self::user_id_hint()`].
     pub fn user_id_hint(mut self, user_id: &UserId) -> Self {
         self.login_hint = Some(format!("mxid:{user_id}"));
         self