WorkOS Docs Homepage
Single Sign-On

Login Flows

Learn the differences between SP‑initiated and IdP‑initiated SSO.

The instructions in the Quick Start guide focus on setting up Service Provider (SP)-initiated SSO. In these scenarios, when a user attempts to login, they navigate to an application (a service provider) and are then redirected to the Identity Provider (IdP) for authentication, via the WorkOS API.

Alternatively, most users are able to start the process from the Identity Provider itself. Enterprise companies will often provide an IdP dashboard where employees can select any of the eligible applications that they can access via the IdP, similar to the screenshot below. Clicking on a tile results in an IdP-initiated login flow, since the user initiates the login from the Identity Provider, not the application.

With an SP-initiated login flow, the user begins the authentication process from your application. You can control where the user will be redirected after login by specifying the redirectURI parameter when making the Get Authorization URL call. Additionally, this call can take an optional state parameter - this parameter will be returned in the callback after authentication, where your application can use it to verify the validity of the response or to pass any state from the originating session. One common practice is to route requests from different Organizations to a single Redirect URI, but instead utilize the state parameter to deep link users into the application after the authentication is completed.

Get Authorization URL Call

If you follow the instructions in the Quick Start guide, IdP-initiated login flows will automatically be available, and users will be able to find a tile for your application within their IdP, similar to the screenshot above. Clicking on the tile will will send an IdP-initiated SSO response to your application's callback endpoint.

IdP-initiated authentication is inherently more exposed to security vulnerabilities since the IdP delivers an SSO response to your application (the Service Provider) that the Service Provider had not initiated. There is no way for the application to definitively determine that these unsolicited responses have not been issued or compromised by an attacker, which exposes IdP-initiated SSO to potential CSRF Login and other “man-in-the-middle” attacks. As a result, WorkOS recommends using SP-initiated authentication whenever possible.

Additionally, since IdP-initiated flows do not generate a customized authorization URL the way SP-initiated flows do, there is no way to dynamically pass the redirectURI and state parameters to your application's callback. IdP administrators could configure such parameters via the default RelayState that the IdP will send with its requests, however, WorkOS does not currently support processing a RelayState for IdP-initiated authentication flows, so it should be left blank. If a RelayState is received, the request will result in an error. Consequently, upon a successful IdP-initiated login, the user will always be redirected to the default Redirect URI from your WorkOS configuration.

While there is no unique redirectURI or state parameter that can be used to route the requests, you will have access to the Profile object for the user, which your application can retrieve once authentication is completed.

Example Profile

The Profile object includes the connection_id which identifies the connection that the profile is associated with in WorkOS. We recommend using the connection information for routing requests in an IdP-Initiated flow.

We have recently added Beta support for reading the redirectURI from the RelayState during an IdP-initiated SSO request. This allows an IdP administrator to configure the location where users will be redirected after a successful IdP-initiated authentication request. WorkOS will retrieve the Redirect URI from the IdP’s default RelayState, where it must be configured in the format of a URL parameter: redirect_uri=[uri]. The URI must be one of the Redirect URIs specified in your WorkOS Dashboard, otherwise, the request will result in an error. Any other values in the IdP’s RelayState will be ignored and discarded.

RelayState support for IdP-initiated authentication is currently in invite-only beta, please reach out to WorkOS support if you’d like to use it or learn more about it.

We have recently added Beta support for fully disabling IdP-initiated SSO logins for a connection. Once disabled, any attempted IdP-initiated requests will fail with an idp_initiated_sso_disabled error.

Disabling IdP-initiated SSO is currently in invite-only beta, please reach out to WorkOS support if you’d like to use it or learn more about it.

For applications that need to support IdP-initiated workflows, but would like to mitigate the security risks of unsolicited SAML responses, WorkOS recommends the following:

  • Disable IdP-initiated SSO for your connection.
  • Adjust your callback method to capture the idp_initiated_sso_disabled error.
  • Start a new SP-initiated request from the callback when the error is detected.

The error callback will include the connection and organization ID’s, which can be used to request a new authorization URL for the SP-initiated request. The new request will generally be transparent to the user, as they are already logged in to the Identity Provider.