SAML 2.0 Integration Guide

🔐 SAML 2.0 Enterprise Integration

SAML 2.0 provides the most secure and enterprise-ready authentication method for RecoAgent, supporting all major enterprise identity providers.

🎯 Supported Identity Providers

Enterprise Identity Providers

• Okta - Cloud-based identity management
• Azure Active Directory - Microsoft identity platform
• Ping Identity - Enterprise identity security
• OneLogin - Identity and access management
• PingFederate - Enterprise federation server
• Shibboleth - Open source identity provider

🚀 SAML Configuration

1. Identity Provider Setup

Okta Configuration

from recoagent.packages.security.sso import SAMLProvider

# Configure Okta SAML provider
okta_saml = SAMLProvider(
    entity_id="https://your-company.okta.com",
    sso_url="https://your-company.okta.com/app/your-app/sso/saml",
    slo_url="https://your-company.okta.com/app/your-app/slo/saml",
    x509_cert="-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    attribute_mapping={
        "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
        "last_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
        "groups": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/groups",
        "department": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department"
    },
    name_id_format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    authn_context="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
)

Azure AD Configuration

# Configure Azure AD SAML provider
azure_saml = SAMLProvider(
    entity_id="https://sts.windows.net/your-tenant-id/",
    sso_url="https://login.microsoftonline.com/your-tenant-id/saml2",
    slo_url="https://login.microsoftonline.com/your-tenant-id/saml2",
    x509_cert="-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    attribute_mapping={
        "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
        "last_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
        "groups": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/groups",
        "tenant_id": "http://schemas.microsoft.com/identity/claims/tenantid"
    },
    name_id_format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
)

2. SAML Request Configuration

# Configure SAML request parameters
saml_config = {
    "force_authn": True,  # Force re-authentication
    "is_passive": False,  # Active authentication
    "requested_authn_context": {
        "comparison": "exact",
        "authn_context_class_ref": [
            "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
        ]
    },
    "name_id_policy": {
        "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
        "allow_create": True
    }
}

3. SAML Response Processing

from recoagent.packages.security.sso import SAMLResponseProcessor

# Initialize SAML response processor
saml_processor = SAMLResponseProcessor(
    certificate_validation=True,
    signature_validation=True,
    encryption_validation=True,
    time_validation=True,
    audience_validation=True
)

# Process SAML response
def process_saml_response(saml_response, request_id):
    try:
        # Validate and parse SAML response
        response_data = saml_processor.process_response(
            saml_response=saml_response,
            request_id=request_id,
            expected_audience="https://your-domain.com",
            expected_issuer="https://your-company.okta.com"
        )
        
        # Extract user attributes
        user_attributes = response_data.get_attributes()
        
        # Create or update user
        user = create_or_update_user(user_attributes)
        
        # Generate session token
        session_token = generate_session_token(user)
        
        return {
            "status": "success",
            "user": user,
            "session_token": session_token
        }
        
    except SAMLValidationError as e:
        return {
            "status": "error",
            "message": f"SAML validation failed: {str(e)}"
        }

📊 SAML Features

1. Security Features

Feature	Description	Status
Signature Validation	XML signature verification	✅ Required
Certificate Validation	X.509 certificate validation	✅ Required
Time Validation	NotBefore/NotOnOrAfter validation	✅ Required
Audience Validation	Audience restriction validation	✅ Required
Encryption Support	Encrypted assertions support	✅ Optional

2. Attribute Mapping

SAML Attribute	RecoAgent Field	Description
emailaddress	email	User email address
givenname	first_name	User first name
surname	last_name	User last name
groups	groups	User group memberships
department	department	User department
title	title	User job title

3. Name ID Formats

Format	Description	Use Case
emailAddress	Email address as identifier	Simple email-based identification
persistent	Persistent identifier	Long-term user identification
transient	Transient identifier	Session-based identification
unspecified	Unspecified format	Generic identification

🛡️ Security Configuration

1. Certificate Management

# Certificate validation configuration
certificate_config = {
    "validation_enabled": True,
    "certificate_chain_validation": True,
    "crl_checking": True,
    "ocsp_checking": True,
    "certificate_expiry_warning_days": 30
}

# Configure certificate validation
saml_provider.configure_certificate_validation(certificate_config)

2. Encryption Configuration

# Encryption configuration
encryption_config = {
    "encryption_enabled": True,
    "encryption_algorithm": "AES-256-CBC",
    "key_transport_algorithm": "RSA-OAEP",
    "encryption_certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

# Configure encryption
saml_provider.configure_encryption(encryption_config)

3. Session Management

# Session configuration
session_config = {
    "session_timeout": 3600,  # 1 hour
    "idle_timeout": 1800,     # 30 minutes
    "max_concurrent_sessions": 3,
    "session_regeneration": True,
    "secure_cookies": True,
    "http_only_cookies": True
}

# Configure session management
saml_provider.configure_session_management(session_config)

📚 Identity Provider Setup

1. Okta Setup

Step 1: Create SAML Application

1. Log into Okta Admin Console
2. Navigate to Applications → Applications
3. Click "Create App Integration"
4. Select "SAML 2.0" as sign-in method
5. Configure application settings

Step 2: Configure SAML Settings

<!-- SAML Settings for Okta -->
<EntityDescriptor entityID="https://your-company.okta.com">
  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <SingleSignOnService 
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://your-company.okta.com/app/your-app/sso/saml"/>
    <SingleLogoutService 
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://your-company.okta.com/app/your-app/slo/saml"/>
  </IDPSSODescriptor>
</EntityDescriptor>

Step 3: Configure Attribute Mapping

{
  "attributeStatements": [
    {
      "name": "email",
      "namespace": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
      "values": ["user.email"]
    },
    {
      "name": "firstName",
      "namespace": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
      "values": ["user.firstName"]
    },
    {
      "name": "lastName",
      "namespace": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
      "values": ["user.lastName"]
    },
    {
      "name": "groups",
      "namespace": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
      "values": ["user.groups"]
    }
  ]
}

2. Azure AD Setup

Step 1: Register Enterprise Application

1. Log into Azure Portal
2. Navigate to Azure Active Directory → Enterprise applications
3. Click "New application" → "Create your own application"
4. Select "Non-gallery application"
5. Configure application properties

Step 2: Configure SAML Settings

<!-- SAML Settings for Azure AD -->
<EntityDescriptor entityID="https://sts.windows.net/your-tenant-id/">
  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <SingleSignOnService 
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://login.microsoftonline.com/your-tenant-id/saml2"/>
    <SingleLogoutService 
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://login.microsoftonline.com/your-tenant-id/saml2"/>
  </IDPSSODescriptor>
</EntityDescriptor>

Step 3: Configure User Attributes

{
  "samlTokenAttributes": [
    {
      "name": "emailaddress",
      "source": "user.mail"
    },
    {
      "name": "givenname",
      "source": "user.givenname"
    },
    {
      "name": "surname",
      "source": "user.surname"
    },
    {
      "name": "groups",
      "source": "user.groups"
    }
  ]
}

🎯 Testing SAML Integration

1. SAML Request Testing

# Test SAML authentication flow
def test_saml_authentication():
    # Generate SAML request
    saml_request = saml_provider.generate_authn_request(
        relay_state="test_state",
        force_authn=True
    )
    
    # Simulate SAML response
    saml_response = simulate_saml_response(saml_request)
    
    # Process SAML response
    result = process_saml_response(saml_response, "test_request_id")
    
    # Validate result
    assert result["status"] == "success"
    assert result["user"]["email"] is not None
    assert result["session_token"] is not None

2. Attribute Mapping Testing

# Test attribute mapping
def test_attribute_mapping():
    # Test user attributes
    user_attributes = {
        "emailaddress": "john.doe@company.com",
        "givenname": "John",
        "surname": "Doe",
        "groups": ["Analysts", "Data-Team"]
    }
    
    # Map attributes
    mapped_attributes = saml_provider.map_attributes(user_attributes)
    
    # Validate mapping
    assert mapped_attributes["email"] == "john.doe@company.com"
    assert mapped_attributes["first_name"] == "John"
    assert mapped_attributes["last_name"] == "Doe"
    assert mapped_attributes["groups"] == ["Analysts", "Data-Team"]

🎯 Next Steps

1. Choose Identity Provider: Select Okta, Azure AD, or another SAML provider
2. Configure SAML Application: Set up SAML application in your identity provider
3. Configure Attribute Mapping: Map identity provider attributes to RecoAgent fields
4. Test SAML Flow: Validate SAML authentication and attribute mapping
5. Configure Security: Set up certificate validation and encryption
6. Enable Audit Logging: Configure comprehensive SAML event logging

---

Secure your AI operations with enterprise-grade SAML authentication! 🔐