> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-quickstart-revamp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Describes how to customize SAML assertions and the SAML and WS-Fed protocol parameters.

# Customize SAML Assertions

You can customize your <Tooltip tip="Security Assertion Markup Language (SAML): Standardized protocol allowing two parties to exchange authentication information without a password." cta="View Glossary" href="/docs/glossary?term=SAML">SAML</Tooltip> assertions as well as the SAML and WS-Federation protocol parameters.

## Auth0 as identity provider

Customize SAML assertions when Auth0 acts as the <Tooltip tip="Identity Provider (IdP): Service that stores and manages digital identities." cta="View Glossary" href="/docs/glossary?term=identity+provider">identity provider</Tooltip> by configuring the addon in the Dashboard or by using rules.

### Use the Dashboard

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications/\{yourClientId}/addons) and select the name of the application to view.
2. Select the **Addons** tab.
3. Enable **SAML2 Web App** toggle to view settings and options.

   <Frame>
     <img src="https://mintcdn.com/docs-staging-quickstart-revamp/0yzvW89mU3tfXF-c/images/cdy7uua7fh8z/6dJgYkcOgMZ73HVTkAWt1x/fe9dbbf306e6c587cb3326c00a3b4e1f/2025-02-27_13-59-00.png?fit=max&auto=format&n=0yzvW89mU3tfXF-c&q=85&s=4031fdf3a4e9a576e20770db398498e6" alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" width="606" height="757" data-path="images/cdy7uua7fh8z/6dJgYkcOgMZ73HVTkAWt1x/fe9dbbf306e6c587cb3326c00a3b4e1f/2025-02-27_13-59-00.png" />
   </Frame>
4. In the **Settings** tab, you can make several types of customizations, such as:

   * Specify an audience other than the default issuer of the SAML request.
   * Specify a recipient.
   * Map profile attributes to specific attribute statements.
   * Change the signature or digest algorithm.
   * Specify whether just the assertion or the entire response should be signed.

### Use Actions

You can use Actions to add more extensive or dynamic customizations to the SAML response. Customizations made in Actions override customizations done using the **Application Addons** view in the Dashboard.

The `api.samlResponse` object is used to override default SAML attributes or add new attributes.

#### Example: Changing the SAML token lifetime and use UPN as NameID

```js lines
exports.onExecutePostLogin = async (event, api) => {
	api.samlResponse.setLifetimeInSeconds(36000);
	if (event.user.upn) {
		api.samlResponse.setAttribute('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier', 'upn');
	}
};
```

#### Example: Include user\_metadata attributes in an assertion

```js lines
exports.onExecutePostLogin = (event, api) => {
	event.user.user_metadata = event.user.user_metadata || {};
	event.user.user_metadata.color = 'purple';
	api.samlResponse.setAttribute('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/color', event.user.user_metadata.color);
};
```

## SAML assertion attributes

The following is a list of customization attributes for SAML assertions.

<table class="table">
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>audience</code></td>
      <td>string</td>
      <td>Audience of the SAML assertion. Default is issuer on SAMLRequest.</td>
    </tr>

    <tr>
      <td><code>recipient</code></td>
      <td>string</td>
      <td>Recipient of the SAML assertion (<code>SubjectConfirmationData</code>). Default is <code>AssertionConsumerUrl</code> on SAMLRequest or callback URL if no SAMLRequest was sent.</td>
    </tr>

    <tr>
      <td><code>issuer</code></td>
      <td>string</td>
      <td>Unique identifier of the SAML identity provider, formatted as a URL.</td>
    </tr>

    <tr>
      <td><code>mappings</code></td>
      <td>object</td>
      <td>Mappings between Auth0 profile and the output attributes on the SAML assertion. Default mapping is shown above.</td>
    </tr>

    <tr>
      <td><code>createUpnClaim</code></td>
      <td>boolean</td>
      <td>Whether or not a UPN claim should be created. Default is <code>true</code>.</td>
    </tr>

    <tr>
      <td><code>passthroughClaimsWithNoMapping</code></td>
      <td>boolean</td>
      <td>If <code>true</code> (default), for each claim that is not mapped to the common profile, Auth0  passes through those in the output assertion. If <code>false</code>, those claims won't be mapped.</td>
    </tr>

    <tr>
      <td><code>mapUnknownClaimsAsIs</code></td>
      <td>boolean</td>
      <td>If <code>passthroughClaimsWithNoMapping</code> is <code>true</code> and this is <code>false</code> (default), for each claim not mapped to the common profile Auth0 adds a prefix <code>[http://schema.auth0.com](http://schema.auth0.com)</code>. If <code>true</code> it will pass through the claim as-is.</td>
    </tr>

    <tr>
      <td><code>mapIdentities</code></td>
      <td>boolean</td>
      <td>If <code>true</code> (default), it adds more information in the token such as the provider (Google, ADFS, AD, etc.) and the access token, if available.</td>
    </tr>

    <tr>
      <td><code>signatureAlgorithm</code></td>
      <td>string</td>
      <td>Signature algorithm to sign the SAML assertion or response. Default is <code>rsa-sha1</code>.</td>
    </tr>

    <tr>
      <td><code>digestAlgorithm</code></td>
      <td>string</td>
      <td>Digest algorithm to calculate digest of the SAML assertion or response. Default is <code>sha1</code>.</td>
    </tr>

    <tr>
      <td><code>destination</code></td>
      <td>object</td>
      <td>Destination of the SAML response. If not specified, it will be <code>AssertionConsumerUrl</code> of SAMLRequest or callback URL if there was no SAMLRequest.</td>
    </tr>

    <tr>
      <td><code>lifetimeInSeconds</code></td>
      <td>integer</td>
      <td>Expiration of the token. Default is <code>3600</code> seconds (1 hour).</td>
    </tr>

    <tr>
      <td><code>signResponse</code></td>
      <td>boolean</td>
      <td>Whether or not the SAML response should be signed. By default the SAML assertion will be signed, but not the SAML response. If <code>true</code>, SAML Response will be signed instead of SAML assertion.</td>
    </tr>

    <tr>
      <td><code>nameIdentifierFormat</code></td>
      <td>string</td>
      <td>Default is <code>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</code>.</td>
    </tr>

    <tr>
      <td><code>nameIdentifierProbes</code></td>
      <td>array</td>
      <td>Auth0 will try each of the attributes of this array in order. If one of them has a value, it will use that for the <code>Subject/NameID</code>. The order is: <code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) (mapped from user\_id)</code>, <code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress) (mapped from email)</code>, <code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)</code> (mapped from name).</td>
    </tr>

    <tr>
      <td><code>authnContextClassRef</code></td>
      <td>string</td>
      <td>Default is <code>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</code>.</td>
    </tr>

    <tr>
      <td><code>typedAttributes</code></td>
      <td>boolean</td>
      <td>Default is <code>true</code>. When set to <code>true</code>, we infer the <code>xs:type</code> of the element. Types are <code>xs:string</code>, <code>xs:boolean</code>, <code>xs:double </code>and <code>xs:anyType</code>. When set to <code>false</code> all <code>xs:type</code> are <code>xs:anyType</code>.</td>
    </tr>

    <tr>
      <td><code>includeAttributeNameFormat</code></td>
      <td>boolean</td>
      <td>Default is <code>true</code>. When set to <code>true</code>, we infer the <code>NameFormat</code> based on the attribute name. <code>NameFormat</code> values are <code>urn:oasis:names:tc:SAML:2.0:attrname-format:uri</code>, <code>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</code> and <code>urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified</code>. If set to <code>false</code>, the attribute <code>NameFormat</code> is not set in the assertion.</td>
    </tr>

    <tr>
      <td><code>logout</code></td>
      <td>object</td>
      <td>Controls SAML logout. It can contain two properties:<code>callback</code> (string) that contains the service provider (client application) Single Logout Service URL, where Auth0 will send logout requests and responses, and <code>slo\_enabled</code>(boolean) that controls whether Auth0 should notify service providers of session termination. The default value is<code>true</code> (notify service providers).</td>
    </tr>

    <tr>
      <td><code>binding</code></td>
      <td>string</td>
      <td>Optionally indicates the protocol binding used for SAML logout responses. By default Auth0 uses <code>HTTP-POST</code>, but you can switch to <code>HTTP-Redirect</code> by setting <code>"binding"</code> to <code>"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"</code>.</td>
    </tr>

    <tr>
      <td><code>signingCert</code></td>
      <td>string</td>
      <td>Optionally indicates the public key certificate used to validate SAML requests. If set, SAML requests will be required to be signed. A sample value would be <code>"-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n\[..all the other lines..]-----END CERTIFICATE-----\n"</code>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors)
* [Configure SAML Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on)