Test SSO flow

After implementing Single Sign-On using our Quickstart guide, you need to validate your integration for all possible scenarios. This guide shows you how to test your SSO implementation using two approaches:

1. IdP Simulator (quick testing): Test all SSO scenarios without external services. Your development environment includes a pre-configured test organization with an SSO connection to our IdP Simulator.
2. Real identity provider (production-ready testing): Test with actual identity providers like Okta or Microsoft Entra ID to simulate real customer scenarios.

To ensure a successful SSO implementation, test all three scenarios described in this guide before deploying to production: SP-initiated SSO, IdP-initiated SSO, and error handling.

Testing with IdP Simulator Quick testing

The IdP Simulator allows you to test all SSO scenarios without requiring external services. Your development environment includes a pre-configured test organization with an SSO connection to our IdP Simulator and test domains like @example.com or @example.org.

To locate the test organization, navigate to Dashboard > Organizations and select Test Organization.

Service provider (SP) initiated SSO Scenario 1

In this common scenario, users start the Single Sign-On process from your application’s login page.

Generate authorization URL

Generate an authorization URL with your test organization ID. This redirects users to Scalekit’s hosted login page, which will then redirect to the IdP Simulator.

Node.js

Express.js

// Use your test organization ID from the dashboard
const options = {
  organizationId: 'org_32656XXXXXX0438' // Replace with your test organization ID
};

// Generate Authorization URL that redirects to IdP Simulator
const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options);

// Redirect user to start SSO flow
res.redirect(authorizationURL);

Python

Flask

# Use your test organization ID from the dashboard
options = {
    "organizationId": 'org_32656XXXXXX0438'  # Replace with your test organization ID
}

# Generate Authorization URL that redirects to IdP Simulator
authorization_url = scalekit_client.get_authorization_url(
    redirect_url,
    options,
)

# Redirect user to start SSO flow
return redirect(authorization_url)

Go

Gin

// Use your test organization ID from the dashboard
options := scalekit.AuthorizationUrlOptions{
    OrganizationId: "org_32656XXXXXX0438", // Replace with your test organization ID
}

// Generate Authorization URL that redirects to IdP Simulator
authorizationURL := scalekitClient.GetAuthorizationUrl(
    redirectUrl,
    options,
)

// Redirect user to start SSO flow
c.Redirect(http.StatusFound, authorizationURL)

Java

Spring Boot

// Use your test organization ID from the dashboard
AuthorizationUrlOptions options = new AuthorizationUrlOptions();
options.setOrganizationId("org_32656XXXXXX0438"); // Replace with your test organization ID

// Generate Authorization URL that redirects to IdP Simulator
String authorizationURL = scalekitClient
        .authentication()
        .getAuthorizationUrl(redirectUrl, options)
        .toString();

// Redirect user to start SSO flow
return "redirect:" + authorizationURL;

Find your organization ID

Your test organization ID is displayed in the organization details page at Dashboard > Organizations > Test Organization.

Test the SSO flow

After generating the authorization URL, users are redirected to the IdP Simulator:

1. Select User login via SSO from the dropdown menu
2. Enter test user details (email, name, etc.) to simulate authentication
3. Click Submit to complete the simulation

After submitting the form, your application receives an idToken containing the user details you entered:

Custom user attributes

To test custom attributes from the IdP Simulator, first register them at Dashboard > Development > Single Sign-On > Custom Attributes.

Identity provider (IdP) initiated SSO Scenario 2

In this scenario, users start the sign-in process from their identity provider (typically through an applications catalog) rather than from your application’s login page. Your application must handle this flow by detecting IdP-initiated requests and converting them to SP-initiated SSO.

If you haven’t implemented IdP-initiated SSO yet, follow our IdP-initiated SSO implementation guide before testing this scenario.

Test IdP-initiated SSO flow

1. Generate the authorization URL using your test organization
2. When redirected to the IdP Simulator, select IdP initiated SSO from the dropdown menu
3. Enter test user details to simulate the login
4. Click Submit to complete the simulation

Verify callback handling

Your callback handler receives the IdP-initiated request and must process it correctly:

Your application should:

1. Detect the IdP-initiated request based on the request parameters
2. Retrieve connection details (connection_id or organization_id) from Scalekit
3. Generate a new authorization URL to convert the IdP-initiated flow to SP-initiated SSO
4. Complete the authentication flow

Testing notes

• The IdP Simulator uses your default redirect URL as the callback URL. Ensure this is correctly configured at Dashboard > Developers > Redirect URLs.
• In production, users would select your application from their identity provider’s app catalog to initiate this flow.

Error handling Scenario 3

Your application should gracefully handle error scenarios to provide a good user experience. SSO failures can occur due to misconfiguration, incomplete user profiles, or integration issues.

Test error scenarios

1. Generate and redirect to the authorization URL
2. In the IdP Simulator, select Error from the dropdown menu
3. Verify your callback handler processes the error correctly
4. Ensure users see an appropriate error message

Error handling best practices

Review the complete list of SSO integration error codes to implement comprehensive error handling in your application.

Testing with real identity providers Production-ready

After validating your SSO implementation with the IdP Simulator, test with real identity providers like Okta or Microsoft Entra ID to simulate actual customer scenarios. This ensures your integration works correctly with production identity systems.

Setup your test environment

To simulate a real customer onboarding scenario, create a new organization with a real SSO connection:

1. Create an organization at Dashboard > Organizations with a name that reflects a test customer
2. Generate an Admin Portal link from the organization’s overview page
3. Open the Admin Portal link and follow the integration guide to set up an SSO connection:
   • Okta SAML integration guide
   • Microsoft Entra ID integration guide
   • Other SSO integrations

Customize the admin portal

You can customize the Admin Portal with your application’s branding to provide a polished experience for your customers.

Free Okta developer account

If you don’t have access to an identity provider, sign up for a free Okta developer account to test SSO integration.

Service provider (SP) initiated SSO Scenario 1

Test the most common SSO scenario where users start the authentication flow from your application’s login page.

Validate the flow

1. Generate authorization URL: Create an authorization URL with your test organization’s ID (see Authorization URL documentation)
2. User authentication: Verify that Scalekit redirects users to the correct identity provider
3. Callback handling: Confirm your application receives the authorization code at your redirect URI
4. Token exchange: Verify you can exchange the authorization code for user details and tokens
5. Session creation: Ensure your application creates a session and logs the user in successfully

Your application should successfully retrieve user details including email, name, and any custom attributes configured in the SSO connection.

Identity provider (IdP) initiated SSO Scenario 2

Test the scenario where users start authentication from their identity provider’s application catalog.

Validate the flow

1. Initial callback: User is redirected to your default redirect URI with IdP-initiated request parameters
2. Detection logic: Your application detects this as an IdP-initiated request (based on the request parameters)
3. SP-initiated conversion: Your application initiates SP-initiated SSO by generating an authorization URL
4. IdP redirect: User is redirected to the identity provider based on the authorization URL
5. Final callback: After authentication, user is redirected back with an authorization code and state parameter
6. Token exchange: Exchange the code for user details and complete the login

For implementation details, see our IdP-initiated SSO implementation guide.

Default redirect URL configuration

Ensure your default redirect URL is correctly configured at Dashboard > Developers > Redirect URLs. This URL receives IdP-initiated requests.

Error handling Scenario 3

Test how your application handles SSO failures. Common error scenarios include:

• Misconfigured SSO connections (wrong certificates, invalid metadata)
• Incomplete user profiles (missing required attributes)
• Expired or revoked SSO connections
• Network or integration issues with the identity provider

Validate error handling

1. Review the SSO integration error codes documentation
2. Test each applicable error scenario by intentionally misconfiguring your SSO connection
3. Verify your application displays appropriate, user-friendly error messages
4. Ensure errors are logged for debugging purposes
5. Confirm users can retry authentication or contact support

Error logging

Implement comprehensive error logging to help diagnose SSO issues quickly. Include the error code, timestamp, organization ID, and connection ID in your logs.

Next steps

After thoroughly testing your SSO implementation:

1. Review the SSO launch checklist to ensure production readiness
2. Configure the Admin Portal for your customers to self-serve SSO setup
3. Implement custom domain for a seamless branded experience
4. Set up webhooks to receive real-time authentication events