auth_framework/server/token_exchange/
token_exchange_factory.rs

1//! # Token Exchange Factory Examples
2//!
3//! This module provides practical examples and factory methods for creating
4//! the appropriate token exchange manager based on your use case.
5
6use crate::errors::Result;
7use crate::security::secure_jwt::{SecureJwtConfig, SecureJwtValidator};
8use crate::server::oidc::oidc_session_management::SessionManager;
9use crate::server::token_exchange::TokenExchangeManager;
10use crate::server::token_exchange::advanced_token_exchange::{
11    AdvancedTokenExchangeConfig, AdvancedTokenExchangeManager,
12};
13use crate::server::token_exchange::token_exchange_common::{
14    ExchangeRequirements, ServiceComplexityLevel, TokenExchangeFactory, TokenExchangeUseCase,
15};
16use std::sync::Arc;
17
18/// High-level factory for creating token exchange managers
19pub struct TokenExchangeManagerFactory;
20
21impl TokenExchangeManagerFactory {
22    /// Create a basic token exchange manager for simple scenarios
23    pub fn create_basic_manager(jwt_secret: &str) -> Result<TokenExchangeManager> {
24        let config = SecureJwtConfig {
25            jwt_secret: jwt_secret.to_string(),
26            ..SecureJwtConfig::default()
27        };
28        let jwt_validator = SecureJwtValidator::new(config)?;
29        Ok(TokenExchangeManager::new(jwt_validator))
30    }
31
32    /// Create an advanced token exchange manager for enterprise scenarios
33    pub fn create_advanced_manager(
34        config: Option<AdvancedTokenExchangeConfig>,
35        session_manager: Arc<SessionManager>,
36    ) -> Result<AdvancedTokenExchangeManager> {
37        let config = config.unwrap_or_default();
38        AdvancedTokenExchangeManager::new(config, session_manager)
39    }
40
41    /// Create manager based on use case requirements
42    pub fn create_for_use_case(
43        use_case: TokenExchangeUseCase,
44        jwt_secret: &str,
45        session_manager: Option<Arc<SessionManager>>,
46    ) -> Result<Box<dyn std::any::Any>> {
47        let requirements = TokenExchangeFactory::get_recommended_config(&use_case);
48        let manager_type = TokenExchangeFactory::determine_manager_type(&requirements);
49
50        match manager_type {
51            ServiceComplexityLevel::Basic => {
52                let manager = Self::create_basic_manager(jwt_secret)?;
53                Ok(Box::new(manager))
54            }
55            ServiceComplexityLevel::Advanced => {
56                let session_mgr = session_manager
57                    .unwrap_or_else(|| Arc::new(SessionManager::new(Default::default())));
58                let manager = Self::create_advanced_manager(None, session_mgr)?;
59                Ok(Box::new(manager))
60            }
61        }
62    }
63
64    /// Get configuration recommendations for a use case
65    pub fn get_setup_guide(use_case: TokenExchangeUseCase) -> SetupGuide {
66        let requirements = TokenExchangeFactory::get_recommended_config(&use_case);
67        let manager_type = TokenExchangeFactory::determine_manager_type(&requirements);
68
69        SetupGuide {
70            use_case,
71            recommended_manager: manager_type,
72            requirements: requirements.clone(),
73            setup_instructions: match manager_type {
74                ServiceComplexityLevel::Basic => vec![
75                    "1. Create SecureJwtValidator with your JWT secret".to_string(),
76                    "2. Initialize TokenExchangeManager::new(jwt_validator)".to_string(),
77                    "3. Register policies for your clients".to_string(),
78                    "4. Use exchange_token(request, client_id) for exchanges".to_string(),
79                ],
80                ServiceComplexityLevel::Advanced => vec![
81                    "1. Configure AdvancedTokenExchangeConfig with your requirements".to_string(),
82                    "2. Set up SessionManager for OIDC integration".to_string(),
83                    "3. Initialize AdvancedTokenExchangeManager::new(config, session_manager)"
84                        .to_string(),
85                    "4. Register token processors if needed".to_string(),
86                    "5. Use exchange_token(request) for complex exchanges".to_string(),
87                ],
88            },
89            performance_characteristics: match manager_type {
90                ServiceComplexityLevel::Basic => PerformanceCharacteristics {
91                    memory_footprint: "~50KB base",
92                    latency: "Sub-millisecond",
93                    throughput: "10,000+ ops/sec",
94                    resource_usage: "Minimal",
95                },
96                ServiceComplexityLevel::Advanced => PerformanceCharacteristics {
97                    memory_footprint: "~500KB+ base",
98                    latency: "1-5ms",
99                    throughput: "1,000-5,000 ops/sec",
100                    resource_usage: "Moderate to High",
101                },
102            },
103            example_code: generate_example_code(use_case, manager_type),
104        }
105    }
106}
107
108/// Setup guide for token exchange implementation
109#[derive(Debug, Clone)]
110pub struct SetupGuide {
111    /// The use case this guide is for
112    pub use_case: TokenExchangeUseCase,
113
114    /// Recommended manager type
115    pub recommended_manager: ServiceComplexityLevel,
116
117    /// Feature requirements analysis
118    pub requirements: ExchangeRequirements,
119
120    /// Step-by-step setup instructions
121    pub setup_instructions: Vec<String>,
122
123    /// Performance characteristics to expect
124    pub performance_characteristics: PerformanceCharacteristics,
125
126    /// Example implementation code
127    pub example_code: String,
128}
129
130/// Performance characteristics for a manager type
131#[derive(Debug, Clone)]
132pub struct PerformanceCharacteristics {
133    /// Base memory footprint
134    pub memory_footprint: &'static str,
135
136    /// Expected latency range
137    pub latency: &'static str,
138
139    /// Expected throughput range
140    pub throughput: &'static str,
141
142    /// Overall resource usage
143    pub resource_usage: &'static str,
144}
145
146fn generate_example_code(
147    use_case: TokenExchangeUseCase,
148    manager_type: ServiceComplexityLevel,
149) -> String {
150    match (use_case, manager_type) {
151        (TokenExchangeUseCase::SimpleServiceToService, ServiceComplexityLevel::Basic) => r#"
152use auth_framework::server::{TokenExchangeManager, TokenExchangeRequest};
153use auth_framework::secure_jwt::SecureJwtValidator;
154
155async fn setup_simple_exchange() -> Result<(), Box<dyn std::error::Error>> {
156    // Create basic manager
157    let jwt_validator = SecureJwtValidator::new("your-secret-key".to_string())?;
158    let mut manager = TokenExchangeManager::new(jwt_validator);
159
160    // Register client policy
161    let policy = TokenExchangePolicy::default();
162    manager.register_policy("service_a".to_string(), policy).await;
163
164    // Simple exchange
165    let request = TokenExchangeRequest {
166        grant_type: "urn:ietf:params:oauth:grant-type:token-exchange".to_string(),
167        subject_token: "user_jwt_token".to_string(),
168        subject_token_type: "urn:ietf:params:oauth:token-type:jwt".to_string(),
169        requested_token_type: Some("urn:ietf:params:oauth:token-type:access_token".to_string()),
170        audience: Some("service_b".to_string()),
171        scope: Some("read".to_string()),
172        // ... other fields
173    };
174
175    let response = manager.exchange_token(request, "service_a").await?;
176    println!("New token: {}", response.access_token);
177
178    Ok(())
179}
180"#
181        .to_string(),
182
183        (TokenExchangeUseCase::EnterpriseIntegration, ServiceComplexityLevel::Advanced) => r#"
184use auth_framework::server::{
185    AdvancedTokenExchangeManager, AdvancedTokenExchangeConfig,
186    AdvancedTokenExchangeRequest, ExchangeContext,
187};
188use auth_framework::server::oidc_session_management::SessionManager;
189use std::sync::Arc;
190
191async fn setup_enterprise_exchange() -> Result<(), Box<dyn std::error::Error>> {
192    // Advanced configuration
193    let config = AdvancedTokenExchangeConfig {
194        enable_multi_party_chains: true,
195        max_delegation_depth: 10,
196        require_audit_trail: true,
197        enable_context_preservation: true,
198        // ... other enterprise settings
199        ..Default::default()
200    };
201
202    // Session management integration
203    let session_manager = Arc::new(SessionManager::new(Default::default()));
204    let manager = AdvancedTokenExchangeManager::new(config, session_manager)?;
205
206    // Complex exchange with business context
207    let context = ExchangeContext {
208        transaction_id: "enterprise_txn_123".to_string(),
209        business_context: serde_json::json!({
210            "department": "finance",
211            "operation": "quarterly_report_access",
212            "compliance_level": "sox_required"
213        }),
214        delegation_chain: Vec::new(),
215        // ... other context fields
216    };
217
218    let request = AdvancedTokenExchangeRequest {
219        grant_type: "urn:ietf:params:oauth:grant-type:token-exchange".to_string(),
220        subject_token: "enterprise_user_token".to_string(),
221        subject_token_type: "urn:ietf:params:oauth:token-type:jwt".to_string(),
222        requested_token_type: "urn:ietf:params:oauth:token-type:jwt".to_string(),
223        exchange_context: Some(context),
224        policy_requirements: vec![
225            "require_mfa".to_string(),
226            "audit_financial_access".to_string(),
227        ],
228        // ... other fields
229    };
230
231    let response = manager.exchange_token(request).await?;
232
233    // Enterprise features available in response
234    if let Some(audit) = response.exchange_audit {
235        println!("Audit ID: {}", audit.exchange_id);
236    }
237
238    Ok(())
239}
240"#
241        .to_string(),
242
243        _ => format!(
244            r#"
245// Example for {:?} using {:?} manager
246// Customize based on your specific requirements
247use auth_framework::server::token_exchange_common::*;
248
249async fn setup_custom_exchange() -> Result<(), Box<dyn std::error::Error>> {{
250    // Use TokenExchangeManagerFactory::get_setup_guide() for detailed instructions
251    let guide = TokenExchangeManagerFactory::get_setup_guide(TokenExchangeUseCase::{:?});
252
253    for instruction in &guide.setup_instructions {{
254        println!("Step: {{}}", instruction);
255    }}
256
257    Ok(())
258}}
259"#,
260            use_case, manager_type, use_case
261        ),
262    }
263}
264
265#[cfg(test)]
266mod tests {
267    use super::*;
268
269    #[test]
270    fn test_setup_guide_generation() {
271        let guide = TokenExchangeManagerFactory::get_setup_guide(
272            TokenExchangeUseCase::SimpleServiceToService,
273        );
274
275        assert_eq!(guide.recommended_manager, ServiceComplexityLevel::Basic);
276        assert!(!guide.setup_instructions.is_empty());
277        assert!(!guide.example_code.is_empty());
278    }
279
280    #[test]
281    fn test_advanced_setup_guide() {
282        let guide = TokenExchangeManagerFactory::get_setup_guide(
283            TokenExchangeUseCase::EnterpriseIntegration,
284        );
285
286        assert_eq!(guide.recommended_manager, ServiceComplexityLevel::Advanced);
287        assert!(guide.requirements.needs_audit_trail);
288        assert!(guide.requirements.needs_session_integration);
289    }
290
291    #[tokio::test]
292    async fn test_basic_manager_creation() {
293        let result = TokenExchangeManagerFactory::create_basic_manager("test-secret");
294        assert!(result.is_ok());
295    }
296}
auth_framework/server/token_exchange/token_exchange_factory.rs

auth_framework/server/token_exchange/
token_exchange_factory.rs
