LDAP & SAML API Reference (POST-Only)

Complete API reference for LDAP and SAML authentication endpoints. All endpoints use POST for end-to-end encryption compliance.

---

LDAP Endpoints

1. Fetch LDAP Configuration

Endpoint: POST /auth/ldap/config

Request (empty body):

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

Response:

{
  "uri": "ldap://ldap.example.com:389",
  "bind_dn": "cn=admin,dc=example,dc=com",
  "base_dn": "dc=example,dc=com",
  "user_filter": "(uid={username})",
  "attr_mail": "mail",
  "attr_name": "cn",
  "group_member_attr": "memberOf"
}

Note: The bind_password is never returned in responses for security.

---

2. Create/Update LDAP Configuration

Endpoint: POST /auth/ldap/config

Request (with JSON body):

curl -X POST http://localhost:8000/auth/ldap/config \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "ldap://ldap.example.com:389",
    "bind_dn": "cn=admin,dc=example,dc=com",
    "bind_password": "admin_password",
    "base_dn": "dc=example,dc=com",
    "user_filter": "(uid={username})",
    "attr_mail": "mail",
    "attr_name": "cn",
    "group_member_attr": "memberOf"
  }'

Response:

{
  "status": "success"
}

---

3. LDAP Login

Endpoint: POST /auth/ldap/login

Request:

curl -X POST http://localhost:8000/auth/ldap/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'method=ldap&username=john.doe&password=password123'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "active": true
  },
  "permissions": ["user.read", "user.write"],
  "actions": ["view_dashboard"],
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_profile": { ... }
}

Error Responses:

// Invalid credentials
{
  "status_code": 401,
  "detail": "invalid ldap credentials"
}

// Missing username/password
{
  "status_code": 400,
  "detail": "username/password required"
}

---

SAML Endpoints

1. Fetch SAML Configuration

Endpoint: POST /auth/saml/config

Request (empty body):

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

Response:

{
  "sp_entity_id": "http://app.example.com/metadata/",
  "acs_url": "http://app.example.com/auth/saml/acs",
  "slo_url": "http://app.example.com/auth/saml/sls",
  "idp_entity_id": "https://idp.example.com/metadata/",
  "idp_sso_url": "https://idp.example.com/sso",
  "idp_x509cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "nameid_format": "persistent"
}

---

2. Create/Update SAML Configuration

Endpoint: POST /auth/saml/config

Request (with JSON body):

curl -X POST http://localhost:8000/auth/saml/config \
  -H "Content-Type: application/json" \
  -d '{
    "sp_entity_id": "http://app.example.com/metadata/",
    "acs_url": "http://app.example.com/auth/saml/acs",
    "slo_url": "http://app.example.com/auth/saml/sls",
    "idp_entity_id": "https://idp.example.com/metadata/",
    "idp_sso_url": "https://idp.example.com/sso",
    "idp_x509cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "nameid_format": "persistent"
  }'

Response:

{
  "status": "success"
}

---

3. Get SAML SP Metadata

Endpoints: - GET /auth/saml/metadata (for IdP compatibility) - POST /auth/saml/metadata (for E2E encryption)

GET Request:

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

POST Request:

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

Response (XML):

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" 
                  entityID="http://app.example.com/metadata/">
  <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false"
                   protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                              Location="http://app.example.com/auth/saml/acs" index="0"/>
    <!-- ... -->
  </SPSSODescriptor>
</EntityDescriptor>

---

4. Initiate SAML Login

Endpoint: POST /auth/saml/login

Request:

curl -X POST http://localhost:8000/auth/saml/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'relay_state=http://app.example.com/dashboard'

Response (redirect URL in JSON):

{
  "access_token": "https://idp.example.com/sso?SAMLRequest=PHNhbWxwOkF1dGhuUmVxdWVzdC...",
  "token_type": "saml_redirect"
}

Client Usage:

// Client redirects to the URL returned
window.location.href = response.access_token;

---

5. SAML Assertion Consumer Service (ACS)

Endpoint: POST /auth/saml/acs

After IdP authentication, the IdP POSTs a SAML response to this endpoint.

Request (form-encoded):

curl -X POST http://localhost:8000/auth/saml/acs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'SAMLResponse=PHNhbWxwOlJlc3BvbnNl...&RelayState=state123'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Error Responses:

// Signature verification failed
{
  "detail": {
    "errors": ["Signature verification failed"]
  }
}

// User not authenticated
{
  "detail": "not authenticated"
}

---

Third-Party Login (Unified Endpoint)

Unified Third-Party Login

Endpoint: POST /auth/third-party/login

LDAP Method:

curl -X POST http://localhost:8000/auth/third-party/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'method=ldap&username=john.doe&password=password123'

SAML Method (returns redirect):

curl -X POST http://localhost:8000/auth/third-party/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'method=saml&relay_state=http://app.example.com/dashboard'

Response (SAML redirect):

{
  "access_token": "https://idp.example.com/sso?SAMLRequest=...",
  "token_type": "saml_redirect"
}

---

Common Endpoints

Refresh Access Token

Endpoint: POST /auth/refresh

curl -X POST http://localhost:8000/auth/refresh \
  -H "Authorization: Bearer refresh_token_here"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Logout

Endpoint: POST /auth/logout

curl -X POST http://localhost:8000/auth/logout \
  -H "Authorization: Bearer access_token_here" \
  -H "Cookie: session-id=session_id_here"

Response:

{
  "status": "success"
}

---

Authentication Methods

JWT Token Usage

Include access token in Authorization header:

curl -H "Authorization: Bearer access_token_here" \
     http://localhost:8000/auth/user

Session Cookie

The system automatically sets a session-id cookie on login. Subsequent requests should include this cookie.

---

Error Codes

Status	Description
200	Success
400	Bad request (missing/invalid parameters)
401	Unauthorized (invalid credentials, expired token)
402	2FA required
403	Forbidden (insufficient permissions)
404	Not found
500	Server error

---

Request Examples

Complete LDAP Flow

#!/bin/bash

# 1. Configure LDAP
curl -X POST http://localhost:8000/auth/ldap/config \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "ldap://ldap.example.com",
    "bind_dn": "cn=admin,dc=example,dc=com",
    "bind_password": "admin",
    "base_dn": "dc=example,dc=com",
    "user_filter": "(uid={username})",
    "attr_mail": "mail"
  }'

# 2. Login
LOGIN_RESPONSE=$(curl -X POST http://localhost:8000/auth/ldap/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'method=ldap&username=john.doe&password=password123')

ACCESS_TOKEN=$(echo $LOGIN_RESPONSE | jq -r '.access_token')

# 3. Use token
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     http://localhost:8000/auth/user

Complete SAML Flow

#!/bin/bash

# 1. Configure SAML
curl -X POST http://localhost:8000/auth/saml/config \
  -H "Content-Type: application/json" \
  -d '{
    "sp_entity_id": "http://app.example.com/metadata/",
    "acs_url": "http://app.example.com/auth/saml/acs",
    "idp_entity_id": "https://idp.example.com/metadata/",
    "idp_sso_url": "https://idp.example.com/sso",
    "idp_x509cert": "cert_here"
  }'

# 2. Get metadata
curl -X POST http://localhost:8000/auth/saml/metadata

# 3. Initiate login
SAML_RESPONSE=$(curl -X POST http://localhost:8000/auth/saml/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'relay_state=http://app.example.com/dashboard')

REDIRECT_URL=$(echo $SAML_RESPONSE | jq -r '.access_token')

# 4. Redirect browser to IdP
open $REDIRECT_URL  # or redirect in client app

# 5. After IdP redirects back to /auth/saml/acs with SAMLResponse,
#    the system responds with access token

---

Notes

• ✅ All endpoints use POST for end-to-end encryption
• ✅ Metadata endpoint provides both GET (for IdPs) and POST (for E2E encryption)
• ✅ Configuration endpoints handle both fetch and update based on payload
• ✅ Sensitive data (e.g., bind_password) is never returned in responses
• ✅ JIT provisioning creates users automatically on first login
• ✅ User IDP links prevent account takeover via email matching