Error handling during single sign-on

Reference of error codes and how to handle them

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.

Integration related errors

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

Tip

Ideally, you would want to catch these errors in the development environments. These errors are not meant to be exposed to your customers in the production environments.

Error	Error description	Possible resolution strategy
invalid_redirect_uri	Redirect URI is not part of the pre-approved list of redirect URIs	Add the valid URL in the Scalekit dashboard before using it
invalid_connection_selector	Missing organization_id (or) connection_id (or) domain (or) provider in the authorization URL	Include at least one of these parameters in the request
no_active_connections	There are no active SSO connections configured to process the single sign-on request	Ensure active SSO connections are set up
connection_not_active	The configured connection is not active	Enable the SSO connection in the Scalekit dashboard
no_configured_connections	No active SSO connections configured	Ensure active SSO connections are set up
invalid_organization_id	Invalid organization ID	Verify and use a valid organization ID
invalid_connection_id	Invalid connection ID	Verify and use a valid connection ID
domain_not_found	No domain specified for the SSO connection(s)	Check domain configuration in Scalekit dashboard
invalid_user_domain	User’s domain not allowed for this SSO connection	Ensure user domain is part of the allowed domains list
invalid_client	The client application is not recognized or not configured correctly	Verify the client_id value in your authorization URL
application_not_active	The application is inactive	Enable the application in the Scalekit dashboard
invalid_request	The authorization request contains invalid or missing parameters	Review the authorization URL parameters
unauthorized	The request is unauthorized	Verify that valid credentials are being used
user_not_active	The user account is inactive	Activate the user account or contact the IT admin
server_error	actual error description from the server	This must be a rare occurrence. Please reach out to us via your private slack channel or via email

SSO configuration related errors

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

Tip

Ideally, these errors should have been caught and handled by your customer’s IT admin at the time of SSO configuration. If your customers encounter problems with the single sign-on (SSO) setup, they will have the opportunity to review and correct the configuration during the “Test connection” step.

Once your customer configures the SSO settings properly, tests the configuration and enables it - you shouldn’t receive these errors unless something has been modified, tampered or changed with identity provider.

Error code	Error description	Possible resolution strategy
mandatory_attribute_missing	Missing mandatory user attributes	Ensure all the mandatory user attributes are configured properly
invalid_id_token	Invalid ID token	Check the identity provider’s functioning
failed_to_exchange_token	Token exchange failure due to incorrect client_secret	Update the client_secret with the correct value
user_info_retrieve_failed	User info retrieval failed, possibly due to an incorrect client_secret or other issues	Update the client_secret with the correct value. If unsuccessful, investigate further. Please reach out to us via your private slack channel or via email
invalid_saml_metadata	Incorrect SAML metadata configuration	Update SAML metadata URL with the correct value
invalid_saml_response	Invalid SAML response	Review and fix SAML configuration settings
invalid_saml_request	The SAML request is invalid	Check the SAML configuration in both Scalekit and the identity provider
invalid_saml_form_params	The SAML form parameters are invalid or malformed	Review the SAML response format from the identity provider
signature_validation_failed	Failed signature validation	Review and update the ACS URL in the identity provider’s settings
invalid_acs_url	Invalid ACS URL	Review and update the ACS URL in the identity provider’s settings
invalid_assertion_url	The assertion URL in the SAML request is invalid	Verify and update the ACS URL in the identity provider’s settings
invalid_status	Invalid status	Review and update the SAML configuration settings in the identity provider
malformed_saml_response	Marshalling error	Ensure SAML response is properly formatted
assertion_expired	Expired SAML assertion	We received an expired SAML assertion. This could be because of clock skew between the identity provider’s server and our servers. Please reach out to us via your private slack channel or via email
response_expired	Expired SAML response	We received an expired SAML response. This could be because of clock skew between the identity provider’s server and our servers. Please reach out to us via your private slack channel or via email
authentication_not_completed	The authentication flow was not completed	Ensure the user completes the login process in the identity provider
user_login_required	User login is required to continue	Redirect the user to the login page to complete authentication