# SSO simulator
After implementing Single Sign-On using our [Quickstart guide](/authenticate/sso/add-modular-sso/), you need to validate your integration for all possible scenarios. This guide shows you how to test your SSO implementation using two approaches:
1. **SSO 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 SSO 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 SSO Simulator Quick testing
The SSO 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 SSO 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 SSO Simulator.
```javascript title="Express.js" wrap
// 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 SSO Simulator
const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options);
// Redirect user to start SSO flow
res.redirect(authorizationURL);
```
```python title="Flask" wrap
# Use your test organization ID from the dashboard
options = {
"organizationId": 'org_32656XXXXXX0438' # Replace with your test organization ID
}
# Generate Authorization URL that redirects to SSO Simulator
authorization_url = scalekit_client.get_authorization_url(
redirect_url,
options,
)
# Redirect user to start SSO flow
return redirect(authorization_url)
```
```go title="Gin" wrap
// 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 SSO Simulator
authorizationURL := scalekitClient.GetAuthorizationUrl(
redirectUrl,
options,
)
// Redirect user to start SSO flow
c.Redirect(http.StatusFound, authorizationURL)
```
```java title="Spring Boot" wrap
// 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 SSO 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 SSO 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 SSO 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](/sso/guides/idp-init-sso) before testing this scenario.
#### Test IdP-initiated SSO flow
1. Generate the authorization URL using your test organization
2. When redirected to the SSO 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 SSO 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 SSO 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](/sso/reference/sso-integration-errors/) to implement comprehensive error handling in your application.
## Testing with real identity providers Production-ready
After validating your SSO implementation with the SSO 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](/guides/integrations/sso-integrations/okta-saml/)
- [Microsoft Entra ID integration guide](/guides/integrations/sso-integrations/azure-ad-saml/)
- [Other SSO integrations](/guides/integrations/)
**Customize the admin portal:** You can [customize the Admin Portal](/guides/admin-portal/#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](/sso/guides/authorization-url/))
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](/sso/guides/idp-init-sso/).
**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](/sso/reference/sso-integration-errors/) 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](/sso/guides/launch-checklist/) to ensure production readiness
2. Configure the [Admin Portal](/guides/admin-portal/) for your customers to self-serve SSO setup
3. Implement [custom domain](/guides/custom-domain/) for a seamless branded experience
4. Set up [webhooks](/authenticate/implement-workflows/implement-webhooks/) to receive real-time authentication events