SCIM and account SSO issues

This section covers errors related to SCIM provisioning and tenant-specific configurations:

• How to troubleshoot SCIM provisioning?
• Why do I see "Tenant SSO Failed" logs?
• Why do I get an error when uploading my XML metadata?

How to troubleshoot SCIM provisioning?

Frontegg supports user provisioning from external IdPs in compliance with SCIM standards and protocol. However, variations in how providers implement user attributes and data synchronization can occasionally cause errors during the provisioning process.

Provisioning users

The primary user identifier in Frontegg is the email address. Errors can occur during user provisioning (automatic or on-demand) if user attributes fail validation on the Frontegg side.

For instance, the error message:
Bad request. Errors reported by remote server
typically indicates a mismatch in the expected data type of a user attribute. For example, provisioning a user with an unsupported timezone attribute from the external IdP may trigger this error.

These issues will soon be logged in Frontegg's monitoring system for greater transparency. Until then, if you encounter this error:

1. Contact Frontegg Support at support@frontegg.com.
2. Provide the tenantId and the affected user’s email address.
3. The support team will investigate and provide further details.

Provisioning groups and users

User groups and their assignments are synced between the IdP and Frontegg using Add or Replace requests. Occasionally, the IdP may send a Replace request instead of an Add, which can result in:

• Users not being synced to Frontegg.
• Users not appearing in the correct groups after synchronization.

If group membership changes are not reflected in Frontegg after a provisioning cycle:

1. Check the monitoring logs for Group creation or Group updation requests.
2. Confirm whether the IdP sent an Add or a Replace request to Frontegg.

If the IdP sent a Replace request to sync additional users to a group:

• Contact Frontegg Support to enable a flag that treats Replace requests as Add operations.
• This behavior is common with Microsoft Entra. For more details, refer to the Microsoft Entra documentation.

Common SCIM errors

Below are some common SCIM errors you may encounter when provisioning users, along with potential causes and solutions:

Why do I see "Tenant SSO Failed" logs?

Logs are a powerful tool for diagnosing and resolving authentication issues in your application. If an end-user attempts to log in via SSO (Single Sign-On) and the login fails, a Tenant SSO Failed log will appear under the relevant environment.

Identifying the issue

When you open the raw data of the log, you will find error and reason fields that specify the cause of the failure. These failures often occur due to a mismatch between the SP (Service Provider) and IDP (Identity Provider) setup.

For example:

• If the SP Entity ID is set to "Acme" but your customer mistakenly configured their SAML app with "Acme.com," the login will fail with an error related to the audience attribute.

To pinpoint the mismatch:

1. Locate the SAMLResponse in the raw data of the log.
2. Copy the SAMLResponse.
3. Use an online decoding tool like SAML Tool Decode to decode the response into an XML file.

What to check in the decoded SAMLResponse

Inspect the following attributes in the decoded XML file:

1. nameId

   • Ensure that the nameId attribute contains the email address the user attempted to log in with.

2. Destination

   • Verify that the Destination attribute matches the ACS URL (Assertion Consumer Service URL) configured under your SAML settings.

3. Audience

   • Ensure that the Audience attribute matches the SP Entity ID configured under your SAML settings.

4. Certificate

   • Confirm that the X509Certificate value in the XML matches the certificate applied to this SSO connection.

Verifying the applied certificate

To check which certificate is applied to the account:

1. Open the Frontegg portal.
2. Navigate to [ENVIRONMENT] ➜ Management ➜ Accounts, and select the designated account.
3. Go to the SSO Configurations tab.
4. Locate the Public Certificate displayed in the modal. This certificate is Base64 encoded.
5. Decode the certificate using any online decoding tool.
6. Compare the decoded certificate with the X509Certificate value in the user’s SAMLResponse to ensure they match.

By following these steps, you can identify and resolve SSO-related issues effectively. For further assistance, contact Frontegg Support at [support@frontegg.com].

Why do I get an error when uploading my XML metadata?

If you encounter an error while uploading XML metadata for a SAML SSO connection, it may be due to missing or incompatible attributes in the XML file.

For a complete guide on enabling SSO with your identity provider (IDP) through Frontegg, refer to this guide.

Automatic upload method

When setting up a SAML SSO connection, Frontegg recommends using the automatic method to upload the XML file from your IDP.

During the upload, Frontegg parses the SSO Endpoint and public certificate from the XML file. However, some IDPs, such as JumpCloud, may omit the necessary parameter for extracting the SSO Endpoint:

Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

Resolution

If the required attribute is missing, you can proceed with one of the following solutions:

1. Use the manual method:

   • Open the Frontegg portal and navigate to [ENVIRONMENT] → Configurations → Authentication → SSO.
   • Manually paste the SSO Endpoint and public certificate into the appropriate fields.

2. Modify the XML file in JumpCloud:

   • Enable the Declare Redirect Endpoint option in JumpCloud to ensure the Binding attribute is included in the XML file.
   • Re-export the metadata file and upload it again.

Following these steps should resolve the issue and allow successful SSO configuration.