Skip to content

Handle Identity Provider initiated SSO

IdP-initiated SSO allows users to log into your application directly from their identity provider’s portal. The workflow consists of three main steps:

  1. The user logs into their identity provider portal and selects your application
  2. The identity provider sends the user’s details as assertions to your application
  3. Your application validates the assertions, retrieves the user information, and if everything checks out, logs the user in

Scalekit's recommended workflow for IdP initiated SSO

Since the login is initiated from the identity provider’s portal, this flow is called IdP-initiated SSO.

To securely implement IdP-initiated SSO, follow these steps to convert incoming IdP-initiated requests to SP-initiated flows:

  1. Set up a default redirect endpoint: When Scalekit receives an IdP-initiated SSO request, it sends a request to your configured default redirect_uri with an idp_initiated_login parameter.

    Terminal window
    https://{your-subdomain}.scalekit.dev/default-redirect-uri?idp_initiated_login=<encoded_jwt_token>
  2. Extract information from the JWT token: The idp_initiated_login parameter contains a signed JWT with organization, connection, and user details.

    {
    "organization_id": "org_225336910XXXX588",
    "connection_id": "conn_22533XXXXX575236",
    "login_hint": "name@example.com",
    "exp": 1723042087,
    "nbf": 1723041787,
    "iat": 1723041787,
    "iss": "https://b2b-app.com"
    }
  3. Convert to SP-initiated flow: Use the extracted parameters to initiate a new SSO request. Here are implementation examples:

    // 1. Default redirect URL is callback with JWT
    const { code, error_description, idp_initiated_login } = req.query;
    if (error_description) {
    return res.status(400).json({ message: error_description });
    }
    // 2. Decode the JWT
    if (idp_initiated_login) {
    const {
    connection_id,
    organization_id,
    login_hint,
    relay_state
    } = await scalekit.getIdpInitiatedLoginClaims(idp_initiated_login);
    let options = {};
    // Either ONE of the following properties
    options["connectionId"] = connection_id
    options["organizationId"] = organization_id
    options["loginHint"] = login_hint
    // 3. Generate Authorization URL
    const url = scalekit.getAuthorizationUrl(
    <redirect_uri>,
    options
    )
    return res.redirect(url);
    }
  4. Handle errors: If errors occur, the redirect URI will receive a callback with error information. See the error handling guide for more details.

    Terminal window
    https://{your-subdomain}.scalekit.dev/callback
    ?error="<error_category>"
    &error_description="<details>"

If you encounter issues implementing IdP-initiated SSO:

  1. Verify your redirect URI is properly configured in the Scalekit Dashboard
  2. Check that you’re correctly processing the JWT token from the idp_initiated_login parameter
  3. Ensure your error handling properly captures and processes any error messages

The advantages of using Scalekit’s approach are:

  • Enhanced security: Overcomes the security risks of handling IdP-initiated SSO
  • Seamless experience: The additional redirect is almost instantaneous, providing a smooth user experience

While IdP-initiated SSO offers convenience, it comes with significant security risks:

Stolen SAML assertions: Attackers can steal SAML assertions and use them to gain unauthorized access. If an attacker manages to steal these assertions, they can:

  • Inject them into another service provider, gaining access to that user’s account
  • Inject them back into your application with altered assertions, potentially elevating their privileges

With a stolen SAML assertion, an attacker can gain access to your application as the compromised user, bypassing the usual authentication process.

Attackers can steal SAML assertions through various methods:

  • Man-in-the-middle (MITM) attacks: Intercepting and replacing the SAML response during transmission
  • Open redirect attacks: Exploiting improper endpoint validation to redirect the SAML response to a malicious server
  • Leaky logs and headers: Sensitive information, including SAML assertions, can be leaked through logs or headers
  • Browser-based attacks: Exploiting browser vulnerabilities to steal SAML assertions

The chief problem with stolen assertions is that everything appears legitimate to the service provider (your application). The message and assertion are valid, issued by the expected identity provider, and signed with the expected key. However, the service provider cannot verify whether the assertions are stolen or not.