Customize SAML Start, Login, Logout, and Error Pages

You can customize these pages for SAML SSO using external identity providers.

• Identity Provider Login Page—In service provider-initiated SSO, the page where the user is sent for login after trying to access the service provider. The URL for this page must support service provider-initiated SSO and be able to receive SAML requests. Define the URL using the ssoStartPage parameter, or enter a URL in Identity Provider Login URL. If you specify a login page, we recommend that you also specify a logout page.

  You can use the RelayState parameter to control where users are directed after successful login.

• 

  Note If you use the RelayState parameter, maintain its state to send back to the service provider, as recommended in the SAML 2.0 specification. For example, if your identity provider modifies the RelayState, such as with URL-decoding, the identity provider must echo back the original RelayState to the service provider. Re-encode the relay state before returning it.
• Custom Logout Page—The page the user is redirected to when they click the Logout button or when the user’s session expires. To control where the user is redirected, specify a URL for the logout page in Custom Logout URL.

  The default logout page is https://MyDomainName.my.salesforce.com.

  Or if you configure single logout, specify a logout page in Identity Provider Single Logout URL.

• Custom Error Page (optional)— The page the user is redirected to if a SAML login error occurs. Specify an error page in Custom Error URL. The error page must be publicly accessible, like a public site Visualforce page. The URL can be absolute or relative.

You can set these values when setting up SSO. Here’s the order of precedence.

1. Session cookie. If you already logged in to Salesforce and a cookie still exists, SSO uses the login and logout pages specified by the session cookie.
2. Values passed in from the identity provider.
3. Values specified on the Single Sign-On Settings Setup page.

If you decide not to specify these values on the Single-Sign-On Settings Setup page, share them with your identity provider. The identity provider uses these values in either the login URL or the SAML assertion.

• ssoStartPage–The page that the user is redirected to when trying to log in. This value is the SAML identity provider’s login page. The user is directed to this page when requesting a protected resource in Salesforce without an active session.
• startURL–The URL to direct the user to when SSO completes successfully. The URL can be absolute, for example, https://yourInstance.salesforce.com/001/o. Or it can be relative, for example, /001/o.

  You can also use the RelayState parameter to control where users are redirected after a successful login. If you use the RelayState parameter, make sure that you maintain its state to send back to the service provider, as recommended in the SAML 2.0 specification. For example, if your identity provider modifies the relay state, such as with URL-decoding, the identity provider must echo back the relay state to the service provider. Reencode the relay state before returning it.

• logoutURL–The URL where you want the user to be directed when they click the Logout button in Salesforce. The default is https://salesforce.com.

Here’s an example of an <AttributeStatement> that contains both the ssoStartPage and logoutURL:

<saml:AttributeStatement>
   <saml:Attribute Name="ssoStartPage" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">
              http://www.customer.org
      </saml:AttributeValue>
   </saml:Attribute>

   <saml:Attribute Name="logoutURL" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
              https://www.salesforce.com
      </saml:AttributeValue>
   </saml:Attribute>
</saml:AttributeStatement>