SAML Configuration

SAML Configuration Management

POST /api/organizations/:org_slug/services/:service_slug/saml

Configure SAML Identity Provider settings for a service. This endpoint sets up the SAML integration parameters required for the service to function as an IdP.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

Path Parameters:

Request Body:

Request Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Example Request:

curl -X POST https://sso.example.com/api/organizations/acme-corp/services/main-app/saml \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "entity_id": "https://acme.my.salesforce.com",
    "acs_url": "https://acme.my.salesforce.com/services/auth/saml/AssertionConsumerService",
    "slo_url": "https://acme.my.salesforce.com/services/auth/saml/SingleLogoutService",
    "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "attribute_mapping": {
      "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    },
    "sign_assertions": true,
    "sign_response": true
  }'

Response (200 OK):

{
  "success": true,
  "message": "SAML configuration updated successfully"
}

Common NameID Formats:

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress (default, most common)
• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• urn:oasis:names:tc:SAML:2.0:nameid-format:transient

Attribute Mapping:

The attribute_mapping field allows you to map user fields to SAML attribute names expected by the Service Provider. Built-in source fields:

• email: User’s email address
• id: User’s unique identifier

Example mapping for common Service Providers:

Salesforce:

{
  "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
}

AWS:

{
  "email": "https://aws.amazon.com/SAML/Attributes/RoleSessionName"
}

Error Responses:

• 400 Bad Request: Invalid configuration (missing required fields, invalid URLs)

  {
    "error": "Entity ID is required when SAML is enabled"
  }
  

  {
    "error": "Invalid ACS URL"
  }
  

• 401 Unauthorized: Missing or invalid JWT token
• 403 Forbidden: User is not an admin/owner, or organization is not active
• 404 Not Found: Organization or service not found

Important Notes:

• You must generate a signing certificate (see below) before SAML can be used
• Both sign_assertions and sign_response set to true is recommended for security
• The Service Provider must be configured with the IdP’s metadata URL
• Organization must be in “active” status to configure SAML

GET /api/organizations/:org_slug/services/:service_slug/saml

Retrieve the current SAML Identity Provider configuration for a service.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

Path Parameters:

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X GET https://sso.example.com/api/organizations/acme-corp/services/main-app/saml \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

{
  "enabled": true,
  "entity_id": "https://acme.my.salesforce.com",
  "acs_url": "https://acme.my.salesforce.com/services/auth/saml/AssertionConsumerService",
  "slo_url": "https://acme.my.salesforce.com/services/auth/saml/SingleLogoutService",
  "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "attribute_mapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  },
  "sign_assertions": true,
  "sign_response": true,
  "has_certificate": true
}

Response Fields:

• enabled (boolean): Whether SAML IdP is enabled
• entity_id (string | null): Service Provider’s entity ID
• acs_url (string | null): Assertion Consumer Service URL
• slo_url (string | null): Single Logout URL (optional)
• name_id_format (string | null): NameID format configuration
• attribute_mapping (object | null): Custom attribute mappings
• sign_assertions (boolean): Whether assertions are signed
• sign_response (boolean): Whether responses are signed
• has_certificate (boolean): Whether an active signing certificate exists

DELETE /api/organizations/:org_slug/services/:service_slug/saml

Delete SAML Identity Provider configuration for a service. This will disable SAML and deactivate all associated signing certificates.

Authentication: Required (Organization Management JWT)

Permissions: Service-management capability or explicit service-manager relation

Path Parameters:

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X DELETE https://sso.example.com/api/organizations/acme-corp/services/main-app/saml \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

{
  "success": true,
  "message": "SAML configuration deleted successfully"
}

Important Notes:

• This action deactivates all signing certificates
• Users will no longer be able to authenticate via SAML to the Service Provider
• Configuration can be re-enabled by creating new settings and certificate