Error handling during single sign-on

Reference of error codes and how to handle them. For step-by-step fixes of the errors developers hit most often while adding Modular SSO, see Troubleshoot Modular SSO.

When users attempt to log in via single sign-on (SSO) using Scalekit, any issues encountered will result in error details being sent to your application’s redirect URI via the error and error_description query parameters. Proper error handling ensures a better user experience.

Scalekit sends an SSO error to the redirect_uri of the sign-in request, the same URL that receives the authorization code on success. The redirect carries error, error_description and the state value from your authorization URL. If the redirect_uri is missing or isn’t one of your registered redirect URLs, Scalekit can’t redirect and shows the user an error page instead.

Errors from IdP-initiated sign-in have no sign-in request to return to, so Scalekit sends them to your initiate-login URL with the same error and error_description parameters.

Errors don’t have a per-connection destination, but you choose the redirect_uri and state on every sign-in request, so your callback knows which organization the user was signing in to. Use that to show an error page that fits the organization and tells its users how to fix the problem.

• Look up the organization from state. When you build the authorization URL, store the organization ID in the user’s server-side session next to the random state value. In your callback, verify state matches, read the organization ID from the session, and render that organization’s error page.
• Or use a redirect URL per organization. Register a separate redirect URL for each organization, such as https://app.example.com/sso/callback/acme, and pass it as redirect_uri on that organization’s sign-in requests.

Keep state unguessable and verify it on every callback, including error callbacks. Don’t put the organization ID in state in place of the random value: state protects the callback from cross-site request forgery.

If there is any issue between Scalekit and your application, the following errors may occur:

invalid_redirect_uri

invalid_connection_selector

no_active_connections

connection_not_active

no_configured_connections

invalid_organization_id

invalid_connection_id

domain_not_found

invalid_user_domain

invalid_client

application_not_active

invalid_request

invalid_idp_initiated_sso

unauthorized

user_not_active

server_error

If SSO configuration issues arise, you will encounter the following errors:

mandatory_attribute_missing

invalid_id_token

failed_to_exchange_token

user_info_retrieve_failed

invalid_saml_metadata

invalid_saml_response

invalid_in_response_to

invalid_saml_request

invalid_saml_form_params

signature_validation_failed

invalid_acs_url

invalid_assertion_url

invalid_status

malformed_saml_response

assertion_expired

response_expired

authentication_not_completed

user_login_required

These errors come from exchanging the code for the user’s profile, not from the redirect to your callback URL. The SDK throws an error that carries Scalekit’s JSON response, such as {"error":"invalid_grant","error_description":"invalid code"}.

invalid_grant

invalid_grant

invalid_client

invalid_scope