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

  1. Go to Dashboard > Applications > Applications 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.

    Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab

  4. In the Settings tab, you can make several types of customizations, such as:

    1. Specify an audience other than the default issuer of the SAML request.

    2. Specify a recipient.

    3. Map profile attributes to specific attribute statements.

    4. Change the signature or digest algorithm.

    5. Specify whether just the assertion or the entire response should be signed.

Use rules

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

The context.samlConfiguration.mappings object is used to override default SAML attributes or add new attributes. The object keys are the name of the SAML attribute to override or add and the values are a string of the user object property to use as the attribute value.

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

function (user, context, callback) {
  // change SAML token lifetime to 10 hours
  context.samlConfiguration.lifetimeInSeconds = 36000;

  // if available, use upn as NameID
  if (user.upn) {
    context.samlConfiguration.mappings = {
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier": "upn" // use user.upn as the value
    }
  }

  callback(null, user, context);
}

Example: Include user_metadata attributes in an assertion

function (user, context, callback) {
  user.user_metadata = user.user_metadata || {};
  user.user_metadata.color = "purple";
  context.samlConfiguration.mappings = {
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/color": "user_metadata.color", // use user.user_metadata.color as the value
  };
  callback(null, user, context);
}

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.
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. It can also be rsa-sha256.
digestAlgorithm string Digest algorithm to calculate digest of the SAML assertion or response. Default is sha1. It can also be sha256.
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 istrue (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 PUBLIC KEY-----\nMIGf...bpP/t3\n+JGNGIRMj1hF1rnb6QIDAQAB\n-----END PUBLIC KEY-----\n".

Learn more