mas_data_model/oauth2/
client.rs

1// Copyright 2025, 2026 Element Creations Ltd.
2// Copyright 2024, 2025 New Vector Ltd.
3// Copyright 2021-2024 The Matrix.org Foundation C.I.C.
4//
5// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
6// Please see LICENSE files in the repository root for full details.
7
8use chrono::{DateTime, Utc};
9use mas_iana::{jose::JsonWebSignatureAlg, oauth::OAuthClientAuthenticationMethod};
10use mas_jose::jwk::PublicJsonWebKeySet;
11use oauth2_types::{
12    oidc::ApplicationType,
13    registration::{ClientMetadata, Localized},
14    requests::GrantType,
15};
16use rand::RngCore;
17use serde::Serialize;
18use thiserror::Error;
19use ulid::Ulid;
20use url::Url;
21
22#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
23#[serde(rename_all = "snake_case")]
24pub enum JwksOrJwksUri {
25    /// Client's JSON Web Key Set document, passed by value.
26    Jwks(PublicJsonWebKeySet),
27
28    /// URL for the Client's JSON Web Key Set document.
29    JwksUri(Url),
30}
31
32#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
33pub struct Client {
34    pub id: Ulid,
35
36    /// Client identifier
37    pub client_id: String,
38
39    /// Hash of the client metadata
40    pub metadata_digest: Option<String>,
41
42    pub encrypted_client_secret: Option<String>,
43
44    pub application_type: Option<ApplicationType>,
45
46    /// Array of Redirection URI values used by the Client
47    pub redirect_uris: Vec<Url>,
48
49    /// Array containing a list of the OAuth 2.0 Grant Types that the Client is
50    /// declaring that it will restrict itself to using.
51    pub grant_types: Vec<GrantType>,
52
53    /// Name of the Client to be presented to the End-User
54    pub client_name: Option<String>, // TODO: translations
55
56    /// URL that references a logo for the Client application
57    pub logo_uri: Option<Url>, // TODO: translations
58
59    /// URL of the home page of the Client
60    pub client_uri: Option<Url>, // TODO: translations
61
62    /// URL that the Relying Party Client provides to the End-User to read about
63    /// the how the profile data will be used
64    pub policy_uri: Option<Url>, // TODO: translations
65
66    /// URL that the Relying Party Client provides to the End-User to read about
67    /// the Relying Party's terms of service
68    pub tos_uri: Option<Url>, // TODO: translations
69
70    pub jwks: Option<JwksOrJwksUri>,
71
72    /// JWS alg algorithm REQUIRED for signing the ID Token issued to this
73    /// Client
74    pub id_token_signed_response_alg: Option<JsonWebSignatureAlg>,
75
76    /// JWS alg algorithm REQUIRED for signing `UserInfo` Responses.
77    pub userinfo_signed_response_alg: Option<JsonWebSignatureAlg>,
78
79    /// Requested authentication method for the token endpoint
80    pub token_endpoint_auth_method: Option<OAuthClientAuthenticationMethod>,
81
82    /// JWS alg algorithm that MUST be used for signing the JWT used to
83    /// authenticate the Client at the Token Endpoint for the `private_key_jwt`
84    /// and `client_secret_jwt` authentication methods
85    pub token_endpoint_auth_signing_alg: Option<JsonWebSignatureAlg>,
86
87    /// URI using the https scheme that a third party can use to initiate a
88    /// login by the RP
89    pub initiate_login_uri: Option<Url>,
90
91    /// Whether this client is statically configured (defined in the
92    /// configuration file) rather than dynamically registered.
93    pub is_static: bool,
94}
95
96#[derive(Debug, Error)]
97pub enum InvalidRedirectUriError {
98    #[error("redirect_uri is not allowed for this client")]
99    NotAllowed,
100
101    #[error("multiple redirect_uris registered for this client")]
102    MultipleRegistered,
103
104    #[error("client has no redirect_uri registered")]
105    NoneRegistered,
106}
107
108impl Client {
109    /// Determine which redirect URI to use for the given request.
110    ///
111    /// # Errors
112    ///
113    /// Returns an error if:
114    ///
115    ///  - no URL was given but multiple redirect URIs are registered,
116    ///  - no URL was registered, or
117    ///  - the given URL is not registered
118    pub fn resolve_redirect_uri<'a>(
119        &'a self,
120        redirect_uri: &'a Option<Url>,
121    ) -> Result<&'a Url, InvalidRedirectUriError> {
122        match (&self.redirect_uris[..], redirect_uri) {
123            ([], _) => Err(InvalidRedirectUriError::NoneRegistered),
124            ([one], None) => Ok(one),
125            (_, None) => Err(InvalidRedirectUriError::MultipleRegistered),
126            (uris, Some(uri)) if uri_matches_one_of(uri, uris) => Ok(uri),
127            _ => Err(InvalidRedirectUriError::NotAllowed),
128        }
129    }
130
131    /// Create a client metadata object for this client
132    #[must_use]
133    pub fn into_metadata(self) -> ClientMetadata {
134        let (jwks, jwks_uri) = match self.jwks {
135            Some(JwksOrJwksUri::Jwks(jwks)) => (Some(jwks), None),
136            Some(JwksOrJwksUri::JwksUri(jwks_uri)) => (None, Some(jwks_uri)),
137            _ => (None, None),
138        };
139        ClientMetadata {
140            redirect_uris: Some(self.redirect_uris.clone()),
141            response_types: None,
142            grant_types: Some(self.grant_types.clone()),
143            application_type: self.application_type.clone(),
144            client_name: self.client_name.map(|n| Localized::new(n, [])),
145            logo_uri: self.logo_uri.map(|n| Localized::new(n, [])),
146            client_uri: self.client_uri.map(|n| Localized::new(n, [])),
147            policy_uri: self.policy_uri.map(|n| Localized::new(n, [])),
148            tos_uri: self.tos_uri.map(|n| Localized::new(n, [])),
149            jwks_uri,
150            jwks,
151            id_token_signed_response_alg: self.id_token_signed_response_alg,
152            userinfo_signed_response_alg: self.userinfo_signed_response_alg,
153            token_endpoint_auth_method: self.token_endpoint_auth_method,
154            token_endpoint_auth_signing_alg: self.token_endpoint_auth_signing_alg,
155            initiate_login_uri: self.initiate_login_uri,
156            contacts: None,
157            software_id: None,
158            software_version: None,
159            sector_identifier_uri: None,
160            subject_type: None,
161            id_token_encrypted_response_alg: None,
162            id_token_encrypted_response_enc: None,
163            userinfo_encrypted_response_alg: None,
164            userinfo_encrypted_response_enc: None,
165            request_object_signing_alg: None,
166            request_object_encryption_alg: None,
167            request_object_encryption_enc: None,
168            default_max_age: None,
169            require_auth_time: None,
170            default_acr_values: None,
171            request_uris: None,
172            require_signed_request_object: None,
173            require_pushed_authorization_requests: None,
174            introspection_signed_response_alg: None,
175            introspection_encrypted_response_alg: None,
176            introspection_encrypted_response_enc: None,
177            post_logout_redirect_uris: None,
178        }
179    }
180
181    #[doc(hidden)]
182    pub fn samples(now: DateTime<Utc>, rng: &mut impl RngCore) -> Vec<Client> {
183        vec![
184            // A client with all the URIs set
185            Self {
186                id: Ulid::from_datetime_with_source(now.into(), rng),
187                client_id: "client1".to_owned(),
188                metadata_digest: None,
189                encrypted_client_secret: None,
190                application_type: Some(ApplicationType::Web),
191                redirect_uris: vec![
192                    Url::parse("https://client1.example.com/redirect").unwrap(),
193                    Url::parse("https://client1.example.com/redirect2").unwrap(),
194                ],
195                grant_types: vec![GrantType::AuthorizationCode, GrantType::RefreshToken],
196                client_name: Some("Client 1".to_owned()),
197                client_uri: Some(Url::parse("https://client1.example.com").unwrap()),
198                logo_uri: Some(Url::parse("https://client1.example.com/logo.png").unwrap()),
199                tos_uri: Some(Url::parse("https://client1.example.com/tos").unwrap()),
200                policy_uri: Some(Url::parse("https://client1.example.com/policy").unwrap()),
201                initiate_login_uri: Some(
202                    Url::parse("https://client1.example.com/initiate-login").unwrap(),
203                ),
204                token_endpoint_auth_method: Some(OAuthClientAuthenticationMethod::None),
205                token_endpoint_auth_signing_alg: None,
206                id_token_signed_response_alg: None,
207                userinfo_signed_response_alg: None,
208                jwks: None,
209                is_static: false,
210            },
211            // Another client without any URIs set
212            Self {
213                id: Ulid::from_datetime_with_source(now.into(), rng),
214                client_id: "client2".to_owned(),
215                metadata_digest: None,
216                encrypted_client_secret: None,
217                application_type: Some(ApplicationType::Native),
218                redirect_uris: vec![Url::parse("https://client2.example.com/redirect").unwrap()],
219                grant_types: vec![GrantType::AuthorizationCode, GrantType::RefreshToken],
220                client_name: None,
221                client_uri: None,
222                logo_uri: None,
223                tos_uri: None,
224                policy_uri: None,
225                initiate_login_uri: None,
226                token_endpoint_auth_method: None,
227                token_endpoint_auth_signing_alg: None,
228                id_token_signed_response_alg: None,
229                userinfo_signed_response_alg: None,
230                jwks: None,
231                is_static: false,
232            },
233        ]
234    }
235}
236
237/// The hosts that match the loopback interface.
238const LOCAL_HOSTS: &[&str] = &["localhost", "127.0.0.1", "[::1]"];
239
240/// Whether the given URI matches one of the registered URIs.
241///
242/// If the URI host is one if `localhost`, `127.0.0.1` or `[::1]`, any port is
243/// accepted.
244fn uri_matches_one_of(uri: &Url, registered_uris: &[Url]) -> bool {
245    if LOCAL_HOSTS.contains(&uri.host_str().unwrap_or_default()) {
246        let mut uri = uri.clone();
247        // Try matching without the port first
248        if uri.set_port(None).is_ok() && registered_uris.contains(&uri) {
249            return true;
250        }
251    }
252
253    registered_uris.contains(uri)
254}
255
256#[cfg(test)]
257mod tests {
258    use url::Url;
259
260    use super::*;
261
262    #[test]
263    fn test_uri_matches_one_of() {
264        let registered_uris = &[
265            Url::parse("http://127.0.0.1").unwrap(),
266            Url::parse("https://example.org").unwrap(),
267        ];
268
269        // Non-loopback interface URIs.
270        assert!(uri_matches_one_of(
271            &Url::parse("https://example.org").unwrap(),
272            registered_uris
273        ));
274        assert!(!uri_matches_one_of(
275            &Url::parse("https://example.org:8080").unwrap(),
276            registered_uris
277        ));
278
279        // Loopback interface URIS.
280        assert!(uri_matches_one_of(
281            &Url::parse("http://127.0.0.1").unwrap(),
282            registered_uris
283        ));
284        assert!(uri_matches_one_of(
285            &Url::parse("http://127.0.0.1:8080").unwrap(),
286            registered_uris
287        ));
288        assert!(!uri_matches_one_of(
289            &Url::parse("http://localhost").unwrap(),
290            registered_uris
291        ));
292    }
293}
mas_data_model/oauth2/client.rs

mas_data_model/oauth2/
client.rs
