Customize SAML Assertions

You can customize your SAML assertions as well as the SAML and WS-Federation protocol parameters.

Auth0 as identity provider

Customize SAML assertions when Auth0 acts as the identity provider by configuring the addon in the Dashboard or by using rules.

Use the Dashboard

Go to Dashboard > Applications > Applications and select the name of the application to view.
Select the Addons tab.
Enable SAML2 Web App toggle to view settings and options.
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

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');
	}
};

Was this helpful?

Example: Include user_metadata attributes in an assertion

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);
};

Was this helpful?

SAML assertion attributes

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

Attribute	Type	Description
`audience`	string	Audience of the SAML assertion. Default is issuer on SAMLRequest.
`recipient`	string	Recipient of the SAML assertion (`SubjectConfirmationData`). Default is `AssertionConsumerUrl` on SAMLRequest or callback URL if no SAMLRequest was sent.
`issuer`	string	Unique identifier of the SAML identity provider, formatted as a URL.
`mappings`	object	Mappings between Auth0 profile and the output attributes on the SAML assertion. Default mapping is shown above.
`createUpnClaim`	boolean	Whether or not a UPN claim should be created. Default is `true`.
`passthroughClaimsWithNoMapping`	boolean	If `true` (default), for each claim that is not mapped to the common profile, Auth0 passes through those in the output assertion. If `false`, those claims won't be mapped.
`mapUnknownClaimsAsIs`	boolean	If `passthroughClaimsWithNoMapping` is `true` and this is `false` (default), for each claim not mapped to the common profile Auth0 adds a prefix `http://schema.auth0.com`. If `true` it will pass through the claim as-is.
`mapIdentities`	boolean	If `true` (default), it adds more information in the token such as the provider (Google, ADFS, AD, etc.) and the access token, if available.
`signatureAlgorithm`	string	Signature algorithm to sign the SAML assertion or response. Default is `rsa-sha1`.
`digestAlgorithm`	string	Digest algorithm to calculate digest of the SAML assertion or response. Default is `sha1`.
`destination`	object	Destination of the SAML response. If not specified, it will be `AssertionConsumerUrl` of SAMLRequest or callback URL if there was no SAMLRequest.
`lifetimeInSeconds`	integer	Expiration of the token. Default is `3600` seconds (1 hour).
`signResponse`	boolean	Whether or not the SAML response should be signed. By default the SAML assertion will be signed, but not the SAML response. If `true`, SAML Response will be signed instead of SAML assertion.
`nameIdentifierFormat`	string	Default is `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`.
`nameIdentifierProbes`	array	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 `Subject/NameID`. The order is: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (mapped from user_id)`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress (mapped from email)`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` (mapped from name).
`authnContextClassRef`	string	Default is `urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified`.
`typedAttributes`	boolean	Default is `true`. When set to `true`, we infer the `xs:type` of the element. Types are `xs:string`, `xs:boolean`, `xs:double` and `xs:anyType`. When set to `false` all `xs:type` are `xs:anyType`.
`includeAttributeNameFormat`	boolean	Default is `true`. When set to `true`, we infer the `NameFormat` based on the attribute name. `NameFormat` values are `urn:oasis:names:tc:SAML:2.0:attrname-format:uri`, `urn:oasis:names:tc:SAML:2.0:attrname-format:basic` and `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`. If set to `false`, the attribute `NameFormat` is not set in the assertion.
`logout`	object	Controls SAML logout. It can contain two properties:`callback` (string) that contains the service provider (client application) Single Logout Service URL, where Auth0 will send logout requests and responses, and `slo_enabled`(boolean) that controls whether Auth0 should notify service providers of session termination. The default value is`true` (notify service providers).
`binding`	string	Optionally indicates the protocol binding used for SAML logout responses. By default Auth0 uses `HTTP-POST`, but you can switch to `HTTP-Redirect` by setting `"binding"` to `"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"`.
`signingCert`	string	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 `"-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"`.

Authenticate