> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Auth0 as a SAML Service Provider
> Learn how to configure Auth0 to serve as a service provider in a SAML federation.
To configure Auth0 as the service provider (SP) in a SAML federation, you will need to create an Enterprise connection in Auth0 and then update your SAML identity provider (IdP) with the connection's metadata.
Auth0 supports using Auth0 as the SP in configurations that conform to the SAML 1.1 or SAML 2.0 protocol.
## Get metadata and certificate from the IdP
You'll need to collect some configuration metadata from the IdP to create a connection in Auth0:
| Field | Description |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sign In URL | The URL where SAML authentication requests are sent. This is also called the single sign-on (SSO) endpoint. |
| Sign Out URL | The URL where SAML logout requests are sent. This is also called the single logout (SLO) endpoint. |
| X509 Signing Certificate | The public-key certificate required by the SP to validate the signature of the authentication assertions that have been digitally signed by the IdP. Auth0 accepts the .pem and .cer formats. |
## Create SAML Enterprise connection in Auth0
You can create a SAML Enterprise connection in the Auth0 Dashboard or with the Auth0 Management API:
1. Go to [**Dashboard > Authentication > Enterprise**](https://manage.auth0.com/#/connections/enterprise/samlp) and select **SAML**.
2. Select **Create Connection**.
3. Configure the following settings:
| Setting | Description |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connection Name | Enter a connection name such as `SAML-SP`. |
| Sign In URL | Enter the **Sign In URL** that you obtained from the IdP. |
| X509 Signing Certificate | Upload the X509 Signing Certificate file (in `.pem` or `.cer` format) that you obtained from the IdP. |
| Enable Sign Out | Enable the **Sign Out URL** field. |
| Sign Out URL | Enter the **Sign Out URL** obtained from the IdP. |
| User ID Attribute | Enter the attribute in the SAML token that will be mapped to the `user_id` property in Auth0. If not set, then the `user_id` will be retrieved from the following (in listed order):- `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier`
- `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn`
- `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
|
| Debug Mode | Enable **Debug Mode** for more verbose logging. |
| Sign Request | Enable signed SAML authentication requests. |
| Sign Request Algorithm | From the dropdown menu, select the hash algorithm to use. |
| Sign Request Algorithm Digest | From the dropdown menu, select the algorithm to use to check the validity of the assertion. |
| Protocol Binding | From the dropdown menu, select one of the following options:- `HTTP-Redirect`: Enables messages to be transmitted within URL parameters.
- `HTTP-POST`: Enables messages to be transmitted within an HTML form.
|
| Sync user profile attributes at each login | Enable syncing user profile attributes during each login. |
4. Select **Create**.
The Auth0 Management API [Create a Connection](https://auth0.com/docs/api/management/v2#!/Connections/post_connections) endpoint supports the following properties on the `options` object when creating a SAML connection:
| Field | Type | Required? | Description |
| -------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signInEndpoint` | String | Required | The **Sign In URL** of the IdP. |
| `signingCert` | String | Required | Contents of the X509 signing certificate (in `.pem` or `.cer` format) encoded in Base64. |
| `debug` | Boolean | Optional | Toggles **Debug Mode**, which includes more verbose logging during the authentication process. Set to `false` for connections used in production environments. |
| `destinationUrl` | String | Optional | The URL where Auth0 will send SAML authentication requests. Only required when using a proxy gateway. |
| `digestAlgorithm` | String | Optional | The algorithm used to encrypt the digest element of authentication requests.
Accepted values are `sha256` and `sha1`. |
| `disableSignout` | Boolean | Optional | Toggles the **Sign Out URL**. If `false`, you must provide a **Sign Out URL** to accept logout requests. If `true`, logout requests will be sent to the **Sign In URL**. |
| `fieldsMap` | Object | Optional | Contains attribute mappings to be applied to the authentication responses from the IdP.
For example: `"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`. |
| `idpinitiated` | Object | Optional | Contains options for IdP-Initiated SSO:- `enabled`: Boolean. Toggles IdP-Initiated SSO.
- `client_id`: String. The client ID of the default application.
- `client_protocol`: String. The response protocol used to communicate with the default application. Accepted values are `oauth2`, `samlp`, and `wsfed`.
- `client_authorizequery`: String. The query string sent to the default application.
|
| `protocolBinding` | String | Optional | The protocol binding used for authentication requests.
Accepted values are:- `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect`
- `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST`
|
| `recipientUrl` | String | Optional | The URL where the IdP will send SAML authentication responses. Only required when using a proxy gateway. |
| `signatureAlgorithm` | String | Optional | The algorithm used to sign authentication requests.
Accepted values are `rsa-sha256` and `rsa-sha1`. |
| `signSAMLRequest` | Boolean | Optional | Toggles the signing of authentication requests sent by Auth0. |
| `user_id_attribute` | String | Optional | The name of the attribute in the authentication responses to map to the User ID property. This field will supersede any mappings for the `user_id` property in the `fieldsMap` object. |
#### Example request
```json lines expandable theme={null}
{
"strategy": "samlp",
"name": "example-samlp-connection",
"options": {
"signingCert": "{X509_CERTIFICATE_IN_BASE64}",
"signInEndpoint": "https://example.com/samlp/login",
"disableSignout": false,
"signOutEndpoint": "https://example.com/samlp/logout",
"fieldsMap": {
"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"user_id": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"address_name": "http://schemas.auth0.com/address_name",
"address_street_address": "http://schemas.auth0.com/address_street_address"
},
"user_id_attribute": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"idpinitiated": {
"enabled": true,
"client_id": "{DEFAULT_APPLICATION_CLIENT_ID}",
"client_protocol": "oauth2",
"client_authorizequery": "response_type=code&scope=openid email profile"
},
"signSAMLRequest": true,
"signatureAlgorithm": "rsa-sha256",
"digestAlgorithm": "sha256",
"protocolBinding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
"debug": true
}
}
```
### Configure SAML connection for proxy gateways
If you have Auth0 behind a proxy gateway, you’ll need to configure the SAML connection’s `destinationUrl` and `recipientUrl` fields accordingly.
1. Get your SAML connection's current configuration with the Management API [Get a connection](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) endpoint.
2. Copy the value of the `options` object from the returned response.
3. Add the following fields to the `options` object:
| Field | Type | Value |
| ---------------- | ------ | ------------------------- |
| `destinationUrl` | String | URL of the proxy gateway. |
| `recipientUrl` | String | URL of the proxy gateway. |
4. Call the Management API [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint with the entire updated `options` object in the request body.
### Customize the request template
When Auth0 sends the authentication request to the IdP, the request body contains an `AuthnRequest` object. You can customize the template used for this object:
1. Go to [Dashboard > Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp), and select your connection.
2. Switch to the **Settings** view, and locate the **Request Template** field.
3. Modify the template.
4. Select **Save Changes**.
#### Template variables
Variables can be placed into the `AuthnRequest` template using the `@@VariableName@@` syntax. The following variables are available:
| Name | Description |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AssertionConsumerServiceURL` | The URL where the IdP sends the response after the user signs in. Include the `ProtocolBinding` attribute in the request template if you use this. |
| `Connection.` | Use dot notation on the `Connection` key to access any of the connection's `options` values as returned from the Auth0 Management API's [Get a Connection](https://auth0.com/docs/api/management/v2/#!/Connections/get_connections_by_id) endpoint. For example, if the connection has `options.some_property: "value"`, then you can use `@@Connection.some_property@@` in the template. |
| `Destination` | The URL where Auth0 sends the request. This should be the **Sign In URL** configured for the connection. |
| `ID` | The transaction ID. |
| `IssueInstant` | The transaction date timestamp. |
| `Issuer` | The entity ID of the SP in `urn` format.
For example, `urn:auth0::`. |
| `LoginHint` | The username or email of the user logging in. If you are using [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first), Auth0 can send this value to the IdP to pre-populate it in the IdP's login form. |
| `ProtocolBinding` | The protocol [binding type](https://www.ibm.com/support/knowledgecenter/en/SSPREK_9.0.4/com.ibm.isam.doc/config/concept/fed_SAML20_bindings.html). |
| `ProviderName` | The name of the application that initiated the request. This always returns the Auth0 tenant name. |
| `AssertServiceURLAndDestination` | Deprecated. For new configurations, use `AssertionConsumerServiceURL` and `Destination` instead. |
## Configure the IdP
Go to [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings) to find the metadata you'll need to provide to the IdP.
Auth0 supports all SAML IdPs that conform to the SAML 1.1 or SAML 2.0 protocol. We have detailed instructions for configuring specific providers below.
## Test connection
To test your connection in the Dashboard:
1. Go to [Dashboard > Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp).
2. Locate the connection you created, select the **...** (three dots) menu icon, and select **Try**.
3. A Universal Login Page will appear and prompt you to enter credentials.
4. Enter the email address of a user who exists in the IdP. If you configured [Home Realm Discovery](/docs/authenticate/login/auth0-universal-login/identifier-first#define-home-realm-discovery-identity-providers), make sure you enter an email address that uses one of the specified domains.
5. After you are redirected to the login screen for the IdP, log in as you normally would.
6. You will be redirected to a page on Auth0 that displays the contents of the authentication assertion sent to Auth0 from the IdP.
## Troubleshoot connection
If your connection is not working as expected, try the following steps:
* Clear your browser history, cookies, and cache before each test. If you do not, the browser may not pick up the latest configuration information, or it may have stale cookies that affect execution.
* Ensure that your browser allows cookies and has JavaScript enabled.
* [Capture a HAR file](https://support.auth0.com/center/s/article/generate-and-analyze-har-files-to-troubleshoot-auth0-issues) of the transaction, and then use the [Auth0 SAML Tool](http://samltool.io/) to decode the SAML assertion and inspect its contents.