Setting up Casdoor as a SAML identity provider: metadata, ACS and attributes

SAML integrations fail for boring reasons: an entity ID with a trailing slash, an ACS URL that does not match, or an assertion signed twice. This guide walks through Casdoor as the SAML 2.0 identity provider, with the exact values the service provider needs and the fields to set on the Casdoor application.

Casdoor also works in the opposite direction — as a service provider signing users in through an external SAML IdP — but that is a different setup and is covered in identity provider vs service provider.

Step 1: Get the IdP metadata

Every service provider needs three things from the identity provider: the single sign-on URL, the issuer (entity ID) and the signing certificate. Most service providers can read all three from a metadata URL.

Casdoor exposes metadata per application:

<casdoor-host>/api/saml/metadata?application=admin/<application-name>

For example, a Casdoor instance at https://door.example.com and the application app-built-in expose:

https://door.example.com/api/saml/metadata?application=admin/app-built-in

In the Casdoor admin console, open the application, go to the SAML tab, and click Copy SAML metadata URL. Opening the URL in a browser downloads the metadata XML.

If the service provider asks for values instead of a URL, take them from that metadata: the SingleSignOnService URL, the entity ID and the X.509 certificate.

Step 2: Configure the Casdoor application

On the application's edit page, two fields decide whether the integration works:

The Redirect URLs value is used as the audience of the assertion. If it differs from the SP's entity ID by even a trailing slash, the SP rejects the assertion with an audience mismatch.

The SAML reply URL controls the response binding:

• Set — Casdoor posts the SAML response to this URL with HTTP POST, overriding the assertion consumer URL in the request.
• Empty — Casdoor uses the redirect binding and sends the response to the assertion consumer URL from the SAML request.

If you are unsure which the service provider supports, start by leaving it empty and following the SP's documentation; most enterprise applications publish their ACS URL and expect HTTP POST.

Step 3: Configure the service provider

Register Casdoor at the service provider with the values from step 1. Common fields:

• SSO URL — the SingleSignOnService from the metadata.
• Entity ID / issuer — the Casdoor entity ID from the metadata.
• Certificate — the signing certificate from the metadata.
• ACS URL — the service provider's own endpoint, entered back into Casdoor as the SAML reply URL.

The loop closes when both sides have each other's values. A mismatch on either side is the most common cause of "invalid signature" or "response not for this recipient" errors.

Step 4: Map attributes

By default, a Casdoor SAML response carries three attributes:

If the service provider needs more — roles, department, a group list — add rows to the SAML attributes table on the application. The value can use these variables: $user.owner, $user.name, $user.displayName, $user.email, $user.id, $user.phone, $user.roles, $user.permissions and $user.groups.

Two practical notes:

• If the service provider only needs the NameID, turn on Disable SAML attributes. This avoids XML namespace problems with strict SPs.
• Casdoor always signs the SAML response. Enable SAML assertion signature additionally signs the assertion inside it; some SPs (Sentry, for example) reject responses with a signed assertion, so only turn it on when the SP requires it.

Step 5: Decide who starts the login

SP-initiated is the default: the user opens the application, the SP redirects to Casdoor, and Casdoor returns the assertion. This is what most applications expect.

IdP-initiated (portal-style) SSO is also supported. To enable it:

1. Set SAML reply URL to the SP's ACS URL — required, or the sign-in fails.
2. Make sure the first entry of Redirect URLs is the SP's entity ID.
3. Use the IdP-initiated SSO URL shown on the SAML tab:

<casdoor-host>/login/saml/authorize/admin/<application-name>

Add ?RelayState=/dashboard to send the SP a landing path. IdP-initiated responses have no InResponseTo, because no request preceded them.

Step 6: Single logout

To let a sign-out at the service provider end the Casdoor session, set SAML single logout URL on the application to the SP's SingleLogoutService URL.

Casdoor announces its own SingleLogoutService in the application metadata:

<casdoor-backend-host>/api/saml/logout/admin/<application-name>

Every assertion carries a SessionIndex in its AuthnStatement, which is how Casdoor finds the sessions to end. Logout works in both directions: the SP can send a LogoutRequest to Casdoor, and Casdoor can send LogoutRequests to the applications a user signed in to.

Troubleshooting checklist

Where to go next

If you are choosing protocols rather than setting one up, read SAML vs OIDC. If you need to know what the SP expects, read identity provider vs service provider.

Casdoor is open source and self-hostable, with a hosted option from $9 per month and no per-user fees.