Sometimes we encounter some errors when logging in using SSO, and here we will share some of the information that can be validated internally, which is often the source of the problem. First of all, as soon as we face a Login error with SSO, the best thing to collect is the SAML Tracer. And with it, we can start validating the following:
1. is the Origin hostname returned in the header the same as the one configured on the Harness platform(IdP metadata)?
2. The user email that the IdP (e.g., Okta, Azure AD, etc.) responds to is the same one used for login?
3. The identity provider(IdP) sends the properly configured Issuer(entity ID) to Harness(default app.harness.io)?
No worries because we will now cover the above common issues in more detail below:
1. Example of how to validate if the Origin is correct from an Account configured with IdP (Okta for this example):
In the SSO Settings, we can see the Origin expected is
sso.test.com, but for this user, and probably for the other, it is coming as
test.okta.com as it does not match; it is failing.
The Origin we get from the Referrer header in the SAML tracer:
The above mentioned problem is typically encountered with unsupported/undocumented SAML SSO providers. That being said, you can see this article that our team has written to work around this from the client side by modifying the IDP metadata to use the hostname the IDP is originating coming from:
This is because we use the hostname for Origin in the HTTP headers to, in fact, look up the accountID IdP metadata after POSTing to the ACS URL. So if this is out of spec, we will fail to find the accountID metadata and subsequently fail the login with another famous ‘InvalidSSO’ error during login.
2. Incorrect NameID format, or incorrect value being sent for NameID (user login ID) attribute in SAML assertion/response:
Once you collect the SAML tracer, you can check and make SURE that the login ID between the tags for in the assertion is both in email address format and exist in Harness before attempting a test/login. If not, get this corrected on the IdP side. This is a widespread problem where the user IdP is not appropriately configured due to either misconfiguration during the configuration or using an unsupported identity provider. So, when checking the assertion, which is the response coming from the identity provider after valid authentication, you will see something along the lines of:
There are some typical scenarios where customers send their user ID or some internal company pattern which we discover either in the SAML trace or HAR file(SAML trace is easier). One example of a misconfigured application(Harness) on the IdP sending the user’s ID as the NameID:
The above will fail as that account format is not permitted in Harness, so it could not possibly exist and will end up with the famous ‘InvalidSSO’ error seen in the UI.
3. Entity ID mismatch between IDP and Harness(SP)
Another common issue we see with a lot is where the Entity ID does match the ‘Audience’ attribute in the SAML metadata that has been uploaded. By default, unless you define a custom entity ID here(under Access Management->Authentication Settings->Edit SAML provider):
We will default to using ‘app.harness.io’ as the service provider expected entity ID(Issuer attribute in IdP metadata/SSO Settings XML). We see that it is prevalent for customers to make up an entity ID and think this will work, but they need to match. Entity ID can be anything and is not required to be a hostname. For example, if I change the above and add the Entity ID ‘harness-rules’, as long as the application is configured with the same on my identity provider, this will work. If the customer doesn’t want or needs to customize the entity ID above, leave it unchecked, and ensure it is app.harness.io on the IdP.
Thanks for reading!
I hope this article will help you troubleshoot the most common issues you face configuring SSO with Harness.