SAML 2.0 Integration Endpoints

Overview

The SAML 2.0 endpoints provide integration with an external SAML 2.0 Identity Provider (IdP) to enable IdP-initiated single sign-on (SSO) for platform operators. This allows users to authenticate with their organization's IdP and be redirected to the platform's admin user interface.

This component exposes two primary endpoints:

• GET /saml/metadata: Generates the Service Provider (SP) metadata XML required by an IdP to establish a trust relationship.
• POST /saml/acs: The Assertion Consumer Service (ACS) endpoint that receives and validates SAML assertions from the IdP.

These endpoints are located under the /saml path prefix, which is intentionally separate from the standard /admin/v1 API path. This allows the IdP to post the SAML assertion to the ACS endpoint without requiring prior authentication to the platform.

This integration currently supports only the IdP-initiated SSO flow, where the sign-in process begins at the IdP (e.g., by a user clicking an application tile).

IdP-Initiated SSO Flow

The following diagram illustrates the sequence of events during an IdP-initiated sign-in.

sequenceDiagram
    participant User as User's Browser
    participant IdP as Identity Provider (IdP)
    participant S2R as SAML Endpoints

    User->>IdP: Initiates sign-in (e.g., clicks app tile)
    IdP-->>User: Authenticates user (if not already logged in)
    IdP->>User: Generates SAML Assertion and auto-submits form to ACS
    User->>S2R: POST /saml/acs (with SAMLResponse and RelayState)
    S2R->>S2R: Load IdP config and verify assertion
    alt Verification Successful
        S2R->>User: HTTP 302 Redirect to RelayState or "/"
        User->>S2R: Follows redirect to admin UI
    else Verification Failed
        S2R->>User: HTTP 4xx Error Response
    end

How it Works

1. A user initiates login from their IdP's dashboard.
2. The IdP authenticates the user and generates a SAML assertion.
3. The IdP uses the HTTP-POST binding to send a form to the user's browser, which automatically posts the base64-encoded SAMLResponse to the platform's POST /saml/acs endpoint.
4. The ACS endpoint retrieves the active SAML IdP configuration, including the IdP's metadata XML.
5. It uses the IdP metadata to verify the signature and validity of the incoming SAML assertion.
6. It checks if the authenticated user's email domain is present in the configured list of allowedEmailDomains.
7. If verification is successful and the email domain is allowed, the service responds with an HTTP 302 Found redirect, sending the user's browser to the admin UI. The redirect target is determined by the RelayState parameter or defaults to the root (/).
8. If verification fails for any reason (e.g., invalid signature, expired assertion, disallowed email domain), the service returns an appropriate 4xx error response.

API Endpoints

GET /saml/metadata

This endpoint provides the Service Provider (SP) metadata required to configure this platform as an application within a SAML IdP. The metadata is an XML document that describes the platform's SAML capabilities, including its entity ID and ACS endpoint location.

The entityID and ACS Location URLs are constructed based on the platform's public base URL. This URL is determined in the following order of precedence:

1. The value of the S2R_PUBLIC_BASE_URL system setting.
2. If the system setting is not defined, the value of the S2R_PUBLIC_BASE_URL environment variable.
3. If neither is defined, the URL is derived from the scheme, host, and port of the incoming GET request.

Example SP Metadata

The following is an example of the XML document returned by this endpoint. The %s placeholders are dynamically replaced with the correct entityID and acsUrl values.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="%s">
  <md:SPSSODescriptor AuthnRequestsSigned="false"
                      WantAssertionsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                 Location="%s"
                                 index="0"
                                 isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

POST /saml/acs

The Assertion Consumer Service (ACS) endpoint. It receives the SAML assertion from the IdP via an HTTP POST request from the user's browser.

Request Parameters

The request must have a Content-Type of application/x-www-form-urlencoded and include the following form parameters:

Responses

• 302 Found: On successful verification, the service redirects the user's browser. The Location header will point to the path specified by RelayState or to / as a default.
• 400 Bad Request: Returned if the system is not properly configured for SAML. See Troubleshooting for details.
• 401 Unauthorized: Returned if the SAMLResponse fails verification (e.g., invalid signature, expired assertion). The response body contains details.
• 403 Forbidden: Returned if the user's email domain is not in the configured allowlist.

Configuration Prerequisites

For the SAML endpoints to function correctly, the following configuration must be in place:

• installation_id System Setting: The POST /saml/acs endpoint requires a valid installation_id system setting to be configured. If this setting is missing, the endpoint will return a 400 Bad Request error.
• Active SAML IdP Configuration: An active Identity Provider configuration with the provider type saml must exist. This configuration must contain:
  • metadataXml: The full XML metadata document from the external IdP. This is required to validate incoming assertions.
  • allowedEmailDomains: An optional list of email domains (e.g., ["example.com"]). If this list is configured, only users whose email addresses belong to one of these domains will be allowed to sign in. If the list is empty or not defined, users from any email domain are permitted.

Troubleshooting

When a request to the POST /saml/acs endpoint fails, it returns an HTTP error status and a JSON body containing an error code and message.

See Also

• Identity Provider Configuration
• System Settings Management

All SOAP-to-REST docs