IdP-initiated authentication is inherently more exposed to security vulnerabilities since the IdP delivers an SSO response to 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.

The instructions in this guide will allow the Identity Provider to issue IdP-initiated SSO calls to your application's callback endpoint. IdP administrators can configure the RelayState that the IdP will send with these requests. Currently, however, WorkOS does not 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. Upon a successful request, the user will be redirected to the default redirect URI in the WorkOS configuration.

We have recently added Beta support for reading the redirect_uri from the RelayState during an IdP-initiated SSO request. This allows an IdP administrator to configure the location where user will be redirected after a successful IdP-initiated authentication request. WorkOS will retrieve the redirect URI from the IdP's 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.

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.

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.

const express = require('express');
const { WorkOS } = require('@workos-inc/node');
const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;
app.get('/callback', async (req, res) => {
  const { code, error, connection_id } = req.query;
  if (error === 'idp_initiated_sso_disabled') {
    const redirectURI = 'https://dashboard.my-app.com/'; // The callback URI WorkOS should redirect to post-authentication
    const state = 'state=param'; // The state parameter to be returned to the callback for additional security
    const authorizationURL = workos.sso.getAuthorizationURL({
      clientID: clientID,
      redirectURI: redirectURI,
      state: state,
      connection: connection_id,
    });
    res.redirect(authorizationURL);
  } else if (!error) {
    const { profile } = await workos.sso.getProfileAndToken({
      code,
      clientID,
    });
    // Use the information in `profile` for further business logic.
    res.redirect('/');
  }
});