How do I troubleshoot SSO issues?
Here are the most common troubleshooting steps to make SSO work.
Table of Failure Codes
Code |
Federation Type | Enum Value | Comment | Possible solution |
---|---|---|---|---|
1 | WS-Federation | InvalidMessageType | Invalid response, cannot parse SignInResponseMessage, the returned message has invalid format. | Check your configuration |
2 | WS-Federation | MissingContext | Context not preserved during redirects The returned message does not contain the federation context, cannot resume flow. |
Check your configuration |
3 | SAML2 | InvalidResponseToken | Invalid response or authentication was not successful. | |
4 | WS-Federation | InvalidSecurityToken | Response XML signature is invalid. | Make sure that the used signature method is supported. |
5 | SAML2/WS-Federation | SecurityTokenNotYetValid | The token is not valid yet. | Time correction is needed on client's server. |
6 | SAML2/WS-Federation | SecurityTokenExpired | The token has expired. | Time correction is needed on client's server. |
7 | SAML2/WS-Federation | InvalidIdentityProviderId | Cannot find federation data for the domain. | Contact Support. |
8 | SAML2/WS-Federation | EmailMismatch | Email domain is different than the stored federation data. | |
9 | SAML2/WS-Federation | SignatureVerificationKeyMismatch | Signature public key is different than the stored one. | Contact Support. |
10 | SAML2/WS-Federation | MissingSamlAttributes | No SAML attributes are present in the assertion. | Check configuration, make sure the required claims are returned. |
11 | SAML2/WS-Federation | MissingSamlAttributeValues | No SAML attribute values are present in the assertion. | Check configuration, make sure the required claims are returned. |
13 | SAML2/WS-Federation | MissingEmailClaim | No email attribute is present in the assertion. | Misconfigured attribute mappings or attribute names. |
14 | SAML2/WS-Federation | InvalidFederatedContext | Cannot find federation context, probably timed out from cache. | Ask users to finish the login flow in less than 20 minutes. |
16 | SAML2/WS-Federation | InvalidSignatureVerificationCertificate | Cannot validate SAML response, the certificate is invalid. | Make sure that the response message signature certificate is correct . |
17 | SAML2/WS-Federation | MissingSignatureVerificationKey | Signing certificate public key is not present in the assertion. | Make sure that the response message signature certificate is correct . |
18 | WS-Federation | InvalidRequestMethod | Unsupported HTTP method. | WS-Federation supports only Http POST. |
19 | SAML2/WS-Federation | InvalidRequest | Cannot parse SAML response. | |
20 | WS-Federation | MissingMessage | Missing federation message. | |
21 | SAML2/WS-Federation | ReplayedToken | SAML token has already been used. |
Troubleshooting
- InvalidMessageType
-
Invalid message format means that something in the assertion is not recognized. This can occur when the attributes are not recognized or there is key information missing in the assertion.
In order to work towards a resolution, you will need to collect an assertion and analyze it for missing parameters. You can recreate the issue in Firefox and use SAML Tracer or SSO Tracer.
Once you have collected the assertion compare it with the example assertion below. If nothing sticks out, please provide it to development with the other relevant data.
- InvalidResponseToken
-
There are a few instances in which this can occur, most prominently this occurs when the attributes for email, firstname and lastname are wrong. Often times you will see attributes with names such as mail, givenname, name, etc. These will need to be adjusted to reflect as Email FirstName and LastName in the assertion. Here is an example failed assertion:
<saml2:Attribute FriendlyName="mail" Name="" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">john.smith@internet.com</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName="sn" Name="" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Smith</saml2:AttributeValue> </saml2:Attribute> <saml2:Attribute FriendlyName="givenName" Name="" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">John</saml2:AttributeValue> </saml2:Attribute> </saml2:AttributeStatement>
The highlighted items above will need to be adjusted to Email, LastName and FirstName.
- SecurityTokenNotYetValid
-
All certificates have a validity period, this is designated by the creating party, which could be a Cert Authority such as Thawte or GlobalSign or can be created by the customer. This error presents itself when the cert has not come into its validity period as of yet. Check the validity dates of the certificate and make sure that it is valid for the necessary time period.
- SecurityTokenExpired
-
Similar to the previous error, this refers to the validity period of a certificate. Certificates generally have an expiration date and most companies change them yearly. The user would get this error if the certificate has expired. This would require that we are sent an updated one and upload the new one into the account.
- EmailMismatch
-
This is a pretty common error that's easy to identify. As the name implies, this error means that the email you are providing is not the same as the one you are typing in. The email that you type in at the Central login page must be the same as the email in the: assertion.
Here's an example assertion containing email:
<Conditions NotBefore="2015-03-11T20:22:12.093Z" NotOnOrAfter="2015-03-11T21:22:12.093Z"> <AudienceRestriction> <Audience>https://accounts.logme.in</Audience> </AudienceRestriction> </Conditions> <AttributeStatement> <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"> <AttributeValue>Justin</AttributeValue> </Attribute> <Attribute Name=""> <AttributeValue>Bell</AttributeValue> </Attribute> <Attribute Name=""> <AttributeValue>jbell@logmeinse.com</AttributeValue> </Attribute> </AttributeStatement> <AuthnStatement AuthnInstant="2015-03-11T20:22:12.077Z"> <AuthnContext> <AuthnContextClassRef>urn:federation:authentication:windows</AuthnContextClassRef> </AuthnContext> </AuthnStatement> </Assertion>
Make sure that the emails match.
- SignatureVerificationKeyMismatch
-
Certificate is not the same as the one being passed by IDP. Make sure certificates match, capture from customer or metadata xml file and re-upload.
- MissingSamlAttributes
-
SAML attributes missing, make sure customer has proper rules configured on IDP side. Investigate assertion make sure FirstName, LastName and Email are being provided.
- MissingSamlAttributeValues
-
Variables present for FirstName, LastName, and Email, but are provided blank with no data. Investigate assertion and rules on IDP side.
- MissingEmailClaim
-
Email attribute missing in assertion. Investigate assertion and rules on IDP side.
- InvalidFederatedContext
-
Generally caused by timeout, this can occur if user starts login process, then does not complete and tries later. Have them try entire login process from start to finish with no pauses in-between.
- InvalidSignatureVerificationCertificate
-
Make sure certificate uploaded into the account matches certificate being provided by IDP. Capture certificate directly from customer, IDP or metadata xml file.
- InvalidRequestMethod
-
WS-federation only supports Post HTTP protocol. If this error is present, have user change protocol to HTTP Post on IDP side.Note: As we use SAML 2.0 now, you generally shouldn't see this issue
- InvalidRequest
-
Cannot parse response, check to make sure assertion is coming through properly. Capture assertion and investigate what may be missing. Make sure assertion is actually being passed. At times rules not present on IDP side can cause assertion to not even trigger.
- MissingMessage
-
Missing federation message, proper data not being supplied in assertion. Capture assertion and investigate what may be missing.
- ReplayedToken
-
SAML token used previously. Happens when a refresh of the page sends the same assertion twice.