# Generic SAML single sign-on

<!-- Generated by scripts/generate.ts. Do not edit. -->

Create a SAML 2.0 app in your identity provider, paste the values from this setup, assign your users and share the identity provider metadata with us.

:::caution[Verification]
Not yet verified on a real Generic SAML tenant. It was written from the public Generic SAML documentation, so labels in the admin console may differ slightly.
:::

The values in braces, such as `{acs_url}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="create-app"></a>

### Create a SAML app

In the admin console of your identity provider, create a new SAML 2.0 application for this app. Your identity provider may call it a custom app, a service provider or a relying party. Give it a name your users will recognize.

:::caution[Labels not confirmed in step 1]
Written generically from the protocol specifications; no public Generic SAML admin page was checked for the console's own labels and menu paths.
:::

</li>

<li class="idp-step">

<a id="acs"></a>

### Enter the ACS URL

Paste `{acs_url}` into the assertion consumer service (ACS) URL field, which may be labelled single sign-on URL or reply URL. If the app also has recipient or destination fields, use the same value there.

<div class="setup-values">

Paste into Generic SAML:

- ACS URL: `{acs_url}`

</div>

Fixes: [`saml_destination_mismatch`](/errors/saml_destination_mismatch/), [`saml_response_malformed`](/errors/saml_response_malformed/)

</li>

<li class="idp-step">

<a id="audience"></a>

### Enter the SP entity ID

Paste `{sp_entity_id}` into the service provider entity ID field, which may be labelled audience, audience URI or identifier.

<div class="setup-values">

Paste into Generic SAML:

- SP entity ID: `{sp_entity_id}`

</div>

Fixes: [`saml_audience_mismatch`](/errors/saml_audience_mismatch/)

</li>

<li class="idp-step">

<a id="name-id"></a>

### Send the email address as the name ID

Set the name ID format to email address and send each user's email address as the name ID.

Fixes: [`saml_nameid_missing`](/errors/saml_nameid_missing/)

</li>

<li class="idp-step">

<a id="signing"></a>

### Sign responses with SHA-256

Make sure your identity provider signs the SAML response, the assertion or both, and uses SHA-256 (RSA-SHA256) as the signature algorithm.

Fixes: [`saml_signature_missing`](/errors/saml_signature_missing/), [`saml_signature_algorithm_weak`](/errors/saml_signature_algorithm_weak/)

</li>

<li class="idp-step">

<a id="attributes"></a>

### Send the user attributes

Add attributes named email with the email address, firstName with the first name and lastName with the last name. To send groups, add an attribute named groups with the user's group names.

Fixes: [`saml_email_missing`](/errors/saml_email_missing/)

</li>

<li class="idp-step">

<a id="assign"></a>

### Assign people to the app

Assign the people or groups who should sign in to this app with single sign-on.

Fixes: [`saml_idp_status_error`](/errors/saml_idp_status_error/)

</li>

<li class="idp-step">

<a id="metadata"></a>

### Share the identity provider metadata

Download the app's SAML metadata file and upload it in this setup. Your identity provider offers the metadata as a file rather than a stable URL, so upload a new file whenever the signing certificate changes.

Fixes: [`saml_signature_invalid`](/errors/saml_signature_invalid/), [`saml_issuer_mismatch`](/errors/saml_issuer_mismatch/)

</li>

<li class="idp-step">

<a id="test"></a>

### Test the connection

Run a test sign-in in this setup, signing in as a user you assigned to the app.

</li>

</ol>

<a id="standby"></a>

## Optional: add the standby ACS URL

If our main network ever has an outage, sign-ins can continue through a standby address, but only if your identity provider accepts it. If the app's SAML settings take more than one ACS URL, add `{standby_acs_url}` as a second one and confirm in this setup that you added it. If they take only one, skip this step.

<div class="setup-values">

Paste into Generic SAML:

- Standby ACS URL: `{standby_acs_url}`

</div>

This step is optional. See [standby route behavior](/trust/standby/) for what the standby address does during an outage.

## Sources

- [Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf), read on 2026-10-29
- [Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf), read on 2026-10-29
