Skip to main content

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