If you see an error on the Envoy login screen after attempting to sign in to Envoy using SSO, you may need to check some configuration settings.
Scenario 1: SAML certificate is not valid
This may indicate that the identifiers are mis-configured for the Envoy Relying Party Trust. Check the Identifiers tab of the properties dialog and ensure that there is a single Relying Party identifier with https://app.envoy.com/a/saml/consume.
Scenario 2: SAML account/company not found
This error could result from a couple problems:
It may indicate that the fingerprint in the Envoy configuration is misconfigured. Make sure that you have the SHA1 fingerprint (or thumbprint) of the token-signing certificate. If you are unsure which certificate is used, you may try capturing the SAML request in the browser and decoding it to check.
It may also indicate that the SAML assertion was sent successfully, but that Envoy could not find a user that corresponds to that email address. Ensure that that the user who is logging in has an email address that is already provisioned and confirmed in Envoy.
Also, please ensure that the email the SAML request is sending matches the email in the Envoy employee directory.
Scenario 3: No error, just displays login screen
This may indicate that the user’s email address is not getting sent correctly. Double check that there are two Claim Rules configured to send the LDAP email address as a Name ID claim.
Scenario 4: AADSTS75011: Authentication method by which the user authenticated with the service doesn't match requested authentication method 'Password, ProtectedTransport'. Contact the Envoy_SSO application owner.
This error is most likely due to Envoy setting 'Password, ProtectedTransport' as an exact match requirement for the authentication method through SSO. Please contact Envoy Support so that we can adjust the requirements of your specific SAML integration to set that to optional.
Note: This mostly only happens when setting up SAML through Entra.
Scenario 5: SAML Certificate Expired (Entra)
Refreshing your SSO application certificate in Entra is crucial for maintaining secure and uninterrupted service. Follow these steps to update your certificate:
Create a New Certificate in Entra:
Navigate to Entra: Access your Entra instance through the Entra portal.
Manage SSO Application Certificates: Go to the section dedicated to managing SSO application certificates.
Create a New Certificate: Generate a new certificate, ensuring it aligns with your security and validity requirements.
Remove the Old Certificate:
Locate the Expiring Certificate: Find the certificate for your SSO Application that is nearing expiration.
Deactivate or Remove: Carefully deactivate or remove this certificate to avoid any service disruption.
Activate the New Certificate:
Activate: Activate the newly created certificate.
Set as Primary: Ensure it is designated as the primary certificate for your SSO Application.
Updating the Fingerprint in Envoy
After updating the certificate in Entra, the next step is to update the fingerprint in Envoy. This ensures seamless SSO functionality.
Copy the New Certificate Thumbprint:
Find the New Certificate in Entra: Locate the newly activated certificate in Entra.
Copy Thumbprint: Copy the hexadecimal string representing the certificate's thumbprint.
Log in to Your Envoy Dashboard:
Access Dashboard: Log into your Envoy dashboard.
Navigate to Integrations/SSO Configuration: Find the Integrations or SSO configuration section.
Update the Fingerprint:
Find SAML Configuration: Go to the SAML configuration section or similar.
Replace Thumbprint: Substitute the old certificate's thumbprint with the new one from Entra.
Verify Entry: Ensure the new thumbprint is accurately entered without errors.
Save Changes:
Apply New Settings: Save your changes to apply the new certificate settings to your Envoy SSO configuration.
Test the Configuration:
Perform Test Sign-In: Conduct a test sign-in to verify the SSO functionality with the new certificate.
Check for Errors: Ensure there are no errors and that authentication is successful.
If you need support
If you need to contact Envoy support, there are a few pieces of information that we’ll need to help resolve your issues.
Tell us the exact time that you tried logging in and saw an error. It helps us to be able to look up the failure in our logs. Let us know the email address of the user that is attempting to log in, so we can double check that user is in our system.
It’s also very helpful to capture the SAML request or response in the browser so we can compare it to what we expect. Most web browsers support a way to view the contents of a request.
How to grab a SAML response (Chrome):
Step 1: Open Developer Tools
In Chrome, open the Envoy Dashboard login page.
Access Developer Tools: You can open the Developer Tools by right-clicking anywhere on a webpage and selecting Inspect or use the keyboard shortcut Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (Mac).
Step 2: Go to the Network Tab
Navigate to the Network tab: In the Developer Tools window, find the tab labeled Network and click on it.
Prepare to capture traffic: Make sure the record button (the red circle at the top-left of the Network tab) is activated. If it’s grey, click it to start recording.
Preserve log: Check the Preserve log box to keep the network log upon navigation. This ensures that the log isn't cleared when the authentication process redirects you through different pages.
Step 3: Initiate the SSO Process
Enter credentials and log in: Perform the login steps as you normally would until you are redirected back from the SSO provider. It's important to start recording before logging in to capture the entire SSO process.
Step 4: Capture the SAML Response
Filter the traffic: In the Network tab, use the filter box (usually labeled "Filter" or represented by a text box with a magnifying glass) and type "SAML". This helps in isolating the SAML related network requests.
Identify the SAML Response: Look for network entries with names like SAMLRequest or Consume.
Inspect the details: Click on the relevant entry to view the details.
Check the POST requests payload tab.
Copy the SAML Response: Right-click on the request: Choose "Copy" and then select "Copy response" or select the string of letters after "SAMLResponse"
Send this data to Envoy Support: You can also decode it yourself here.
If you encounter issues capturing the SAML response, try clearing your browser's cache and cookies before starting the process.
Consider performing these steps in an incognito window to avoid interference from browser extensions or cookies and cache that might affect the SSO process.