SAML SP Setup Guide

1. Exchange metadata

SAML setup is a two-way metadata exchange: you import the SP's metadata into authserver.app, and the SP imports authserver.app's IdP metadata.

• Import the SP's metadata. On the SAML App create/edit screen, either paste the SP's metadata URL or upload its metadata XML file, then click Apply Metadata. This pre-fills the SP Entity ID, Assertion Consumer Service (ACS) URL, and (when present in the metadata) NameID Format and SP Encryption Certificate — review the pre-filled values before saving. The SP's SingleLogoutService location is not auto-imported; if the SP supports SLO, set SP Single Logout Service URL yourself in step 5.
• Publish your IdP metadata to the SP. Once a SAML App record is saved, its IdP metadata is published at /metadata/<record number>/ on your tenant domain. Give this URL to the SP so it can import your entityID, SSO endpoint, NameID format, and signing/encryption certificates.

Before or after either import, run the metadata through the SAML Metadata Parser to confirm it parses cleanly and check its entityID, endpoints, and certificates.

2. Configure the SAML App record

A SAML App record captures both sides of the relationship:

• IdP Entity ID — a URI identifying authserver.app as the IdP for this app (a URL or a URN).
• SP Entity ID and SP Consumer URL (ACS) — the SP's identifier and the endpoint it expects the SAML Response posted to.
• Initiation type — whether the flow can start at the SP (SP), at authserver.app (IDP), or either (BOTH, the default). A real AuthnRequest from the SP is always accepted no matter which you choose — this only controls what happens when someone reaches your app's SSO URL with no AuthnRequest. Set it to SP to require the SP-initiated flow.
• SP Start URL — required when Initiation type is SP: a visitor who arrives at your SSO URL with no AuthnRequest is redirected here instead of getting an IdP-initiated login, so the SP can send them back with a fresh one. Left blank with Initiation type SP, that visitor sees a configuration-error page rather than either silently logging in or landing nowhere. Ignored (optional) for IDP or BOTH.
• Signing certificate — the managed certificate authserver.app signs assertions with. An SP-provided encryption certificate is optional, for SPs that require encrypted assertions.

The SAML Response is always delivered via HTTP-POST regardless of the configured binding value, to keep assertion data out of URLs, HTTP logs, and Referer headers.

3. Choose the NameID format and source

NameID Format tells the SP how to interpret the required <NameID> element. NameID Source Field picks which field on the authserver.app user record (email, username, full name, etc.) supplies that value. Confirm both against what the SP's own documentation expects before going live.

These are illustrative, not generated: authserver.app puts your chosen NameID Source Field's actual value into <NameID> and simply labels it with the Format you selected — it does not synthesize an opaque, single-use identifier for Transient or generate a stable pseudonymous one for Persistent. If the SP expects a true opaque identifier for either of those formats, pick a source field that's actually opaque and stable/rotating as appropriate, not something like a real email address.

4. Set up attribute release

NameID is required and separate from optional attributes. Use the Attribute Release section of the SAML App form to add one mapping per attribute the SP needs: pick the source user field (email, first/last/full name, phone, address fields, etc.), the exact <Attribute Name="..."> value the SP expects to receive, and its NameFormat (Unspecified, URI, or Basic). Only attributes you explicitly map are released in the assertion.

5. Enable Single Logout (optional)

To support SP-initiated Single Logout, set SP Single Logout Service URL to the SP's SingleLogoutService location — this is where authserver.app delivers the signed LogoutResponse. Leave it blank if the SP doesn't support SLO. authserver.app's own SLO endpoint is published automatically in your IdP metadata once the SAML App is saved, so the SP picks it up as part of the same metadata import from step 1 — no separate configuration step is needed on your side.

Validate your setup

Use the free diagnostic tools to confirm each side is configured correctly:

• SAML Metadata Parser — fetch, upload, or paste either side's metadata to check its entityID, SSO/ACS endpoints, NameID format, and certificates before you rely on it.
• SAML Response Debugger — paste a captured SAMLResponse to see exactly what NameID and attributes were sent, and catch mismatches against what the SP expects.

Example: annotated SP metadata

A minimal SP metadata document, with the parts Apply Metadata (step 1) actually reads highlighted and labeled below — run your own SP's metadata through the SAML Metadata Parser first if you want to see this same breakdown for it.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                      entityID="https://sp.example.com/saml/metadata">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIC...(base64-encoded certificate)...==</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                             Location="https://sp.example.com/saml/slo"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                  Location="https://sp.example.com/saml/acs"
                                  index="0"
                                  isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

•    entityID → SP Entity ID — auto-imported by Apply Metadata.
•    AssertionConsumerService Location → SP Consumer URL (ACS) — auto-imported.
•    NameIDFormat → NameID Format — auto-imported only when it matches one of the five supported formats.
•    X509Certificate (use="encryption") → SP Encryption Certificate — auto-imported.
•    SingleLogoutService Location → SP Single Logout Service URL — not auto-imported; set it yourself in step 5.