---
title: "SAML/SSO"
description: "Configure SAML 2.0 single sign-on for enterprise TraceRTM deployments"
---

# SAML/SSO

TraceRTM supports SAML 2.0 for enterprise single sign-on (SSO), allowing organizations to use their existing identity providers (IdP) for authentication. This enables centralized user management and seamless access for employees.

## Supported Identity Providers

| Provider | Status | Documentation |
|----------|--------|---------------|
| **Okta** | Fully Supported | [Setup Guide](#okta-setup) |
| **Azure AD** | Fully Supported | [Setup Guide](#azure-ad-setup) |
| **Google Workspace** | Fully Supported | [Setup Guide](#google-workspace-setup) |
| **OneLogin** | Fully Supported | [Setup Guide](#onelogin-setup) |
| **PingIdentity** | Fully Supported | [Setup Guide](#generic-saml-setup) |
| **Auth0** | Fully Supported | [Setup Guide](#generic-saml-setup) |
| **Generic SAML 2.0** | Supported | [Setup Guide](#generic-saml-setup) |

## Prerequisites

- TraceRTM Enterprise plan
- Organization admin access
- Admin access to your Identity Provider

## TraceRTM SAML Configuration

### Service Provider (SP) Metadata

TraceRTM provides the following SP information for your IdP configuration:

```yaml
Entity ID: https://auth.tracertm.dev/saml/{org_id}
ACS URL: https://auth.tracertm.dev/saml/{org_id}/acs
SLO URL: https://auth.tracertm.dev/saml/{org_id}/slo

# Metadata URL
Metadata: https://auth.tracertm.dev/saml/{org_id}/metadata
```

### Download SP Metadata

```bash
# Download metadata XML
curl https://auth.tracertm.dev/saml/org_abc123/metadata > tracertm-sp-metadata.xml

# Or via CLI
rtm sso metadata download --format xml
```

## Okta Setup

### Step 1: Create Application in Okta

1. Log in to Okta Admin Console
2. Go to **Applications** → **Create App Integration**
3. Select **SAML 2.0**
4. Click **Next**

### Step 2: Configure SAML Settings

```yaml
# General Settings
App name: TraceRTM
App logo: (upload TraceRTM logo)

# SAML Settings
Single sign on URL: https://auth.tracertm.dev/saml/{org_id}/acs
Audience URI (SP Entity ID): https://auth.tracertm.dev/saml/{org_id}
Default RelayState: (leave empty)
Name ID format: EmailAddress
Application username: Email

# Attribute Statements
email: user.email
firstName: user.firstName
lastName: user.lastName
department: user.department (optional)
role: appuser.tracertm_role (optional)

# Group Attribute Statements (optional)
groups: Matches regex: tracertm.*
```

### Step 3: Configure TraceRTM

```python
from tracertm.admin import OrganizationAdmin

admin = OrganizationAdmin(client)

# Configure SAML connection
await admin.sso.configure_saml({
    "provider": "okta",
    "idp_entity_id": "http://www.okta.com/exk123456",
    "idp_sso_url": "https://yourcompany.okta.com/app/tracertm/exk123456/sso/saml",
    "idp_slo_url": "https://yourcompany.okta.com/app/tracertm/exk123456/slo/saml",
    "idp_certificate": """-----BEGIN CERTIFICATE-----
MIIDpDCCAoygAwIBAgIGAX...
-----END CERTIFICATE-----""",
    "attribute_mapping": {
        "email": "email",
        "first_name": "firstName",
        "last_name": "lastName",
        "role": "role",
        "groups": "groups"
    },
    "jit_provisioning": True,
    "default_role": "viewer"
})
```

### Step 4: Test Connection

```bash
# Test SAML configuration
rtm sso test

# Output:
# ✓ IdP metadata retrieved
# ✓ Certificate valid until 2025-12-31
# ✓ SSO URL reachable
# ✓ Test login successful
```

## Azure AD Setup

### Step 1: Create Enterprise Application

1. Go to Azure Portal → **Azure Active Directory**
2. Navigate to **Enterprise applications** → **New application**
3. Click **Create your own application**
4. Select **Integrate any other application (Non-gallery)**
5. Name it "TraceRTM"

### Step 2: Configure Single Sign-On

1. Select **Single sign-on** → **SAML**
2. Upload TraceRTM metadata or configure manually:

```yaml
# Basic SAML Configuration
Identifier (Entity ID): https://auth.tracertm.dev/saml/{org_id}
Reply URL (ACS URL): https://auth.tracertm.dev/saml/{org_id}/acs
Sign on URL: https://app.tracertm.dev/login
Logout URL: https://auth.tracertm.dev/saml/{org_id}/slo

# User Attributes & Claims
email: user.mail
firstName: user.givenname
lastName: user.surname
groups: user.groups
role: user.assignedroles
```

### Step 3: Download Azure AD Certificate

1. In the SAML configuration, download **Certificate (Base64)**
2. Note the **Login URL** and **Azure AD Identifier**

### Step 4: Configure TraceRTM

```python
await admin.sso.configure_saml({
    "provider": "azure_ad",
    "idp_entity_id": "https://sts.windows.net/{tenant_id}/",
    "idp_sso_url": "https://login.microsoftonline.com/{tenant_id}/saml2",
    "idp_slo_url": "https://login.microsoftonline.com/{tenant_id}/saml2",
    "idp_certificate": azure_certificate_content,
    "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.microsoft.com/ws/2008/06/identity/claims/groups"
    },
    "jit_provisioning": True
})
```

## Google Workspace Setup

### Step 1: Create Custom SAML App

1. Go to Google Admin Console
2. Navigate to **Apps** → **Web and mobile apps**
3. Click **Add app** → **Add custom SAML app**
4. Name it "TraceRTM"

### Step 2: Download Google IdP Metadata

- Download the IdP metadata XML file
- Note the SSO URL and Entity ID

### Step 3: Configure Service Provider

```yaml
# Service provider details
ACS URL: https://auth.tracertm.dev/saml/{org_id}/acs
Entity ID: https://auth.tracertm.dev/saml/{org_id}
Start URL: https://app.tracertm.dev
Signed response: Checked
Name ID format: EMAIL
Name ID: Basic Information > Primary email

# Attribute mapping
email: Basic Information > Primary email
firstName: Basic Information > First name
lastName: Basic Information > Last name
department: Employee details > Department
```

### Step 4: Configure TraceRTM

```python
await admin.sso.configure_saml({
    "provider": "google",
    "idp_entity_id": "https://accounts.google.com/o/saml2?idpid=...",
    "idp_sso_url": "https://accounts.google.com/o/saml2/idp?idpid=...",
    "idp_certificate": google_certificate_content,
    "attribute_mapping": {
        "email": "email",
        "first_name": "firstName",
        "last_name": "lastName",
        "department": "department"
    },
    "jit_provisioning": True
})
```

## Generic SAML Setup

For other SAML 2.0 identity providers:

### Required IdP Information

```python
saml_config = {
    # Required
    "idp_entity_id": "https://idp.example.com/metadata",
    "idp_sso_url": "https://idp.example.com/sso",
    "idp_certificate": """-----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----""",

    # Optional
    "idp_slo_url": "https://idp.example.com/slo",
    "sign_requests": True,
    "sign_algorithm": "RSA_SHA256",

    # Attribute mapping
    "attribute_mapping": {
        "email": "urn:oid:0.9.2342.19200300.100.1.3",
        "first_name": "urn:oid:2.5.4.42",
        "last_name": "urn:oid:2.5.4.4",
        "groups": "memberOf"
    }
}

await admin.sso.configure_saml(saml_config)
```

### Configure via CLI

```bash
# Interactive configuration
rtm sso configure --provider saml

# From metadata file
rtm sso configure \
  --provider saml \
  --metadata-file idp-metadata.xml \
  --jit-provisioning \
  --default-role viewer
```

## User Provisioning

### Just-In-Time (JIT) Provisioning

Create users automatically on first login:

```python
await admin.sso.configure_saml({
    "jit_provisioning": True,
    "default_role": "viewer",
    "default_teams": ["team_default"],
    "auto_create_teams": True,  # Create teams from groups
    "group_to_role_mapping": {
        "tracertm-admins": "admin",
        "tracertm-editors": "editor",
        "tracertm-viewers": "viewer"
    }
})
```

### SCIM Provisioning

For automated user lifecycle management:

```python
# Enable SCIM
scim_config = await admin.sso.enable_scim()

print(f"SCIM Endpoint: {scim_config.endpoint}")
print(f"SCIM Token: {scim_config.bearer_token}")

# Configure in your IdP:
# SCIM connector URL: https://api.tracertm.dev/scim/v2
# Auth: Bearer token
```

### Manual Provisioning

```python
# Pre-create users before SSO login
await admin.users.create({
    "email": "user@company.com",
    "role": "editor",
    "sso_only": True,  # Can only login via SSO
    "teams": ["engineering", "product"]
})
```

## SSO Enforcement

### Require SSO for All Users

```python
await admin.sso.update_policy({
    "sso_required": True,
    "allowed_email_domains": ["company.com", "subsidiary.com"],
    "allow_password_login": False,
    "allow_api_key_without_sso": True
})
```

### Domain-Based Enforcement

```python
await admin.sso.update_policy({
    "domain_policies": {
        "company.com": {
            "sso_required": True,
            "idp_connection_id": "conn_okta"
        },
        "contractor.com": {
            "sso_required": False,
            "mfa_required": True
        }
    }
})
```

## Multi-IdP Configuration

Support multiple identity providers:

```python
# Primary IdP for employees
await admin.sso.add_connection({
    "id": "conn_okta",
    "provider": "okta",
    "display_name": "Employee Login",
    "email_domains": ["company.com"],
    # ... Okta configuration
})

# Secondary IdP for contractors
await admin.sso.add_connection({
    "id": "conn_azure",
    "provider": "azure_ad",
    "display_name": "Contractor Login",
    "email_domains": ["contractor-agency.com"],
    # ... Azure AD configuration
})

# Login will route based on email domain
```

## Session Management

### SSO Session Settings

```python
await admin.sso.update_session_policy({
    "session_duration_hours": 8,
    "idle_timeout_minutes": 60,
    "force_re_auth_for_sensitive_actions": True,
    "sync_session_with_idp": True,  # End session when IdP session ends
    "single_logout_enabled": True
})
```

### Single Logout (SLO)

```python
# User logout triggers SLO to IdP
async def logout(user_id: str):
    # End TraceRTM session
    await client.auth.logout()

    # Redirect to IdP logout
    slo_url = await client.auth.get_slo_url()
    return redirect(slo_url)
```

## Troubleshooting

### SAML Response Errors

```python
# Debug SAML responses
await admin.sso.enable_debug_mode(
    duration_minutes=30,
    capture_requests=True
)

# View debug logs
logs = await admin.sso.get_debug_logs()
for log in logs:
    print(f"{log.timestamp}: {log.event}")
    print(f"  Request: {log.saml_request}")
    print(f"  Response: {log.saml_response}")
    print(f"  Error: {log.error}")
```

### Common Issues

**"Invalid SAML Response"**
- Check that the ACS URL matches exactly
- Verify certificate hasn't expired
- Ensure clock skew is within 5 minutes

**"User Not Found"**
- Enable JIT provisioning
- Check email attribute mapping
- Verify user has access in IdP

**"Invalid Signature"**
- Download fresh IdP certificate
- Ensure correct certificate is configured
- Check signature algorithm compatibility

### Test Mode

```python
# Test without affecting production
await admin.sso.enable_test_mode({
    "test_users": ["test@company.com"],
    "bypass_sso_for_admins": True
})

# Perform tests...

await admin.sso.disable_test_mode()
```

## Security Considerations

### Certificate Management

```python
# Check certificate expiration
cert_info = await admin.sso.get_certificate_info()
print(f"Expires: {cert_info.expires_at}")
print(f"Days until expiry: {cert_info.days_until_expiry}")

if cert_info.days_until_expiry < 30:
    # Alert admins to update certificate
    await send_certificate_expiry_alert(cert_info)
```

### Audit Logging

```python
# SSO events are logged
events = await client.events.list(
    entity_type="sso",
    event_types=[
        "sso.login_success",
        "sso.login_failure",
        "sso.logout",
        "sso.config_changed"
    ]
)

for event in events:
    print(f"{event.timestamp}: {event.event_type}")
    print(f"  User: {event.user_email}")
    print(f"  IdP: {event.metadata.get('idp')}")
```

## CLI Reference

```bash
# Configure SSO
rtm sso configure --provider okta

# View SSO status
rtm sso status

# Test SSO connection
rtm sso test

# Download SP metadata
rtm sso metadata download

# View SSO users
rtm sso users list

# Debug SSO
rtm sso debug --enable --duration 30m

# View debug logs
rtm sso debug logs
```

## Related Documentation

- [Authentication Overview](/docs/api-reference/authentication) - Auth methods
- [MFA](/docs/api-reference/authentication/mfa) - Multi-factor authentication
- [Security Best Practices](/docs/wiki/guides/security) - Security guidelines

