Problem Statement
This document provides additional information about IdP-initiated sign-in flows, specifically when Auth0 is configured as the SAML SP. Auth0 is acting as the SAML SP if it is configured as a connection. If an application is configured with the “SAML2 Web App Addon” then Auth0 is acting as the SAML IdP and this document does not apply.
Definitions:
IdP: Identity Provider
SP: Service Provider
OIDC: OpenID Connect
SAML: Security Assertion Markup Language
IdP-initiated sign-in flows are sometimes referred to as “unsolicited” because the user never visits the application until they have already interacted with the IdP.
IdP-initiated sign-in flows offer less security than SP-initiated sign-in flows and are not recommended.
A common pattern is to use Auth0 to enable an OIDC application to work with a SAML IdP. This poses a special challenge for OIDC applications as OpenID Connect (OIDC) does not support the concept of an IdP-Initiated flow. So while Auth0 offers the possibility of translating a SAML IdP-Initiated flow (from a SAML connection) into an OIDC response for an application, any application that properly implements the OIDC/OAuth2 protocol will reject an unsolicited response. Auth0 strongly recommends starting login flow at the application in all cases (e.g. a portal can simply link to the application /login endpoint directly instead of starting sign-in at the IdP). If this is impossible, please reference the following document for a workaround:
Steps to Reproduce
A generic IdP-initiated SAML flow is shown in the following sequence diagram
Note the following:
- As the name implies, the user begins the sign-in flow by requesting a URL at the SAML IdP.
- The application is not involved in the sign-in process
- The SAML SP isn’t even involved until (5) above.
- When configuring a SAML connection on the Auth0 dashboard, the settings on the “IdP-initiated SSO” tab only affect the behavior starting at (6) above.
The IdP-initiated SSO Tab
As shown in the generic case sequence diagram in the previous section, the response from Auth0 in an IdP-initiated flow depends on the configuration in this section.
Because the user interacts with the SAML IdP first, the SAML SP has no context for the login transaction. The connection must be configured to redirect the user to the correct application, with the appropriate response, after sign-in. There are two critical pieces of information:
- Which application to redirect to
- What kind of response the application expects
Configuration
Under Default Application, select the application to which Auth0 should redirect users after they sign in.
Under Response Protocol, select the response type the application expects. For most use cases, this is OIDC.
By default, users will be redirected with the appropriate response to the first URL in the list of “Allowed Callback URLs” in the applications settings, with a somewhat generic response. There might be two problems with the defaults:
- The first URL in the list isn’t where the response should be sent
- The response should be different than what the defaults provide.
The solution in either case depends on if the response type is SAML/WS-Fed or OIDC.
OIDC: The Query String setting takes most of the same arguments as requests to the /authorize endpoint. The most commonly used parameters here are redirect_uri and scope. For example, to redirect to a particular URL and request specific scopes. use the following Query String:
redirect_uri=https%3A%2F%2Fexample.com%2Fstartlogin&scope=openid profile email
redirect_uri should be URL-encoded, and it must be present in the list of “Allowed Callback URLs” in the corresponding application (the URL should not be encoded when added to the list of Allowed Callback URLs).
SAML: Enable the SAML2 Web App Addon in the Addons tab of the application (the application selected in the “Default Application” list above). Configure a specific callback URL in the Addon, or attributes and other properties of the SAML response. See Manually configure SSO integrations
WS-Fed: Enable the WS-FED Web App Addon in the Addons tab of the application (the application selected in the “Default Application” list above). Configure a specific callback URL in the Addon.
Troubleshooting
The following are common causes of login failures that occur after step (5) in the SAML sequence diagram above:
- The application may not support IdP-initiated logins (see TODO)
- The application expects an access_token in JWT format (see TODO)
- The idp-initiated configuration is incorrect (wrong application, wrong redirect_uri, disallowed redirect_uri, wrong response protocol)
- The application expects specific information in the SAML response or id_token (See Customize SAML Assertions or use an action to set custom claims in the id_token )
The following are common causes of login failures that occur on or before step (5) in the SAML sequence diagram above:
- Incorrect metadata exchange (wrong certificate, certificate in wrong format, expired certificate)
- Incorrect ACS URL configured on the IdP
- Incorrect “Single Sign on URL” configured on the Auth0 SAML connection
- The application configuration (on the auth0 applications tab or the application itself) is definitively not a factor for idp-initiated SAML flows that fail on or before step (5).
A common failure is illustrated below:
The workaround for this failure is covered here.