Compare commits

...
Author SHA1 Message Date
Ginger fe8314bb4d chore: Fix typo 2026-11-05 10:35:18 -05:00
Ginger 4922e5da01 feat: Add support for OAuth client credentials grant 2026-11-05 10:35:17 -05:00
9 changed files with 259 additions and 13 deletions

No files matched your search

+1
View File
@@ -0,0 +1 @@
Continuwuity now supports the OAuth 2.0 client credentials grant type, allowing secure automated access to the Matrix homeserver admin API, as well as future administrative functionality. Contributed by @ginger.
+42
View File
@@ -2680,3 +2680,45 @@
# #
# env: CONTINUWUITY_OAUTH__OIDC__PROFILE_KEY_IMPORT_MODE # env: CONTINUWUITY_OAUTH__OIDC__PROFILE_KEY_IMPORT_MODE
#profile_key_import_mode = "on_registration" #profile_key_import_mode = "on_registration"
#[global.oauth.clients."$id"]
# Use this section to add static OAuth clients for bots and automation.
# Clients added here may use the client credentials OAuth grant to authorize
# themselves with Continuwuity.
#
# Make sure to replace `$id` in the header with your client ID of choice! You can
# add more copies of this section with different IDs to add multiple clients.
#
# Because the client credentials grant authorizes the client as itself, without
# an attached user, clients that use it will not be able to access most of the Matrix
# client-server API. Administrative functionality that does not require a user
# will still be available.
# The client's client secret.
#
# This must be supplied as the `client_secret` parameter when requesting
# an access token with the OAuth 2.0 token endpoint. Continuwuity does
# not check the `Authorization` header for requests to this endpoint.
#
#client_secret =
# A list of scopes that the client may request. Continuwuity allows static
# clients to request the following scopes:
#
# - "urn:matrix:client:cc.c10y.msc4484.server_administration" (MSC4484):
# This scope grants access to the Matrix server administration APIs, as
# well as Continuwuity's internal admin API (currently a work in
# progress).
# - "urn:matrix:client:api:*": This scope grants access to the Matrix
# client-server API. Most endpoints require an authenticated Matrix user
# and thus will not be usable by static clients.
#
# The `urn:matrix:client:device:<id>` scope may not be requested by static
# clients.
#
# Scopes listed here are not granted by default. The client must
# explicitly include them in the `scope` parameter of its access token
# request.
#
#scopes = []
+1 -1
View File
@@ -61,7 +61,7 @@ pub(crate) async fn authorization_server_metadata(services: &Services) -> Value
"authorization_endpoint": endpoint_base.join(AUTH_CODE_PATH).unwrap(), "authorization_endpoint": endpoint_base.join(AUTH_CODE_PATH).unwrap(),
"code_challenge_methods_supported": ["S256"], "code_challenge_methods_supported": ["S256"],
"device_authorization_endpoint": endpoint_base.join(DEVICE_AUTHORIZATION_PATH).unwrap(), "device_authorization_endpoint": endpoint_base.join(DEVICE_AUTHORIZATION_PATH).unwrap(),
"grant_types_supported": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code"], "grant_types_supported": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code", "client_credentials"],
"issuer": services.config.get_client_domain(), "issuer": services.config.get_client_domain(),
"jwks_uri": endpoint_base.join(JWKS_URI_PATH).unwrap(), "jwks_uri": endpoint_base.join(JWKS_URI_PATH).unwrap(),
"prompt_values_supported": prompt_values_supported, "prompt_values_supported": prompt_values_supported,
+25 -1
View File
@@ -41,6 +41,7 @@ pub(crate) enum ClientIdentity {
sender_device: Option<OwnedDeviceId>, sender_device: Option<OwnedDeviceId>,
appservice_info: Box<RegistrationInfo>, appservice_info: Box<RegistrationInfo>,
}, },
StaticClient,
} }
impl ClientIdentity { impl ClientIdentity {
@@ -48,6 +49,7 @@ impl ClientIdentity {
match self { match self {
| Self::User { sender_user, .. } | Self::Appservice { sender_user, .. } => | Self::User { sender_user, .. } | Self::Appservice { sender_user, .. } =>
Some(sender_user), Some(sender_user),
| Self::StaticClient => None,
} }
} }
@@ -55,6 +57,8 @@ impl ClientIdentity {
match self { match self {
| Self::User { sender_user, .. } | Self::Appservice { sender_user, .. } => | Self::User { sender_user, .. } | Self::Appservice { sender_user, .. } =>
Ok(sender_user), Ok(sender_user),
| Self::StaticClient =>
Err!(Request(Forbidden("Static clients cannot use this endpoint."))),
} }
} }
@@ -62,6 +66,7 @@ impl ClientIdentity {
match self { match self {
| Self::User { sender_device, .. } => Some(sender_device), | Self::User { sender_device, .. } => Some(sender_device),
| Self::Appservice { sender_device, .. } => sender_device.as_deref(), | Self::Appservice { sender_device, .. } => sender_device.as_deref(),
| Self::StaticClient => None,
} }
} }
@@ -71,12 +76,14 @@ impl ClientIdentity {
| Self::Appservice { sender_device: Some(sender_device), .. } => Ok(sender_device), | Self::Appservice { sender_device: Some(sender_device), .. } => Ok(sender_device),
| Self::Appservice { sender_device: None, .. } => | Self::Appservice { sender_device: None, .. } =>
Err!(Request(Forbidden("Appservices must masquerade to use this endpoint."))), Err!(Request(Forbidden("Appservices must masquerade to use this endpoint."))),
| Self::StaticClient =>
Err!(Request(Forbidden("Static clients cannot use this endpoint."))),
} }
} }
pub(crate) fn appservice_info(&self) -> Option<&RegistrationInfo> { pub(crate) fn appservice_info(&self) -> Option<&RegistrationInfo> {
match self { match self {
| Self::User { .. } => None, | Self::User { .. } | Self::StaticClient => None,
| Self::Appservice { appservice_info, .. } => Some(appservice_info), | Self::Appservice { appservice_info, .. } => Some(appservice_info),
} }
} }
@@ -392,6 +399,23 @@ async fn check_access_token(
sender_device, sender_device,
appservice_info: Box::new(appservice_info), appservice_info: Box::new(appservice_info),
}) })
} else if let Some(session) = services.oauth.get_client_credentials_session(token).await {
if !required_scopes
.iter()
.any(|scope| session.scopes.contains(scope))
{
return Err(Error::Request(
ErrorKind::InsufficientUserAuthentication(Box::new(
assign!(InsufficientUserAuthenticationErrorData::new(), {
scope: required_scopes.iter().cloned().collect()
}),
)),
"You do not have permission to access this endpoint.".into(),
StatusCode::UNAUTHORIZED,
));
}
Ok(ClientIdentity::StaticClient)
} else { } else {
Err(Error::Request( Err(Error::Request(
ErrorKind::UnknownToken(UnknownTokenErrorData::new()), ErrorKind::UnknownToken(UnknownTokenErrorData::new()),
+9
View File
@@ -353,6 +353,15 @@ pub fn check(config: &Config) -> Result {
} }
})?; })?;
for (id, client) in &config.oauth.clients {
if client.scopes.is_empty() {
warn!(
"The static OAuth client `{id}` has no scopes configured. It will not be able \
to access any API endpoints."
);
}
}
Ok(()) Ok(())
} }
+54
View File
@@ -24,6 +24,7 @@ use ruma::{
OwnedRoomId, OwnedRoomOrAliasId, OwnedServerName, OwnedServerSigningKeyId, OwnedUserId, OwnedRoomId, OwnedRoomOrAliasId, OwnedServerName, OwnedServerSigningKeyId, OwnedUserId,
RoomVersionId, ServerName, RoomVersionId, ServerName,
api::{ api::{
OAuthClientScope,
client::{discovery::discover_support::ContactRole, rtc::RtcTransport}, client::{discovery::discover_support::ContactRole, rtc::RtcTransport},
federation::discovery::OldVerifyKey, federation::discovery::OldVerifyKey,
}, },
@@ -2746,7 +2747,12 @@ pub struct OauthConfig {
compatibility_mode: OAuthMode, compatibility_mode: OAuthMode,
/// display: hidden /// display: hidden
#[serde(default)]
pub oidc: Option<OidcConfig>, pub oidc: Option<OidcConfig>,
/// display: hidden
#[serde(default)]
pub clients: HashMap<String, OAuthClient>,
} }
impl OauthConfig { impl OauthConfig {
@@ -2960,6 +2966,54 @@ impl TrustedServerConfig {
} }
} }
#[derive(Clone, Debug, Deserialize)]
#[config_example_generator(
filename = "conduwuit-example.toml",
section = "global.oauth.clients.\"$id\"",
optional = "true",
subheader = "\
# Use this section to add static OAuth clients for bots and automation.
# Clients added here may use the client credentials OAuth grant to authorize
# themselves with Continuwuity.
#
# Make sure to replace `$id` in the header with your client ID of choice! You can
# add more copies of this section with different IDs to add multiple clients.
#
# Because the client credentials grant authorizes the client as itself, without
# an attached user, clients that use it will not be able to access most of the Matrix
# client-server API. Administrative functionality that does not require a user
# will still be available."
)]
pub struct OAuthClient {
/// The client's client secret.
///
/// This must be supplied as the `client_secret` parameter when requesting
/// an access token with the OAuth 2.0 token endpoint. Continuwuity does
/// not check the `Authorization` header for requests to this endpoint.
pub client_secret: String,
/// A list of scopes that the client may request. Continuwuity allows static
/// clients to request the following scopes:
///
/// - "urn:matrix:client:cc.c10y.msc4484.server_administration" (MSC4484):
/// This scope grants access to the Matrix server administration APIs, as
/// well as Continuwuity's internal admin API (currently a work in
/// progress).
/// - "urn:matrix:client:api:*": This scope grants access to the Matrix
/// client-server API. Most endpoints require an authenticated Matrix user
/// and thus will not be usable by static clients.
///
/// The `urn:matrix:client:device:<id>` scope may not be requested by static
/// clients.
///
/// Scopes listed here are not granted by default. The client must
/// explicitly include them in the `scope` parameter of its access token
/// request.
///
/// default: []
pub scopes: BTreeSet<OAuthClientScope>,
}
const DEPRECATED_KEYS: &[&str] = &[ const DEPRECATED_KEYS: &[&str] = &[
"cache_capacity", "cache_capacity",
"conduit_cache_capacity_modifier", "conduit_cache_capacity_modifier",
+7
View File
@@ -125,6 +125,12 @@ impl ClientMetadata {
} }
} }
if self.grant_types.contains(&GrantType::ClientCredentials) {
return Err(
"Dynamically registered clients may not use the client credentials grant."
);
}
Ok(()) Ok(())
} }
} }
@@ -144,6 +150,7 @@ pub enum GrantType {
#[serde(rename = "urn:ietf:params:oauth:grant-type:device_code")] #[serde(rename = "urn:ietf:params:oauth:grant-type:device_code")]
DeviceCode, DeviceCode,
RefreshToken, RefreshToken,
ClientCredentials,
} }
#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Deserialize, Serialize)] #[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Deserialize, Serialize)]
+6 -1
View File
@@ -225,6 +225,10 @@ pub enum TokenRequestType {
RefreshToken { RefreshToken {
refresh_token: String, refresh_token: String,
}, },
ClientCredentials {
client_secret: String,
scope: RawScopes,
},
} }
impl TokenRequestType { impl TokenRequestType {
@@ -234,6 +238,7 @@ impl TokenRequestType {
| Self::AuthorizationCode { .. } => GrantType::AuthorizationCode, | Self::AuthorizationCode { .. } => GrantType::AuthorizationCode,
| Self::DeviceCode { .. } => GrantType::DeviceCode, | Self::DeviceCode { .. } => GrantType::DeviceCode,
| Self::RefreshToken { .. } => GrantType::RefreshToken, | Self::RefreshToken { .. } => GrantType::RefreshToken,
| Self::ClientCredentials { .. } => GrantType::ClientCredentials,
} }
} }
} }
@@ -243,7 +248,7 @@ pub struct TokenResponse {
pub access_token: String, pub access_token: String,
pub token_type: TokenType, pub token_type: TokenType,
pub expires_in: u64, pub expires_in: u64,
pub refresh_token: String, pub refresh_token: Option<String>,
pub scope: String, pub scope: String,
} }
+114 -10
View File
@@ -23,8 +23,9 @@ use crate::{
client_metadata::{ApplicationType, ClientMetadata, GrantType, ResponseType}, client_metadata::{ApplicationType, ClientMetadata, GrantType, ResponseType},
grant::{ grant::{
AuthorizationCodeQuery, AuthorizationCodeResponse, CodeChallengeMethod, AuthorizationCodeQuery, AuthorizationCodeResponse, CodeChallengeMethod,
DeviceCodeRequest, DeviceCodeResponse, ErrorCode, OAuthError, RequestedScopes, DeviceCodeRequest, DeviceCodeResponse, ErrorCode, OAuthError, RawScopes,
ResponseMode, TokenRequest, TokenRequestType, TokenResponse, TokenType, RequestedScopes, ResponseMode, TokenRequest, TokenRequestType, TokenResponse,
TokenType,
}, },
}, },
users::{self, DeviceToken}, users::{self, DeviceToken},
@@ -39,6 +40,7 @@ pub struct Service {
tickets: SyncMutex<HashMap<String, HashMap<OAuthTicket, SystemTime>>>, tickets: SyncMutex<HashMap<String, HashMap<OAuthTicket, SystemTime>>>,
pending_auth_code_grants: SyncMutex<LruCache<String, PendingAuthCodeGrant>>, pending_auth_code_grants: SyncMutex<LruCache<String, PendingAuthCodeGrant>>,
pending_device_code_grants: SyncMutex<LruCache<String, PendingDeviceCodeGrant>>, pending_device_code_grants: SyncMutex<LruCache<String, PendingDeviceCodeGrant>>,
client_credential_sessions: tokio::sync::Mutex<HashMap<String, ClientCredentialsSession>>,
} }
struct Data { struct Data {
@@ -78,6 +80,12 @@ struct RefreshTokenInfo {
device_id: OwnedDeviceId, device_id: OwnedDeviceId,
} }
pub struct ClientCredentialsSession {
pub client_id: String,
pub scopes: BTreeSet<OAuthClientScope>,
created_at: SystemTime,
}
struct PendingAuthCodeGrant { struct PendingAuthCodeGrant {
authorizing_user: OwnedUserId, authorizing_user: OwnedUserId,
requested_scopes: RequestedScopes, requested_scopes: RequestedScopes,
@@ -172,6 +180,7 @@ impl crate::Service for Service {
tickets: SyncMutex::default(), tickets: SyncMutex::default(),
pending_auth_code_grants: SyncMutex::new(LruCache::new(Self::MAX_PENDING_GRANTS)), pending_auth_code_grants: SyncMutex::new(LruCache::new(Self::MAX_PENDING_GRANTS)),
pending_device_code_grants: SyncMutex::new(LruCache::new(Self::MAX_PENDING_GRANTS)), pending_device_code_grants: SyncMutex::new(LruCache::new(Self::MAX_PENDING_GRANTS)),
client_credential_sessions: tokio::sync::Mutex::default(),
})) }))
} }
@@ -448,12 +457,25 @@ impl Service {
pub async fn issue_token(&self, request: TokenRequest) -> Result<TokenResponse, OAuthError> { pub async fn issue_token(&self, request: TokenRequest) -> Result<TokenResponse, OAuthError> {
let TokenRequest { client_id, request } = request; let TokenRequest { client_id, request } = request;
let Some(client_metadata) = self.get_client_metadata(&client_id).await else { if !matches!(request, TokenRequestType::ClientCredentials { .. }) {
return Err(OAuthError::new_static(ErrorCode::InvalidClient, "Invalid client ID")); // The client credentials grant can only be used by statically
}; // registered clients, and the other grant types can
// only be used by dynamically registered clients, so we
// don't look up the dynamic client metadata if the token request is
// for the client credentials grant.
if !client_metadata.grant_types.contains(&request.grant_type()) { let Some(client_metadata) = self.get_client_metadata(&client_id).await else {
return Err(OAuthError::unauthorized_client("Client cannot request this grant type")); return Err(OAuthError::new_static(
ErrorCode::InvalidClient,
"Invalid client ID",
));
};
if !client_metadata.grant_types.contains(&request.grant_type()) {
return Err(OAuthError::unauthorized_client(
"Client cannot request this grant type",
));
}
} }
match request { match request {
@@ -525,6 +547,9 @@ impl Service {
}, },
| TokenRequestType::RefreshToken { refresh_token } => | TokenRequestType::RefreshToken { refresh_token } =>
self.refresh_session(client_id, refresh_token).await, self.refresh_session(client_id, refresh_token).await,
| TokenRequestType::ClientCredentials { client_secret, scope: scopes } =>
self.create_client_credentials_token(&client_id, &client_secret, scopes)
.await,
} }
} }
@@ -542,7 +567,7 @@ impl Service {
{ {
(user_id, device_id) (user_id, device_id)
} else { } else {
return Err(OAuthError::invalid_grant("Invalid access or refersh token")); return Err(OAuthError::invalid_grant("Invalid access or refresh token"));
}; };
// This will also call [`Self::remove_session`] // This will also call [`Self::remove_session`]
@@ -668,7 +693,7 @@ impl Service {
token_type: TokenType::Bearer, token_type: TokenType::Bearer,
expires_in: Self::ACCESS_TOKEN_MAX_AGE.as_secs(), expires_in: Self::ACCESS_TOKEN_MAX_AGE.as_secs(),
scope: response_scope, scope: response_scope,
refresh_token, refresh_token: Some(refresh_token),
}) })
} }
@@ -738,10 +763,89 @@ impl Service {
token_type: TokenType::Bearer, token_type: TokenType::Bearer,
expires_in: Self::ACCESS_TOKEN_MAX_AGE.as_secs(), expires_in: Self::ACCESS_TOKEN_MAX_AGE.as_secs(),
scope, scope,
refresh_token: new_refresh_token, refresh_token: Some(new_refresh_token),
}) })
} }
async fn create_client_credentials_token(
&self,
client_id: &str,
client_secret: &str,
scopes: RawScopes,
) -> Result<TokenResponse, OAuthError> {
let now = SystemTime::now();
let Some(client) = self.services.config.oauth.clients.get(client_id) else {
return Err(OAuthError::new_static(ErrorCode::InvalidClient, "Unknown client ID"));
};
let RequestedScopes { device_id, scopes } = scopes
.to_scopes()
.map_err(|err| OAuthError::new(ErrorCode::InvalidGrant, err))?;
if device_id.is_some() {
return Err(OAuthError::new_static(
ErrorCode::InvalidGrant,
"Static clients may not request a device ID",
));
}
if client_secret != client.client_secret {
return Err(OAuthError::new_static(
ErrorCode::InvalidClient,
"Client secret does not match",
));
}
if !scopes.is_subset(&client.scopes) {
return Err(OAuthError::new_static(
ErrorCode::InvalidScope,
"This client may not request those scopes",
));
}
let mut sessions = self.client_credential_sessions.lock().await;
// Clear expired sessions while we're at it
sessions.retain(|_, session| {
now.duration_since(session.created_at)
.is_ok_and(|age| age <= Self::ACCESS_TOKEN_MAX_AGE)
});
let access_token = Self::generate_token();
let scope = scopes.iter().join(" ");
sessions.insert(access_token.clone(), ClientCredentialsSession {
client_id: client_id.to_owned(),
scopes,
created_at: now,
});
Ok(TokenResponse {
access_token,
token_type: TokenType::Bearer,
expires_in: Self::ACCESS_TOKEN_MAX_AGE.as_secs(),
refresh_token: None,
scope,
})
}
pub async fn get_client_credentials_session(
&self,
token: &str,
) -> Option<tokio::sync::MappedMutexGuard<'_, ClientCredentialsSession>> {
let sessions = self.client_credential_sessions.lock().await;
tokio::sync::MutexGuard::try_map(sessions, |sessions| {
sessions.get_mut(token).filter(|session| {
SystemTime::now()
.duration_since(session.created_at)
.is_ok_and(|age| age <= Self::ACCESS_TOKEN_MAX_AGE)
})
})
.ok()
}
pub async fn remove_session(&self, user_id: &UserId, device_id: &DeviceId) { pub async fn remove_session(&self, user_id: &UserId, device_id: &DeviceId) {
let session_info = self.get_session_info_for_device(user_id, device_id).await; let session_info = self.get_session_info_for_device(user_id, device_id).await;