Enterprise SSO API Reference

🔐 SSO API Overview

The RecoAgent Enterprise SSO API provides comprehensive identity management capabilities including SAML 2.0, OAuth 2.0/OIDC, and LDAP/Active Directory integration.

🚀 Authentication

API Key Authentication

Authorization: Bearer sk-enterprise-123

SSO Token Authentication

Authorization: Bearer <sso_token>

📚 API Endpoints

1. SAML 2.0 Integration

Initialize SAML SSO

POST /api/v2/sso/saml/initiate

Request Body:

{
  "provider": "okta",
  "entity_id": "https://your-company.okta.com",
  "sso_url": "https://your-company.okta.com/app/your-app/sso/saml",
  "x509_cert": "-----BEGIN CERTIFICATE-----\n...",
  "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"
  }
}

Response:

{
  "status": "success",
  "sso_url": "https://your-company.okta.com/app/your-app/sso/saml",
  "request_id": "req_123456789"
}

Process SAML Response

POST /api/v2/sso/saml/callback

Request Body:

{
  "saml_response": "<saml:Response>...</saml:Response>",
  "request_id": "req_123456789"
}

Response:

{
  "status": "success",
  "user": {
    "id": "user_123",
    "email": "john.doe@company.com",
    "first_name": "John",
    "last_name": "Doe",
    "roles": ["analyst"]
  },
  "access_token": "jwt_token_here",
  "refresh_token": "refresh_token_here",
  "expires_in": 3600
}

2. OAuth 2.0/OIDC Integration

Initialize OAuth Flow

POST /api/v2/sso/oauth/initiate

Request Body:

{
  "provider": "google",
  "client_id": "your_google_client_id",
  "redirect_uri": "https://your-domain.com/auth/callback",
  "scopes": ["openid", "email", "profile"]
}

Response:

{
  "status": "success",
  "authorization_url": "https://accounts.google.com/oauth/authorize?...",
  "state": "oauth_state_123"
}

Process OAuth Callback

POST /api/v2/sso/oauth/callback

Request Body:

{
  "code": "authorization_code",
  "state": "oauth_state_123",
  "provider": "google"
}

Response:

{
  "status": "success",
  "user": {
    "id": "user_123",
    "email": "john.doe@company.com",
    "first_name": "John",
    "last_name": "Doe",
    "roles": ["analyst"]
  },
  "access_token": "jwt_token_here",
  "refresh_token": "refresh_token_here",
  "expires_in": 3600
}

3. LDAP/Active Directory Integration

LDAP Authentication

POST /api/v2/sso/ldap/authenticate

Request Body:

{
  "username": "john.doe",
  "password": "user_password",
  "server": "ldap://your-ad-server.com",
  "base_dn": "DC=company,DC=com"
}

Response:

{
  "status": "success",
  "user": {
    "id": "user_123",
    "username": "john.doe",
    "email": "john.doe@company.com",
    "first_name": "John",
    "last_name": "Doe",
    "groups": ["Analysts", "Data Team"],
    "roles": ["analyst"]
  },
  "access_token": "jwt_token_here",
  "expires_in": 3600
}

4. SSO Management

Get SSO Status

GET /api/v2/sso/status

Response:

{
  "status": "success",
  "sso_enabled": true,
  "providers": [
    {
      "name": "okta",
      "type": "saml",
      "status": "active",
      "users_count": 150
    },
    {
      "name": "google",
      "type": "oauth",
      "status": "active",
      "users_count": 75
    }
  ]
}

Refresh SSO Token

POST /api/v2/sso/refresh

Request Body:

{
  "refresh_token": "refresh_token_here"
}

Response:

{
  "status": "success",
  "access_token": "new_jwt_token_here",
  "expires_in": 3600
}

Logout

POST /api/v2/sso/logout

Request Body:

{
  "access_token": "jwt_token_here"
}

Response:

{
  "status": "success",
  "message": "Successfully logged out"
}

🔧 Configuration

SAML Configuration

from recoagent.packages.security.sso import SAMLProvider

# Configure SAML provider
saml_provider = SAMLProvider(
    entity_id="https://your-company.okta.com",
    sso_url="https://your-company.okta.com/app/your-app/sso/saml",
    x509_cert="-----BEGIN CERTIFICATE-----\n...",
    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"
    }
)

OAuth Configuration

from recoagent.packages.security.sso import OAuthProvider

# Configure OAuth provider
oauth_provider = OAuthProvider(
    provider="google",
    client_id="your_google_client_id",
    client_secret="your_google_client_secret",
    redirect_uri="https://your-domain.com/auth/callback",
    scopes=["openid", "email", "profile"]
)

LDAP Configuration

from recoagent.packages.security.sso import LDAPConnector

# Configure LDAP connector
ldap_connector = LDAPConnector(
    server="ldap://your-ad-server.com",
    base_dn="DC=company,DC=com",
    bind_dn="CN=service-account,OU=Service Accounts,DC=company,DC=com",
    bind_password="service_account_password",
    user_search_base="OU=Users,DC=company,DC=com",
    group_search_base="OU=Groups,DC=company,DC=com"
)

📊 Error Codes

Code	Description	Solution
400	Bad Request	Check request parameters
401	Unauthorized	Invalid credentials or token
403	Forbidden	Insufficient permissions
404	Not Found	SSO provider not found
409	Conflict	SSO provider already exists
500	Internal Server Error	Contact support

🛡️ Security

Token Security

• JWT Tokens: Signed with RS256 algorithm
• Token Expiration: 1 hour default, configurable
• Refresh Tokens: 30 days default, configurable
• Token Rotation: Automatic refresh token rotation

Data Protection

• Encryption: All sensitive data encrypted at rest
• Transmission: HTTPS/TLS 1.3 for all communications
• Audit Logging: Complete SSO event audit trail
• Rate Limiting: Protection against brute force attacks

📚 Examples

Python SDK Usage

from recoagent_sdk import RecoAgentClient

# Initialize client
client = RecoAgentClient(
    api_key="sk-enterprise-123",
    base_url="https://api.recoagent.com/v2"
)

# Initiate SAML SSO
sso_response = client.sso.saml.initiate({
    "provider": "okta",
    "entity_id": "https://your-company.okta.com",
    "sso_url": "https://your-company.okta.com/app/your-app/sso/saml"
})

# Process SAML callback
auth_response = client.sso.saml.callback({
    "saml_response": "<saml:Response>...</saml:Response>",
    "request_id": sso_response.request_id
})

print(f"User: {auth_response.user.email}")
print(f"Token: {auth_response.access_token}")

TypeScript SDK Usage

import { RecoAgentClient } from '@recoagent/sdk';

// Initialize client
const client = new RecoAgentClient({
  apiKey: 'sk-enterprise-123',
  baseUrl: 'https://api.recoagent.com/v2'
});

// Initiate OAuth flow
const ssoResponse = await client.sso.oauth.initiate({
  provider: 'google',
  clientId: 'your_google_client_id',
  redirectUri: 'https://your-domain.com/auth/callback'
});

// Process OAuth callback
const authResponse = await client.sso.oauth.callback({
  code: 'authorization_code',
  state: ssoResponse.state,
  provider: 'google'
});

console.log(`User: ${authResponse.user.email}`);
console.log(`Token: ${authResponse.access_token}`);

🎯 Next Steps

1. Choose SSO Provider: Select SAML, OAuth, or LDAP
2. Configure Identity Provider: Set up your identity provider
3. Test SSO Integration: Validate SSO functionality
4. Configure User Mapping: Map identity provider attributes
5. Set Up Role Assignment: Configure automatic role assignment
6. Monitor SSO Usage: Track SSO authentication events

---

Secure your AI operations with enterprise-grade SSO! 🔐