Skip to main content

tuwunel_service/oauth/
mod.rs

1pub mod providers;
2pub mod server;
3pub mod sessions;
4pub mod token_response;
5pub mod user_info;
6
7use std::{
8	collections::HashMap,
9	net::IpAddr,
10	sync::{Arc, Mutex},
11	time::Instant,
12};
13
14use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD as b64encode};
15use futures::{Stream, StreamExt, TryStreamExt};
16use http::StatusCode;
17use reqwest::{
18	Method,
19	header::{ACCEPT, CONTENT_TYPE},
20};
21use ruma::{
22	UserId,
23	api::error::{ErrorKind, LimitExceededErrorData},
24};
25use serde::Serialize;
26use serde_json::Value as JsonValue;
27use tuwunel_core::{
28	Err, Error, Result, err, implement,
29	smallstr::SmallString,
30	utils::{
31		hash::sha256,
32		result::{LogErr, NotFound},
33		stream::{ReadyExt, TryReadyExt},
34		string::truncate_deterministic,
35	},
36	warn,
37};
38use url::Url;
39
40use self::{providers::Providers, sessions::Sessions};
41pub use self::{
42	providers::{Provider, ProviderId},
43	server::Server,
44	sessions::{CODE_VERIFIER_LENGTH, Deleted, Deletions, SESSION_ID_LENGTH, Session, SessionId},
45	token_response::TokenResponse,
46	user_info::UserInfo,
47};
48use crate::{SelfServices, client::read_response_capped};
49
50/// Fallback localpart derived from an identity's unique-id string.
51pub type Localpart = SmallString<[u8; 23]>;
52
53/// Per-client-IP token-bucket table: last-refill instant and remaining tokens.
54type Ratelimiter = Mutex<HashMap<IpAddr, (Instant, f64)>>;
55
56pub struct Service {
57	services: SelfServices,
58	pub providers: Arc<Providers>,
59	pub sessions: Arc<Sessions>,
60	pub server: Option<Arc<Server>>,
61	ratelimiter: Ratelimiter,
62	device_ratelimiter: Ratelimiter,
63}
64
65impl crate::Service for Service {
66	fn build(args: &crate::Args<'_>) -> Result<Arc<Self>> {
67		let providers = Arc::new(Providers::build(args));
68		let sessions = Arc::new(Sessions::build(args, providers.clone()));
69		let server = Server::build(args)?.map(Arc::new);
70
71		Ok(Arc::new(Self {
72			services: args.services.clone(),
73			sessions,
74			providers,
75			server,
76			ratelimiter: Mutex::new(HashMap::new()),
77			device_ratelimiter: Mutex::new(HashMap::new()),
78		}))
79	}
80
81	fn name(&self) -> &str { crate::service::make_name(std::module_path!()) }
82}
83
84#[implement(Service)]
85#[inline]
86pub fn get_server(&self) -> Result<&Server> {
87	self.server
88		.as_deref()
89		.ok_or_else(|| err!(Request(Unrecognized("OIDC server not configured"))))
90}
91
92/// Cap on the rate-limit table; fully refilled buckets are pruned past it.
93const RATELIMIT_MAP_CAP: usize = 1 << 16;
94
95#[cfg(test)]
96mod tests;
97
98/// Always-on throttle for the RFC 8628 device user-code endpoints. The
99/// `user_code` is low-entropy by design (§6.1), so §5.1 requires bounding
100/// guesses regardless of the optional `oidc_rc_*` knobs; the burst stays
101/// generous for the one code a real user enters.
102const DEVICE_RC_PER_SECOND: f64 = 1.0;
103/// Generous allowance for the one code a real user enters.
104const DEVICE_RC_BURST: f64 = 60.0;
105
106/// Shared per-client-IP token-bucket throttle for the OIDC endpoints.
107///
108/// A no-op unless both `authentication.oidc.rc_per_second` and
109/// `authentication.oidc.rc_burst_count` are configured.
110#[implement(Service)]
111pub fn check_rate_limit(&self, client: IpAddr) -> Result {
112	let config = &self.services.config;
113	let rate = f64::from(config.authentication.oidc.rc_per_second);
114	let burst = f64::from(config.authentication.oidc.rc_burst_count);
115
116	if rate <= 0.0 || burst <= 0.0 {
117		return Ok(());
118	}
119
120	check_bucket(&self.ratelimiter, client, rate, burst)
121}
122
123/// Always-on anti-brute-force throttle for the device user-code endpoints
124/// (RFC 8628 §5.1), independent of the optional `oidc_rc_*` knobs.
125#[implement(Service)]
126pub fn check_device_rate_limit(&self, client: IpAddr) -> Result {
127	check_bucket(&self.device_ratelimiter, client, DEVICE_RC_PER_SECOND, DEVICE_RC_BURST)
128}
129
130fn check_bucket(table: &Ratelimiter, client: IpAddr, rate: f64, burst: f64) -> Result {
131	check_bucket_at(table, client, rate, burst, Instant::now(), RATELIMIT_MAP_CAP)
132}
133
134fn check_bucket_at(
135	table: &Ratelimiter,
136	client: IpAddr,
137	rate: f64,
138	burst: f64,
139	now: Instant,
140	cap: usize,
141) -> Result {
142	let mut buckets = table.lock()?;
143	debug_assert!(cap > 0, "rate-limit table cap must be positive");
144	debug_assert!(buckets.len() <= cap, "rate-limit table exceeded its cap");
145
146	if buckets.len() >= cap && !buckets.contains_key(&client) {
147		let mut oldest = None;
148
149		buckets.retain(|client, bucket| {
150			let (last_time, tokens) = *bucket;
151			let refilled = now
152				.duration_since(last_time)
153				.as_secs_f64()
154				.mul_add(rate, tokens);
155
156			let retain = refilled < burst;
157
158			if retain && oldest.is_none_or(|(_, oldest_at)| last_time < oldest_at) {
159				oldest = Some((*client, last_time));
160			}
161
162			retain
163		});
164
165		if buckets.len() >= cap
166			&& let Some((oldest, _)) = oldest
167		{
168			buckets.remove(&oldest);
169		}
170	}
171
172	let (last_time, tokens) = buckets
173		.entry(client)
174		.or_insert_with(|| (now, burst));
175
176	let new_tokens = now
177		.duration_since(*last_time)
178		.as_secs_f64()
179		.mul_add(rate, *tokens)
180		.min(burst);
181
182	if new_tokens < 1.0 {
183		return Err(Error::Request(
184			ErrorKind::LimitExceeded(LimitExceededErrorData { retry_after: None }),
185			"Too many OIDC requests.".into(),
186			StatusCode::TOO_MANY_REQUESTS,
187		));
188	}
189
190	*last_time = now;
191	*tokens = new_tokens - 1.0;
192
193	Ok(())
194}
195
196/// Remove every session listed under a user.
197///
198/// Each listed session is deleted whether or not its provider still resolves,
199/// and one that cannot be read is kept; the result counts each outcome, and an
200/// unreadable list is an error. For debug and developer use only; deleting
201/// state can cause registration conflicts and unintended re-registrations.
202#[implement(Service)]
203#[tracing::instrument(level = "debug", skip(self))]
204pub async fn delete_user_sessions(&self, user_id: &UserId) -> Result<Deletions> {
205	self.sessions
206		.get_sess_id_by_user(user_id)
207		// A user with no sessions has no index row to list them.
208		.ready_filter(|listed| !listed.is_missing())
209		.and_then(async |sess_id| Ok((self.sessions.delete(&sess_id).await, sess_id)))
210		.ready_try_fold_default(|deletions: Deletions, (deleted, sess_id)| {
211			Ok(deletions.tally(deleted, &sess_id))
212		})
213		.await
214}
215
216/// Revoke all session tokens for a user.
217#[implement(Service)]
218#[tracing::instrument(level = "debug", skip(self))]
219pub async fn revoke_user_tokens(&self, user_id: &UserId) {
220	self.user_sessions(user_id)
221		.ready_filter_map(Result::ok)
222		.for_each(async |(provider, session)| {
223			self.revoke_token((&provider, &session))
224				.await
225				.log_err()
226				.ok();
227		})
228		.await;
229}
230
231/// Get user's authorizations. Lists pairs of `(Provider, Session)` for a user.
232#[implement(Service)]
233#[tracing::instrument(level = "debug", skip(self))]
234pub fn user_sessions(
235	&self,
236	user_id: &UserId,
237) -> impl Stream<Item = Result<(Provider, Session)>> + Send {
238	self.sessions
239		.get_by_user(user_id)
240		.and_then(async |session| Ok((self.sessions.provider(&session).await?, session)))
241}
242
243/// Network request to a Provider returning userinfo for a Session. The session
244/// must have a valid access token.
245#[implement(Service)]
246#[tracing::instrument(level = "debug", skip_all, ret)]
247pub async fn request_userinfo(
248	&self,
249	(provider, session): (&Provider, &Session),
250) -> Result<UserInfo> {
251	#[derive(Debug, Serialize)]
252	struct Query;
253
254	let url = provider
255		.userinfo_url
256		.clone()
257		.ok_or_else(|| err!(Config("userinfo_url", "Missing userinfo URL in config")))?;
258
259	self.request((Some(provider), Some(session)), Method::GET, url, Option::<Query>::None)
260		.await
261		.and_then(|value| serde_json::from_value(value).map_err(Into::into))
262		.log_err()
263}
264
265/// Network request to a Provider returning information for a Session based on
266/// its access token.
267#[implement(Service)]
268#[tracing::instrument(level = "debug", skip_all, ret)]
269pub async fn request_tokeninfo(
270	&self,
271	(provider, session): (&Provider, &Session),
272) -> Result<UserInfo> {
273	#[derive(Debug, Serialize)]
274	struct Query;
275
276	let url = provider
277		.introspection_url
278		.clone()
279		.ok_or_else(|| {
280			err!(Config("introspection_url", "Missing introspection URL in config"))
281		})?;
282
283	self.request((Some(provider), Some(session)), Method::GET, url, Option::<Query>::None)
284		.await
285		.and_then(|value| serde_json::from_value(value).map_err(Into::into))
286		.log_err()
287}
288
289/// Network request to a Provider revoking a Session's token.
290#[implement(Service)]
291#[tracing::instrument(level = "debug", skip_all, ret)]
292pub async fn revoke_token(&self, (provider, session): (&Provider, &Session)) -> Result {
293	#[derive(Debug, Serialize)]
294	struct RevokeQuery<'a> {
295		client_id: &'a str,
296		client_secret: &'a str,
297	}
298
299	let client_secret = provider.get_client_secret().await?;
300
301	let query = RevokeQuery {
302		client_id: &provider.client_id,
303		client_secret: &client_secret,
304	};
305
306	let url = provider
307		.revocation_url
308		.clone()
309		.ok_or_else(|| err!(Config("revocation_url", "Missing revocation URL in config")))?;
310
311	self.request((Some(provider), Some(session)), Method::POST, url, Some(query))
312		.await
313		.log_err()
314		.map(|_| ())
315}
316
317/// Network request to a Provider to obtain an access token for a Session using
318/// a provided code.
319#[implement(Service)]
320#[tracing::instrument(level = "debug", skip_all, ret)]
321pub async fn request_token(
322	&self,
323	(provider, session): (&Provider, &Session),
324	code: &str,
325) -> Result<TokenResponse> {
326	#[derive(Debug, Serialize)]
327	struct TokenQuery<'a> {
328		client_id: &'a str,
329		client_secret: &'a str,
330		grant_type: &'a str,
331		code: &'a str,
332		code_verifier: Option<&'a str>,
333		redirect_uri: Option<&'a str>,
334	}
335
336	let client_secret = provider.get_client_secret().await?;
337
338	let query = TokenQuery {
339		client_id: &provider.client_id,
340		client_secret: &client_secret,
341		grant_type: "authorization_code",
342		code,
343		code_verifier: session.code_verifier.as_deref(),
344		redirect_uri: provider.callback_url.as_ref().map(Url::as_str),
345	};
346
347	let url = provider
348		.token_url
349		.clone()
350		.ok_or_else(|| err!(Config("token_url", "Missing token URL in config")))?;
351
352	self.request((Some(provider), Some(session)), Method::POST, url, Some(query))
353		.await
354		.and_then(|value| serde_json::from_value(value).map_err(Into::into))
355		.log_err()
356}
357
358/// Send a request to a provider; this is somewhat abstract since URL's are
359/// formed prior to this call and could point at anything, however this function
360/// uses the oauth-specific http client and is configured for JSON with special
361/// casing for an `error` property in the response.
362#[implement(Service)]
363#[tracing::instrument(name = "request", level = "debug", skip(self, body))]
364pub async fn request<Body>(
365	&self,
366	(provider, session): (Option<&Provider>, Option<&Session>),
367	method: Method,
368	url: Url,
369	body: Option<Body>,
370) -> Result<JsonValue>
371where
372	Body: Serialize,
373{
374	let mut request = self
375		.services
376		.client
377		.oauth
378		.request(method, url)
379		.header(ACCEPT, "application/json");
380
381	if let Some(body) = body.map(serde_html_form::to_string).transpose()? {
382		request = request
383			.header(CONTENT_TYPE, "application/x-www-form-urlencoded")
384			.body(body);
385	}
386
387	if let Some(session) = session
388		&& let Some(access_token) = session.access_token.clone()
389	{
390		request = request.bearer_auth(access_token);
391	}
392
393	let limit = self
394		.services
395		.config
396		.network
397		.http
398		.max_response_size;
399
400	let http_response = request.send().await?.error_for_status()?;
401
402	let body = read_response_capped(http_response, limit).await?;
403	let response: JsonValue = serde_json::from_slice(&body)?;
404
405	if let Some(response) = response.as_object().as_ref()
406		&& let Some(error) = response.get("error").and_then(JsonValue::as_str)
407	{
408		let description = response
409			.get("error_description")
410			.and_then(JsonValue::as_str)
411			.unwrap_or("(no description)");
412
413		return Err!(Request(Forbidden("Error from provider: {error}: {description}",)));
414	}
415
416	Ok(response)
417}
418
419/// Generate a unique-id string determined by the combination of `Provider` and
420/// `Session` instances.
421#[inline]
422pub fn unique_id((provider, session): (&Provider, &Session)) -> Result<String> {
423	unique_id_parts((provider, session)).and_then(unique_id_iss_sub)
424}
425
426/// Generate a unique-id string determined by the combination of `Provider`
427/// instance and `sub` string.
428#[inline]
429pub fn unique_id_sub((provider, sub): (&Provider, &str)) -> Result<String> {
430	unique_id_sub_parts((provider, sub)).and_then(unique_id_iss_sub)
431}
432
433/// Generate a unique-id string determined by the combination of `issuer_url`
434/// and `Session` instance.
435#[inline]
436pub fn unique_id_iss((iss, session): (&str, &Session)) -> Result<String> {
437	unique_id_iss_parts((iss, session)).and_then(unique_id_iss_sub)
438}
439
440/// Generate a unique-id string determined by the `issuer_url` and the `sub`
441/// strings directly.
442pub fn unique_id_iss_sub((iss, sub): (&str, &str)) -> Result<String> {
443	let hash = sha256::delimited([iss, sub].iter());
444	let b64 = b64encode.encode(hash);
445
446	Ok(b64)
447}
448
449/// Derive the fallback localpart of an identity from its unique-id string.
450///
451/// The localpart is a lowercase prefix of 15 to 23 characters selected from the
452/// string's contents. An identity whose claimed usernames are unavailable
453/// therefore falls back to the same localpart on every sign-in.
454#[must_use]
455pub fn fallback_localpart(unique_id: &str) -> Localpart {
456	truncate_deterministic(unique_id, Some(15..23))
457		.chars()
458		.flat_map(char::to_lowercase)
459		.collect()
460}
461
462fn unique_id_parts<'a>(
463	(provider, session): (&'a Provider, &'a Session),
464) -> Result<(&'a str, &'a str)> {
465	identity_issuer(provider)
466		.ok_or_else(|| err!(Config("issuer_url", "issuer_url not found for this provider.")))
467		.and_then(|iss| unique_id_iss_parts((iss, session)))
468}
469
470fn unique_id_sub_parts<'a>(
471	(provider, sub): (&'a Provider, &'a str),
472) -> Result<(&'a str, &'a str)> {
473	identity_issuer(provider)
474		.ok_or_else(|| err!(Config("issuer_url", "issuer_url not found for this provider.")))
475		.map(|iss| (iss, sub))
476}
477
478/// Issuer string used as input to the identity hash. Pinned per-brand for
479/// providers whose published issuer has changed under us, so existing account
480/// associations survive the change.
481fn identity_issuer(provider: &Provider) -> Option<&str> {
482	match provider.brand.as_str() {
483		| "github" => Some("https://github.com/"),
484		| _ => provider.issuer_url.as_ref().map(Url::as_str),
485	}
486}
487
488fn unique_id_iss_parts<'a>((iss, session): (&'a str, &'a Session)) -> Result<(&'a str, &'a str)> {
489	session
490		.user_info
491		.as_ref()
492		.map(|user_info| user_info.sub.as_str())
493		.ok_or_else(|| err!(Request(NotFound("user_info not found for this session."))))
494		.map(|sub| (iss, sub))
495}