SSO Login

Authenticate user via SAML/OIDC SSO provider.

Outline

• Endpoint
• Headers
• Request Body
  • Parameters
• Validations
• Response
  • Success (200)
• Error Codes
• Data Flow
• Features
• Status

Endpoint

POST /api/v1/sso/login

Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
  "provider_id": 1,
  "saml_response": "base64_saml_response",
  "oidc_code": null,
  "state": "csrf_state_token"
}

Parameters

Field	Type	Required	Description
provider_id	integer	Yes	SSO Provider ID
saml_response	string	No	SAML response (for SAML providers)
oidc_code	string	No	OIDC authorization code (for OIDC providers)
state	string	No	State parameter for CSRF protection

Validations

• Provider ID validation
• SAML response or OIDC code required (one of them)
• State parameter validation (if provided)
• Provider configuration check

Response

Success (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": 123,
    "is_new_user": false,
    "message": "SSO login successful"
  },
  "message": "SSO login successful"
}

Error Codes

Status	Code	Description
400	SSO_LOGIN_FAILED	SSO authentication failed
400	INVALID_SAML_RESPONSE	Invalid SAML response
400	INVALID_OIDC_CODE	Invalid OIDC code
404	PROVIDER_NOT_FOUND	SSO provider not found

Data Flow

1. Provider Validation

   • Verify provider exists
   • Check provider type (SAML or OIDC)
   • Validate provider configuration

2. SAML/OIDC Processing

   • For SAML: Parse and verify SAML response
   • For OIDC: Exchange code for tokens
   • Extract user attributes

3. User Lookup/Creation

   • Find user by email or external ID
   • Create user if new (based on is_new_user)
   • Link SSO session

4. Token Generation

   • Generate OAuth2 access token
   • Generate refresh token
   • Create session

5. Response

   • Return tokens and user info
   • Include is_new_user flag

Features

• SAML/OIDC authentication
• User creation or linking
• OAuth2 token generation
• SSO session management
• Attribute mapping support

Status

[WARNING] TODO: Not Implemented

This endpoint schema is defined but the implementation logic is not yet complete. Refer to /openapi.json for planned schema.