# 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 |
|-------|------------------|----------------------------|
| <pre>invalid_redirect_uri</pre> | Redirect URI is not part of the pre-approved list of redirect URIs | Add the valid URL in the Scalekit dashboard before using it |
| <pre>invalid_connection_selector</pre> | Missing `organization_id` (or) `connection_id` (or) `domain` (or) `provider` in the authorization URL | Include at least one of these parameters in the request |
| <pre>no_active_connections</pre> | There are no active SSO connections configured to process the single sign-on request | Ensure active SSO connections are set up |
| <pre>connection_not_active</pre> | The configured connection is not active | Enable the SSO connection in the Scalekit dashboard |
| <pre>no_configured_connections</pre> | No active SSO connections configured | Ensure active SSO connections are set up |
| <pre>invalid_organization_id</pre> | Invalid organization ID | Verify and use a valid organization ID |
| <pre>invalid_connection_id</pre> | Invalid connection ID | Verify and use a valid connection ID |
| <pre>domain_not_found</pre> | No domain specified for the SSO connection(s) | Check domain configuration in Scalekit dashboard |
| <pre>invalid_user_domain</pre> | User's domain not allowed for this SSO connection | Ensure user domain is part of the allowed domains list |
| <pre>invalid_client</pre> | The client application is not recognized or not configured correctly | Verify the `client_id` value in your authorization URL |
| <pre>application_not_active</pre> | The application is inactive | Enable the application in the Scalekit dashboard |
| <pre>invalid_request</pre> | The authorization request contains invalid or missing parameters | Review the authorization URL parameters |
| <pre>unauthorized</pre> | The request is unauthorized | Verify that valid credentials are being used |
| <pre>user_not_active</pre> | The user account is inactive | Activate the user account or contact the IT admin |
| <pre>server_error</pre> | _actual error description from the server_ | This must be a rare occurrence. Please reach out to us via your private slack channel or <a href="mailto:support@scalekit.com" target="_blank" rel="noopener">via email</a> |

## 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 |
|------------|------------------|----------------------------|
| <pre>mandatory_attribute_missing</pre> | Missing mandatory user attributes | Ensure all the mandatory user attributes are configured properly |
| <pre>invalid_id_token</pre> | Invalid ID token | Check the identity provider's functioning |
| <pre>failed_to_exchange_token</pre> | Token exchange failure due to incorrect `client_secret` | Update the `client_secret` with the correct value |
| <pre>user_info_retrieve_failed</pre> | 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 <a href="mailto:support@scalekit.com" target="_blank" rel="noopener">via email</a> |
| <pre>invalid_saml_metadata</pre> | Incorrect SAML metadata configuration | Update SAML metadata URL with the correct value |
| <pre>invalid_saml_response</pre> | Invalid SAML response | Review and fix SAML configuration settings |
| <pre>invalid_saml_request</pre> | The SAML request is invalid | Check the SAML configuration in both Scalekit and the identity provider |
| <pre>invalid_saml_form_params</pre> | The SAML form parameters are invalid or malformed | Review the SAML response format from the identity provider |
| <pre>signature_validation_failed</pre> | Failed signature validation | Review and update the ACS URL in the identity provider's settings |
| <pre>invalid_acs_url</pre> | Invalid ACS URL | Review and update the ACS URL in the identity provider's settings |
| <pre>invalid_assertion_url</pre> | The assertion URL in the SAML request is invalid | Verify and update the ACS URL in the identity provider's settings |
| <pre>invalid_status</pre> | Invalid status | Review and update the SAML configuration settings in the identity provider |
| <pre>malformed_saml_response</pre> | Marshalling error | Ensure SAML response is properly formatted |
| <pre>assertion_expired</pre> | 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 <a href="mailto:support@scalekit.com" target="_blank" rel="noopener">via email</a> |
| <pre>response_expired</pre> | 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 <a href="mailto:support@scalekit.com" target="_blank" rel="noopener">via email</a> |
| <pre>authentication_not_completed</pre> | The authentication flow was not completed | Ensure the user completes the login process in the identity provider |
| <pre>user_login_required</pre> | User login is required to continue | Redirect the user to the login page to complete authentication |