1#![forbid(unsafe_code)]
3
4use async_trait::async_trait;
5use minco_core::{
6 CapabilityProvision, ConfigurationField, ConfigurationValueKind, DataClass, Plugin,
7 PluginContext, PluginDescriptor, PluginError, PluginId, PluginStability,
8};
9use semver::{Version, VersionReq};
10use serde::{Deserialize, Serialize};
11use std::{
12 collections::{BTreeMap, BTreeSet},
13 sync::{Arc, Mutex},
14};
15
16#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
19pub struct VerifiedClaims {
20 pub subject: String,
21 #[serde(default)]
22 pub claims: BTreeMap<String, String>,
23}
24
25impl std::fmt::Debug for VerifiedClaims {
26 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
27 formatter
28 .debug_struct("VerifiedClaims")
29 .field("subject", &self.subject)
30 .field("claim_keys", &self.claims.keys().collect::<Vec<_>>())
31 .finish()
32 }
33}
34
35#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
36pub struct Identity {
37 pub subject: String,
38 #[serde(default)]
39 pub permissions: BTreeSet<String>,
40 #[serde(default)]
41 pub scopes: BTreeSet<String>,
42 #[serde(default)]
43 pub claims: BTreeMap<String, String>,
44}
45
46impl std::fmt::Debug for Identity {
47 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
48 formatter
49 .debug_struct("Identity")
50 .field("subject", &self.subject)
51 .field("permissions", &self.permissions)
52 .field("scopes", &self.scopes)
53 .field("claim_keys", &self.claims.keys().collect::<Vec<_>>())
54 .finish()
55 }
56}
57
58impl Identity {
59 pub fn has_permission(&self, permission: &str) -> bool {
60 self.permissions.contains(permission)
61 }
62
63 pub fn require_permission(&self, permission: &str) -> Result<(), IdentityError> {
64 if self.has_permission(permission) {
65 Ok(())
66 } else {
67 Err(IdentityError::PermissionDenied(permission.to_owned()))
68 }
69 }
70}
71
72impl From<Identity> for minco_http::Principal {
73 fn from(identity: Identity) -> Self {
74 let Identity {
75 subject,
76 permissions,
77 scopes,
78 claims,
79 } = identity;
80 Self {
81 subject,
82 permissions,
83 claims,
84 }
85 .with_scopes(scopes)
86 }
87}
88
89#[async_trait]
90pub trait IdentityProvider: Send + Sync + std::fmt::Debug {
91 async fn resolve(&self, claims: VerifiedClaims) -> Result<Identity, IdentityError>;
92}
93
94#[derive(Clone)]
95pub struct IdentityService(pub Arc<dyn IdentityProvider>);
96
97impl std::fmt::Debug for IdentityService {
98 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
99 formatter.debug_tuple("IdentityService").finish()
100 }
101}
102
103impl IdentityService {
104 pub fn new(provider: Arc<dyn IdentityProvider>) -> Self {
105 Self(provider)
106 }
107
108 pub async fn resolve(&self, claims: VerifiedClaims) -> Result<Identity, IdentityError> {
109 self.0.resolve(claims).await
110 }
111}
112
113#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
114pub struct InviteIdentity {
115 pub username: String,
116 pub email: String,
117 #[serde(default)]
118 pub attributes: BTreeMap<String, String>,
119 pub send_invitation: bool,
123}
124
125impl InviteIdentity {
126 pub fn validate(&self) -> Result<(), IdentityError> {
127 validate_managed_username(&self.username)?;
128 validate_email(&self.email)?;
129 validate_managed_attributes(&self.attributes)
130 }
131}
132
133#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
134pub struct ManagedIdentity {
135 pub username: String,
136 pub enabled: bool,
137 pub status: String,
138 #[serde(default)]
139 pub attributes: BTreeMap<String, String>,
140}
141
142#[async_trait]
143pub trait IdentityAdministrator: Send + Sync + std::fmt::Debug {
144 async fn invite(&self, command: InviteIdentity) -> Result<ManagedIdentity, IdentityError>;
145 async fn get(&self, username: &str) -> Result<Option<ManagedIdentity>, IdentityError>;
146 async fn disable(&self, username: &str) -> Result<bool, IdentityError>;
147 async fn delete(&self, username: &str) -> Result<bool, IdentityError>;
148}
149
150#[derive(Clone)]
151pub struct IdentityAdministrationService(pub Arc<dyn IdentityAdministrator>);
152
153impl std::fmt::Debug for IdentityAdministrationService {
154 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
155 formatter
156 .debug_tuple("IdentityAdministrationService")
157 .finish()
158 }
159}
160
161impl IdentityAdministrationService {
162 pub fn new(administrator: Arc<dyn IdentityAdministrator>) -> Self {
163 Self(administrator)
164 }
165
166 pub async fn invite(&self, command: InviteIdentity) -> Result<ManagedIdentity, IdentityError> {
167 command.validate()?;
168 self.0.invite(command).await
169 }
170
171 pub async fn get(&self, username: &str) -> Result<Option<ManagedIdentity>, IdentityError> {
172 validate_managed_username(username)?;
173 self.0.get(username).await
174 }
175
176 pub async fn disable(&self, username: &str) -> Result<bool, IdentityError> {
177 validate_managed_username(username)?;
178 self.0.disable(username).await
179 }
180
181 pub async fn delete(&self, username: &str) -> Result<bool, IdentityError> {
182 validate_managed_username(username)?;
183 self.0.delete(username).await
184 }
185}
186
187#[derive(Debug, Default)]
188pub struct MemoryIdentityAdministrator {
189 identities: Mutex<BTreeMap<String, ManagedIdentity>>,
190}
191
192impl MemoryIdentityAdministrator {
193 pub fn all(&self) -> Result<Vec<ManagedIdentity>, IdentityError> {
194 Ok(self
195 .identities
196 .lock()
197 .map_err(|_| IdentityError::Provider("identity memory lock was poisoned".into()))?
198 .values()
199 .cloned()
200 .collect())
201 }
202}
203
204#[async_trait]
205impl IdentityAdministrator for MemoryIdentityAdministrator {
206 async fn invite(&self, command: InviteIdentity) -> Result<ManagedIdentity, IdentityError> {
207 command.validate()?;
208 let mut identities = self
209 .identities
210 .lock()
211 .map_err(|_| IdentityError::Provider("identity memory lock was poisoned".into()))?;
212 if identities.contains_key(&command.username) {
213 return Err(IdentityError::Provider(
214 "managed identity already exists".into(),
215 ));
216 }
217 let mut attributes = command.attributes;
218 attributes.insert("email".into(), command.email);
219 let identity = ManagedIdentity {
220 username: command.username.clone(),
221 enabled: true,
222 status: if command.send_invitation {
223 "INVITED"
224 } else {
225 "CREATED"
226 }
227 .into(),
228 attributes,
229 };
230 identities.insert(command.username, identity.clone());
231 drop(identities);
232 Ok(identity)
233 }
234
235 async fn get(&self, username: &str) -> Result<Option<ManagedIdentity>, IdentityError> {
236 validate_managed_username(username)?;
237 Ok(self
238 .identities
239 .lock()
240 .map_err(|_| IdentityError::Provider("identity memory lock was poisoned".into()))?
241 .get(username)
242 .cloned())
243 }
244
245 async fn disable(&self, username: &str) -> Result<bool, IdentityError> {
246 validate_managed_username(username)?;
247 let mut identities = self
248 .identities
249 .lock()
250 .map_err(|_| IdentityError::Provider("identity memory lock was poisoned".into()))?;
251 let Some(identity) = identities.get_mut(username) else {
252 return Ok(false);
253 };
254 identity.enabled = false;
255 identity.status = "DISABLED".into();
256 drop(identities);
257 Ok(true)
258 }
259
260 async fn delete(&self, username: &str) -> Result<bool, IdentityError> {
261 validate_managed_username(username)?;
262 Ok(self
263 .identities
264 .lock()
265 .map_err(|_| IdentityError::Provider("identity memory lock was poisoned".into()))?
266 .remove(username)
267 .is_some())
268 }
269}
270
271#[derive(Debug, Clone, Serialize, Deserialize)]
272pub struct ClaimsMapping {
273 pub permission_claim: String,
274 pub scope_claim: String,
275 pub groups_claim: String,
276 pub separator: char,
277 #[serde(default)]
278 pub group_permissions: BTreeMap<String, BTreeSet<String>>,
279}
280
281impl Default for ClaimsMapping {
282 fn default() -> Self {
283 Self {
284 permission_claim: "permissions".into(),
285 scope_claim: "scope".into(),
286 groups_claim: "groups".into(),
287 separator: ' ',
288 group_permissions: BTreeMap::new(),
289 }
290 }
291}
292
293#[derive(Debug, Clone, Default)]
294pub struct ClaimsIdentityProvider {
295 mapping: ClaimsMapping,
296}
297
298impl ClaimsIdentityProvider {
299 pub const fn new(mapping: ClaimsMapping) -> Self {
300 Self { mapping }
301 }
302}
303
304#[async_trait]
305impl IdentityProvider for ClaimsIdentityProvider {
306 async fn resolve(&self, claims: VerifiedClaims) -> Result<Identity, IdentityError> {
307 if claims.subject.trim().is_empty() {
308 return Err(IdentityError::InvalidSubject);
309 }
310 let split = |value: Option<&String>| {
311 value
312 .into_iter()
313 .flat_map(|value| value.split(self.mapping.separator))
314 .map(str::trim)
315 .filter(|value| !value.is_empty())
316 .map(str::to_owned)
317 .collect::<BTreeSet<_>>()
318 };
319 let mut permissions = split(claims.claims.get(&self.mapping.permission_claim));
320 let scopes = split(claims.claims.get(&self.mapping.scope_claim));
321 if let Some(groups) = claims.claims.get(&self.mapping.groups_claim) {
322 for group in groups
323 .split(self.mapping.separator)
324 .map(str::trim)
325 .filter(|value| !value.is_empty())
326 {
327 if let Some(group_permissions) = self.mapping.group_permissions.get(group) {
328 permissions.extend(group_permissions.iter().cloned());
329 }
330 }
331 }
332 Ok(Identity {
333 subject: claims.subject,
334 permissions,
335 scopes,
336 claims: claims.claims,
337 })
338 }
339}
340
341#[derive(Debug, Clone, Default, Serialize, Deserialize)]
342struct ClaimsPluginConfiguration {
343 #[serde(default)]
344 permission_claim: Option<String>,
345 #[serde(default)]
346 scope_claim: Option<String>,
347 #[serde(default)]
348 groups_claim: Option<String>,
349 #[serde(default)]
350 separator: Option<String>,
351 #[serde(default)]
352 group_permissions: Option<BTreeMap<String, BTreeSet<String>>>,
353}
354
355#[derive(Debug, Clone)]
356enum IdentityPluginSource {
357 Claims(ClaimsMapping),
358 Custom(IdentityService),
359}
360
361#[derive(Debug, Clone)]
362pub struct IdentityPlugin {
363 source: IdentityPluginSource,
364 administrator: Option<IdentityAdministrationService>,
365}
366
367impl IdentityPlugin {
368 pub fn new(provider: Arc<dyn IdentityProvider>) -> Self {
371 Self {
372 source: IdentityPluginSource::Custom(IdentityService::new(provider)),
373 administrator: None,
374 }
375 }
376
377 pub const fn claims(mapping: ClaimsMapping) -> Self {
378 Self {
379 source: IdentityPluginSource::Claims(mapping),
380 administrator: None,
381 }
382 }
383
384 #[must_use]
385 pub fn with_administrator(mut self, administrator: Arc<dyn IdentityAdministrator>) -> Self {
386 self.administrator = Some(IdentityAdministrationService::new(administrator));
387 self
388 }
389}
390
391impl Default for IdentityPlugin {
392 fn default() -> Self {
393 Self::claims(ClaimsMapping::default())
394 }
395}
396
397impl Plugin for IdentityPlugin {
398 fn descriptor(&self) -> PluginDescriptor {
399 let mut descriptor = PluginDescriptor::new(
400 PluginId::new("identity").expect("static plugin ID"),
401 Version::new(1, 0, 0),
402 "Maps verified transport claims to provider-neutral identities and permissions",
403 );
404 descriptor.documentation = Some("https://docs.rs/minco-plugin-identity".into());
405 descriptor.core_compatibility =
406 VersionReq::parse(concat!("^", env!("CARGO_PKG_VERSION"))).expect("package version");
407 descriptor.stability = PluginStability::Beta;
408 descriptor
409 .data_classes
410 .extend([DataClass::Personal, DataClass::Confidential]);
411 descriptor.provides.extend([
412 CapabilityProvision {
413 name: "identity.resolve".into(),
414 version: Version::new(1, 0, 0),
415 },
416 CapabilityProvision {
417 name: "authorization.permissions".into(),
418 version: Version::new(1, 0, 0),
419 },
420 ]);
421 if self.administrator.is_some() {
422 descriptor.provides.push(CapabilityProvision {
423 name: "identity.admin".into(),
424 version: Version::new(1, 0, 0),
425 });
426 }
427
428 if let IdentityPluginSource::Claims(mapping) = &self.source {
429 descriptor
430 .configuration
431 .extend(claims_configuration(mapping));
432 }
433 descriptor
434 }
435
436 fn install(&self, context: &mut PluginContext<'_>) -> Result<(), PluginError> {
437 let service = match &self.source {
438 IdentityPluginSource::Custom(service) => service.clone(),
439 IdentityPluginSource::Claims(defaults) => {
440 let configuration = context.configuration::<ClaimsPluginConfiguration>()?;
441 let separator = configuration
442 .separator
443 .as_deref()
444 .map(parse_separator)
445 .transpose()
446 .map_err(PluginError::Installation)?
447 .unwrap_or(defaults.separator);
448 let mapping = ClaimsMapping {
449 permission_claim: non_empty_or(
450 configuration.permission_claim,
451 &defaults.permission_claim,
452 "permission_claim",
453 )?,
454 scope_claim: non_empty_or(
455 configuration.scope_claim,
456 &defaults.scope_claim,
457 "scope_claim",
458 )?,
459 groups_claim: non_empty_or(
460 configuration.groups_claim,
461 &defaults.groups_claim,
462 "groups_claim",
463 )?,
464 separator,
465 group_permissions: configuration
466 .group_permissions
467 .unwrap_or_else(|| defaults.group_permissions.clone()),
468 };
469 IdentityService::new(Arc::new(ClaimsIdentityProvider::new(mapping)))
470 }
471 };
472 context.services().insert(Arc::new(service))?;
473 if let Some(administrator) = &self.administrator {
474 context.services().insert(Arc::new(administrator.clone()))?;
475 }
476 Ok(())
477 }
478}
479
480pub fn validate_managed_username(value: &str) -> Result<(), IdentityError> {
481 if value.trim().is_empty() || value.len() > 128 || value.chars().any(char::is_control) {
482 Err(IdentityError::InvalidAdministrationRequest(
483 "username must contain 1-128 non-control characters".into(),
484 ))
485 } else {
486 Ok(())
487 }
488}
489
490fn validate_email(value: &str) -> Result<(), IdentityError> {
491 let Some((local, domain)) = value.split_once('@') else {
492 return Err(IdentityError::InvalidAdministrationRequest(
493 "email address is malformed".into(),
494 ));
495 };
496 if local.is_empty()
497 || domain.is_empty()
498 || domain.starts_with('.')
499 || domain.ends_with('.')
500 || value.matches('@').count() != 1
501 || value.len() > 320
502 || !value.is_ascii()
503 || value
504 .chars()
505 .any(|character| character.is_control() || character.is_ascii_whitespace())
506 || domain.split('.').any(|label| {
507 label.is_empty()
508 || label.len() > 63
509 || label.starts_with('-')
510 || label.ends_with('-')
511 || !label
512 .bytes()
513 .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
514 })
515 {
516 return Err(IdentityError::InvalidAdministrationRequest(
517 "email address is malformed".into(),
518 ));
519 }
520 Ok(())
521}
522
523fn validate_managed_attributes(attributes: &BTreeMap<String, String>) -> Result<(), IdentityError> {
524 if attributes.len() > 32
525 || attributes.iter().any(|(key, value)| {
526 key.trim().is_empty()
527 || key.len() > 128
528 || value.len() > 2048
529 || key.chars().any(char::is_control)
530 || value.chars().any(char::is_control)
531 || matches!(
532 key.as_str(),
533 "sub" | "username" | "email" | "email_verified"
534 )
535 || key.starts_with("cognito:")
536 })
537 {
538 return Err(IdentityError::InvalidAdministrationRequest(
539 "managed identity attributes are invalid or contain reserved provider fields".into(),
540 ));
541 }
542 Ok(())
543}
544
545fn claims_configuration(mapping: &ClaimsMapping) -> Vec<ConfigurationField> {
546 vec![
547 string_field(
548 "permission_claim",
549 "Verified claim containing permissions",
550 &mapping.permission_claim,
551 ),
552 string_field(
553 "scope_claim",
554 "Verified claim containing OAuth/OIDC scopes",
555 &mapping.scope_claim,
556 ),
557 string_field(
558 "groups_claim",
559 "Verified claim containing provider group names",
560 &mapping.groups_claim,
561 ),
562 string_field(
563 "separator",
564 "Single character separating claim values",
565 &mapping.separator.to_string(),
566 ),
567 ConfigurationField {
568 key: "group_permissions".into(),
569 kind: ConfigurationValueKind::Object,
570 required: false,
571 secret: false,
572 description: "Map of provider groups to application permissions".into(),
573 default: Some(
574 serde_json::to_value(&mapping.group_permissions)
575 .expect("claims group mapping must serialize"),
576 ),
577 },
578 ]
579}
580
581fn string_field(key: &str, description: &str, default: &str) -> ConfigurationField {
582 ConfigurationField {
583 key: key.into(),
584 kind: ConfigurationValueKind::String,
585 required: false,
586 secret: false,
587 description: description.into(),
588 default: Some(serde_json::Value::String(default.into())),
589 }
590}
591
592fn parse_separator(value: &str) -> Result<char, String> {
593 let mut characters = value.chars();
594 let separator = characters
595 .next()
596 .ok_or_else(|| "identity separator must contain one character".to_owned())?;
597 if characters.next().is_some() || separator.is_control() {
598 return Err("identity separator must contain one non-control character".into());
599 }
600 Ok(separator)
601}
602
603fn non_empty_or(value: Option<String>, default: &str, field: &str) -> Result<String, PluginError> {
604 let value = value.unwrap_or_else(|| default.to_owned());
605 if value.trim().is_empty() || value.chars().any(char::is_control) {
606 return Err(PluginError::Installation(format!(
607 "identity {field} must not be empty or contain control characters"
608 )));
609 }
610 Ok(value)
611}
612
613#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq)]
614pub enum IdentityError {
615 #[error("identity subject must not be empty")]
616 InvalidSubject,
617 #[error("permission denied: {0}")]
618 PermissionDenied(String),
619 #[error("identity administration request is invalid: {0}")]
620 InvalidAdministrationRequest(String),
621 #[error("identity provider failed: {0}")]
622 Provider(String),
623}
624
625#[cfg(test)]
626mod tests {
627 use super::*;
628 use minco_core::{PluginManager, PluginSelection};
629
630 #[tokio::test]
631 async fn verified_claims_map_to_permissions_and_scopes() {
632 let provider = ClaimsIdentityProvider::default();
633 let identity = provider
634 .resolve(VerifiedClaims {
635 subject: "client-1".into(),
636 claims: BTreeMap::from([
637 ("permissions".into(), "feedback.create feedback.read".into()),
638 ("scope".into(), "openid profile".into()),
639 ]),
640 })
641 .await
642 .unwrap();
643 assert!(identity.has_permission("feedback.create"));
644 assert!(identity.scopes.contains("openid"));
645 assert!(identity.require_permission("feedback.manage").is_err());
646
647 let principal: minco_http::Principal = identity.into();
648 assert!(principal.has_permission("feedback.create"));
649 assert!(principal.has_scope("openid"));
650 assert!(!principal.has_scope("open"));
651 }
652
653 #[test]
654 fn identity_debug_output_does_not_include_verified_claim_values() {
655 let identity = Identity {
656 subject: "client-1".into(),
657 permissions: BTreeSet::new(),
658 scopes: BTreeSet::new(),
659 claims: BTreeMap::from([("token_hint".into(), "secret-claim-value".into())]),
660 };
661 let principal: minco_http::Principal = identity.clone().into();
662
663 assert!(!format!("{identity:?}").contains("secret-claim-value"));
664 assert!(!format!("{principal:?}").contains("secret-claim-value"));
665 }
666
667 #[tokio::test]
668 async fn runtime_mapping_configuration_is_applied_to_claims_provider() {
669 let mut manager = PluginManager::default();
670 manager.register(IdentityPlugin::default()).unwrap();
671 let id = PluginId::new("identity").unwrap();
672 let mut selection = PluginSelection::default();
673 selection.enabled.insert(id.clone());
674 selection.configuration.insert(
675 id,
676 serde_json::json!({
677 "permission_claim": "roles",
678 "scope_claim": "scp",
679 "groups_claim": "teams",
680 "separator": ",",
681 "group_permissions": {
682 "operators": ["feedback.manage"]
683 }
684 }),
685 );
686 let application = manager.compose(&selection).unwrap();
687 let service = application.services.get::<IdentityService>().unwrap();
688 let identity = service
689 .resolve(VerifiedClaims {
690 subject: "developer-1".into(),
691 claims: BTreeMap::from([
692 ("roles".into(), "feedback.read".into()),
693 ("scp".into(), "openid,profile".into()),
694 ("teams".into(), "operators".into()),
695 ]),
696 })
697 .await
698 .unwrap();
699 assert!(identity.has_permission("feedback.manage"));
700 assert!(identity.scopes.contains("profile"));
701 }
702
703 #[tokio::test]
704 async fn administration_is_injected_and_validated_before_the_provider() {
705 let administrator = Arc::new(MemoryIdentityAdministrator::default());
706 let mut manager = PluginManager::default();
707 manager
708 .register(IdentityPlugin::default().with_administrator(administrator.clone()))
709 .unwrap();
710 let mut selection = PluginSelection::default();
711 selection.enabled.insert(PluginId::new("identity").unwrap());
712 let application = manager.compose(&selection).unwrap();
713 assert!(
714 application
715 .graph
716 .capabilities
717 .contains_key("identity.admin")
718 );
719 let service = application
720 .services
721 .get::<IdentityAdministrationService>()
722 .unwrap();
723 let identity = service
724 .invite(InviteIdentity {
725 username: "reviewer-1".into(),
726 email: "reviewer@example.test".into(),
727 attributes: BTreeMap::from([("custom:team".into(), "review".into())]),
728 send_invitation: false,
729 })
730 .await
731 .unwrap();
732 assert_eq!(identity.status, "CREATED");
733 assert!(
734 service
735 .invite(InviteIdentity {
736 username: "reviewer-2".into(),
737 email: "reviewer@example.test".into(),
738 attributes: BTreeMap::from([("sub".into(), "reserved".into())]),
739 send_invitation: false,
740 })
741 .await
742 .is_err()
743 );
744 assert_eq!(administrator.all().unwrap().len(), 1);
745 }
746
747 #[test]
748 fn administration_rejects_ambiguous_email_addresses() {
749 for email in [
750 "reviewer @example.test",
751 "reviewer@example.test@attacker.test",
752 "reviewer@example..test",
753 "reviewer@-example.test",
754 ] {
755 assert!(
756 InviteIdentity {
757 username: "reviewer".into(),
758 email: email.into(),
759 attributes: BTreeMap::new(),
760 send_invitation: false,
761 }
762 .validate()
763 .is_err(),
764 "{email}"
765 );
766 }
767 }
768}