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

auth_framework/server/token_exchange/
token_exchange_factory.rs
