Skip to content

LDAP & SAML POST-Only Implementation Checklist

✅ Completed Tasks

Endpoint Conversions

  • ✅ POST /auth/ldap/login - LDAP authentication
  • ✅ POST /auth/ldap/config - Unified fetch/update (replaces GET + PUT)
  • ✅ POST /auth/saml/login - SAML login initiation
  • ✅ POST /auth/saml/acs - SAML assertion consumer service
  • ✅ POST /auth/saml/config - Unified fetch/update (replaces GET + PUT)
  • ✅ POST /auth/saml/metadata - Added for E2E encryption support
  • ✅ GET /auth/saml/metadata - Kept for IdP compatibility
  • ✅ POST /auth/third-party/login - Unified LDAP/SAML endpoint

Bug Fixes (Already Applied)

  • ✅ Fixed SAML ACS try/finally bug causing NameError
  • ✅ Fixed SAML user provisioning (username now set to email or nameid)
  • ✅ Fixed token expiry (200s → 15 min + refresh token)
  • ✅ Fixed missing upsert config imports
  • ✅ Fixed HTTP status codes for JSON responses

Code Quality

  • ✅ All config endpoints support both fetch (no body) and update (with payload)
  • ✅ Consistent error handling across all endpoints
  • ✅ No sensitive data (passwords, certs) in URL parameters
  • ✅ All endpoints properly handle E2E encrypted requests

Testing

  • ✅ test_ldap_saml_integration.py - Comprehensive test suite
  • ✅ LDAP configuration CRUD
  • ✅ LDAP authentication (success/failure)
  • ✅ LDAP JIT provisioning
  • ✅ SAML configuration CRUD
  • ✅ SAML metadata (GET + POST)
  • ✅ SAML ACS processing
  • ✅ SAML JIT provisioning
  • ✅ End-to-end workflows
  • ✅ Configuration management tests

Documentation

Endpoint Matrix

LDAP Endpoints

Endpoint Method Body Type Purpose E2E Encrypted
/auth/ldap/config POST None Fetch config ✅
/auth/ldap/config POST JSON Create/update config ✅
/auth/ldap/login POST Form-encoded Authenticate user ✅

SAML Endpoints

Endpoint Method Body Type Purpose E2E Encrypted
/auth/saml/metadata GET None IdP fetches metadata ℹ️ Public
/auth/saml/metadata POST None Client fetches metadata ✅
/auth/saml/config POST None Fetch config ✅
/auth/saml/config POST JSON Create/update config ✅
/auth/saml/login POST Form Initiate SAML flow ✅
/auth/saml/acs POST Form Handle SAML response ✅

Unified Endpoint

Endpoint Method Purpose E2E Encrypted
/auth/third-party/login POST LDAP or SAML login ✅

Request/Response Examples

Config Endpoint Duality

Fetch (no body):

curl -X POST http://localhost:8000/auth/ldap/config

# Returns:
{
  "uri": "ldap://...",
  "bind_dn": "cn=admin,...",
  ...
}

Update (with JSON):

curl -X POST http://localhost:8000/auth/ldap/config \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "ldap://new.com",
    "bind_dn": "cn=admin,..."
  }'

# Returns:
{
  "status": "success"
}

SAML Metadata - Dual Support

For IdP (GET):

curl http://localhost:8000/auth/saml/metadata

# Returns XML metadata

For E2E Client (POST):

curl -X POST http://localhost:8000/auth/saml/metadata

# Returns same XML metadata

Security Considerations

✅ Sensitive Data Protection

  • ✅ Passwords never appear in URLs (POST only)
  • ✅ bind_password never returned in responses
  • ✅ Certificates only returned when explicitly requested
  • ✅ All config updates via encrypted request bodies

✅ JIT Provisioning Security

  • ✅ Users linked via IDP subject (prevents takeover)
  • ✅ Email matching for SAML user linking (existing users)
  • ✅ Credential created for all provisioned users
  • ✅ UserIdentityProvider link prevents duplicate creation

✅ Token Generation

  • ✅ Access tokens: 15 minutes (configurable)
  • ✅ Refresh tokens: 7 days (configurable)
  • ✅ JWT subject encrypted for security
  • ✅ Session records tracked in database

Testing Coverage

Run all tests: 

pytest test_ldap_saml_integration.py -v

Test categories: - LDAP Workflow (line ~30) - Config CRUD - Authentication - User provisioning

  • SAML Workflow (line ~90)
  • Config CRUD
  • Metadata generation

  • ACS processing

  • Configuration Management (line ~150)

  • POST fetch operations
  • POST create/update operations

  • Data validation

  • E2E Workflows (line ~220)

  • Complete LDAP login flow
  • Complete SAML login flow

API Compatibility

Breaking Changes

  • ✗ GET /auth/ldap/config → POST /auth/ldap/config
  • ✗ PUT /auth/ldap/config → POST /auth/ldap/config
  • ✗ GET /auth/saml/config → POST /auth/saml/config
  • ✗ PUT /auth/saml/config → POST /auth/saml/config
  • ℹ️ GET /auth/saml/metadata still works (kept for IdP compatibility)

New Features

  • ✅ POST /auth/saml/metadata - E2E encrypted metadata fetch
  • ✅ Unified config endpoints (fetch + update in one)
  • ✅ Complete POST-only API for end-to-end encryption

Deployment Checklist

  • [ ] Review endpoint changes with frontend team
  • [ ] Update client API calls from GET/PUT to POST
  • [ ] Test with actual LDAP server (if available)
  • [ ] Test SAML flow with IdP
  • [ ] Verify E2E encryption in transit
  • [ ] Monitor for API errors in logs
  • [ ] Update API documentation in frontend
  • [ ] Test refresh token flow
  • [ ] Verify session management
  • [ ] Load test with concurrent logins

Troubleshooting

Issue: Config endpoint returns 400

Solution: Ensure you're sending JSON body correctly for updates, or empty body for fetches.

Issue: LDAP fails to connect

Solution: Verify LDAP server is reachable and bind_dn/bind_password are correct.

Issue: SAML ACS returns 401

Solution: Check IdP certificate is correct and response signature matches.

Issue: User not found after SAML login

Solution: Verify email attribute is returned by IdP and matches existing user email.

Files Modified

Router

  • backend/routers/auth.py - All endpoint conversions

Tests

  • backend/test_ldap_saml_integration.py - Updated with POST methods

Documentation

  • backend/LDAP_SAML_WORKFLOW.md - Complete workflow guide
  • backend/LDAP_SAML_API_REFERENCE.md - Detailed API reference
  • backend/LDAP_SAML_POST_CONVERSION.md - This file

Next Steps

  1. Client Update - Update frontend API calls to use POST
  2. Testing - Run full test suite with actual LDAP/SAML servers
  3. Deployment - Deploy to staging environment
  4. Validation - Verify with real authentication flows
  5. Monitoring - Monitor logs for any issues
  6. Documentation - Update client SDK documentation