fThis article relates to Single Sign-On (SSO) in Foundry.
Below are several cases where you may need help troubleshooting. The action steps are listed below each heading.
1. New User Asked to Update Profile ( Input Fields are Blank )
When a new user SSOs into the EVERFI platform and they are led to a screen where they are asked to input values such as their name or email, which appear blank, then there is an issue with the attribute mapping in the Identity Provider setup. All attributes must be mapped even if your organization is using the exact same attribute names. Please check your Identity Provider setup and try again.
2. New User Asked to Enter Basic Details ( Input Fields are Already Filled In )
When a new user SSOs into the EVERFI platform and they are led to a screen where they are asked to input values such as their name or email, which are prefilled in, please take a screenshot (including the URL showing in the browser nav bar) and send it, along with the steps you took that led to this error screen, to the EVERFI team for review.
3. SSO Leads to Error Message
If during SSO you are led to a screen that looks like this, please take a screenshot (including the URL showing in the browser nav bar) and send it, along with the steps you took that led to this error screen, to the EVERFI team for review.
4. Deactivated User SSO Error
If a user whose account has been deactivated by an EVERFI admin attempts to login via SSO they will receive an error message. If the user has been deactivated in error, contact the EVERFI team.
5. Identity Provider Metadata URL – Updates in IdP SAML Metadata
When you configure your IdP in EVERFI’S platform, if you choose Option 1 to provide a metadata URL for your IdP’s SAML metadata, be aware that EVERFI uses the URL to retrieve the various properties from your SAML metadata at that point in time, and then saves them as static values. EVERFI does not periodically connect to the metadata URL to refresh any settings that might change. Therefore, if you subsequently update any properties in your IdP’s SAML metadata, such as a new x.509 certificate, EVERFI does not automatically discover these changes in order to refresh these properties. You will need to manually update your configuration in EVERFI’s platform by editing the IdP configuration and re-entering the metadata URL and saving it.
6. The Assertion of the Response is not signed and the SP requires it
When attempting SSO, you get an error: “The Assertion of the Response is not signed and the SP requires it”
Explanation: Foundry requires the identity provider’s SAML Response’s Assertion to be signed. It is not enough for just the Response to be signed; the Assertion must also be signed.
Resolution: In your identity provider, in the EVERFI service provider configuration, ensure that the IDP signs the SAML Assertion.
Error when saving Identity Provider – Default User Type cannot be blank
If you attempt to add a new Identity Provider and you get an error message upon saving that says “Default User Type cannot be blank”, you may be confused because you cannot see a field called that on the page.
You will need to check the “Allow registration via SAML?” checkbox on the bottom of the page in order to view that field as well as the attribute mapping fields. You may then enter values into these fields.
In a future release, this UI will be redesigned to be more intuitive.
Sorry, we were not able to connect to your account
If, after a user authenticates to their identity provider, you see this message:
(The part << Organization Name >> will contain the actual name of the Organization)
This error happens with the SAML Subject NameID has a value that cannot be found in any Users in your organization with that SSO ID or email address (as a backup search). This can only happen when your Foundry IDP setup has the “allow registration via SAML” checkbox unchecked, which means Foundry will not create new users during SSO, otherwise Foundry would have simply created a new User after not finding an existing user.
- The error message includes the NameID that was in the SAML Response’s Assertion. Is there a user in Foundry whose SSO ID should have this NameID? Or is there a mismatch in NameID to Foundry SSO ID, for example the NameID is ID but the SSO ID is a username or email address.
- Are the SSO ID values populated in the Users in Foundry?
- Is the User actually in Foundry?
- Is the value being passed in the NameID coming from the correct field in the identity management system? For example, does the SAML NameID contain a numeric employee ID but the SSO ID fields in Foundry have email addresses?
- Is there a case sensitivity mismatch between the SAML NameID value and the Foundry SSO ID? The case must match exactly. For example, a NameID of Jeff.McDaniel@stateu.edu will NOT match to a Foundry User SSO ID of email@example.com.
- The Error Message also contains an ID that is a long string of letters and numbers like this: 82321732d25be376733c0f2e1d9149fc. This is the unique ID of the SAML Response. If your system logs its outgoing SAML Responses, you can search for it with this ID to gain more information. You can also provide this ID to EVERFI for us to search for your SAML Response to diagnose the SSO event in more detail.
SAML ID provider in the request is not configured in the system
If during SSO you get this error:
This error occurs when the Issuer in your IDP’s SAML Response is not the same as the Entity ID that is in the IDP setup in Foundry. When Foundry receives a SAML Response, Foundry takes the Issuer in the Response and tries to locate a IDP setup whose Entity ID is equal to that Issuer. A common reason this might happen is if you have multiple Entity IDs, or your Entity ID is has a mismatch between “http” and “https”, for example.
SAML Response StatusMessage of Signature required
If you are running PingFederate and get this in a SAML Response:
<samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester" /> <samlp:StatusMessage>Signature required</samlp:StatusMessage> </samlp:Status>
When creating a service provider for Foundry in PingFederate, set “Require digitally signed AuthN requests” to false to resolve this error.
The status code of the Response was not Success, was Responder
If your IDP is Microsoft AD FS and you get this error, then in AD FS, make sure that you have uploaded the EVERFI certificate to the Signature tab in the EVERFI relying party trust. See separate Microsoft AD FS SAML Single Sign-On Integration to EVERFI Foundry documentation for more.
You can also see evidence of this error by looking at the SAML response message the IDP sends to the Foundry SP, if you see this in the response XML:
<samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder" /> </samlp:Status>
The SAML assertion could not be decrypted
If during SSO you may see this message when the user attempts to log in:
This message occurs when a X.509 certificate is invalid, or if the there is a certificate mismatch between the identity provider and Foundry. Note that this error is likely to happen only if the partner IdP encrypts their SAML assertions (which is generally recommended).
In SAML, there are two public X.509 certificates: one for the Identity Provider organization and one for the Service Provider organization; in a SAML implementation, each organization’s system “knows” the other’s X.509 certificate. In the identity management system of the partner, in the configuration for the EVERFI service provider, that configuration will normally store the EVERFI public X.509 certificate. In Foundry, in the IdP setup, the IdP’s certificate (or at least the fingerprint of the certificate) is stored, as well as a pointer to which specific EVERFI public X.509 certificate the identity provider is using; this model allows for EVERFI to rotate its own X.509 certificates between an older certificate and a newer one with a later expiration date.
If the certificates between the IdP and the SP are out of sync, then when SAML assertions are send and received and then decrypted, an error will occur because of the certificate mismatch between the two systems. When this occurs, you will see the “The SAML assertion could not be decrypted” error message. This could happen if the X.509 certificates for the partner is out of sync, of if the X.509 certificates for EVERFI are out of sync; either situation could cause this error to happen.
When this problem can occur
Generally, this problem will not occur in a stable environment. This will occur only if someone changes the EVERFI X.509 certificate in the IdP without also updating the Foundry IdP configuration to designate the IdP is using the same EVERFI X.509 certificate, or if someone updates the Foundry IdP configuration with the wrong X.509 certificate of the partner organization.
Or, the error could happen if the X.509 certificate is not formatted properly.
How to Solve This Error
Ensure the X.509 certificates are in sync across both systems.
Ensure the X.509 certificate entered in the Foundry IdP setup for the identity provider is formatted correctly.
SSO Error: Current time is earlier than NotBefore condition
This error can happen with identity providers where there is a slight time offset between systems.
If you experience this with ADFS, you can add a “clock drift.” To remedy this, in your AD FS Windows Server, in a command shell (not a DOS command line) run this command where “TrustName” is the actual name of the relying party trust for EVERFI, without double quotes:
PS C:\> Set-ADFSRelyingPartyTrust -NotBeforeSkew "5" -targetname TrustName
For example, you might have named the Relying Party Trust “EVERFI”, so the command would be:
PS C:\> Set-ADFSRelyingPartyTrust -NotBeforeSkew "5" -targetname EVERFI
See NotBefore causing troubles when server times slightly out of sync for background. The command above is for ADFS2. If running ADFS1 there is a different command.
Foundry’s system time is synched with AWS.
Foundry applies 2 seconds clock drift or leeway, so be sure that if your identity provider is adding NotBefore or NotOnOrAfter conditions to the SAML Response that they are not so limited as to trigger this error.
Invalid Signature on SAML Response
If a user attempts to SSO and gets this error:
First, verify that in the Foundry IDP config, that the IDP certificate and IDP certificate algorithm are correct. If the identity provider is sending in the SAML Response a different certificate than the one entered in Foundry, this mismatch would cause this error. One way to check this is to inspect the SAML Response the identity provider sends with SAML Tracer. Look in the response for the certificate between the
<X509Certificate> tags, and make sure the certificate text is the same as that in the Foundry identity provider config. If you mixed up certificates in the course of your setup, or make a series of changes, it’s possible that you can have the wrong certificate in the Foundry IDP config.
For background, this is the flow in single sign-on:
- Your identity provider sends a SAML
Response. This is triggered by IDP-initiated SSO, or from a SAML
AuthnRequestfrom Foundry during SP-initiated SSO.
- The SAML
Responsecontains a X509Certificate and a signature.
- Foundry calculates the fingerprint from the certificate in the SAML Response and compares it to the IDP certificate fingerprint in the Foundry IDP config. They must be identical. The IDP certificate fingerprint in the Foundry IDP config was calculated from the IDP certificate you entered, or if you did not enter a certificate, then from the IDP certificate fingerprint you entered.
- Next, using the certificate fingerprint generated from the certificate in the SAML Response, Foundry verifies the signature in the SAML Response to ensure it is valid.
If you believe the IDP certificate and IDP certificate algorithm in Foundry are correct and you continue to see this error, then contact EVERFI. We will need to investigate further. Is is possible that when your identity provider metadata was keyed into the Foundry IDP setup, that the fingerprint digest for your certificate was calculated incorrectly.
WSO2 Identity Server Setup
If your identity management solution is WSO2, then in your service provider setup for Foundry, be sure to configure the following settings:
- Certificate Alias – you must select the EVERFI certificate. In order to do so, you must first add the EVERFI certificate into your WSO2 Keystore
- Enable Response Signing – set to checked because Foundry requires SAML responses from the IDP to be digitally signed
- Enable Signature Validation in Authentication Requests and Logout Requests – uncheck this checkbox
Maximum Querystring Length Error
Some systems impose a default maximum length on request querystrings. Often these are Microsoft settings and the limit is 2,048 characters. When Foundry sends a SAML Authorization Request (
AuthnRequest) to your identity provider, the SAML
AuthnRequest is encoded and put into a querystring parameter. The total length of that parameter is often 3,000 – 4,000 or more characters. The
AuthnRequest can get large because Foundry digitally signs the
AuthnRequest so that an identity provider can validate the request is actually coming from Foundry. Signing the request means the Foundry X509 certificate is included in the response, as well as additional XML tags and data associated with signing.
To resolve this, you will need to increase the maximum querystring length in your system.
If your system is running Microsoft.net, these links may be helpful:
Cannot Edit SSO ID of my Own User
SSO ID not visible when Admin edits Users in Customer Portal
Not a valid audience for this Response
A different user with the email <<emailaddress>> already exists
- The user logging in has a SAML Response NameID from the identity provider that is matched with an existing Foundry User. This means that Foundry was able to match the user.
- The Foundry IDP config has an Attribute Mapping for email address.
- The SAML Response contains an Attribute for the email address.
- There is a different user in Foundry with the same email address as the mapped email address in the SAML Response provided by the identity provider. This can happen if the user has a duplicate, whether the duplicate user is active or inactive.
Reason this error was triggered: Where there is a mapped attribute for email, and the SAML Response has a value for that Attribute, then Foundry will attempt to update the user’s email address to that value. But Foundry was not able to do this because of the duplicate email address held by a different user.
Resolution: in the duplicate user who has the same email address as that of the SAML Attribute, change the user’s email address. Since email is a required field, you can make it a fake email address.
Case 2: No Matching NameID, Attempt to Create New User with Duplicate Email Address
The user attempting to log in has a NameID that does not match with the SSO ID of any existing Foundry users
In the identity provider configuration in Foundry, the “Allow automatic registration during SSO” checkbox is checked, so that Foundry will create a new user
When Foundry attempts to create a new user, the email address provided in a mapped Attribute is already held by a user in Foundry, causing Foundry to have an error when attempting to add the new user
Resolution: check the Foundry user who already has the email address. If that user has a SSO ID, ensure that the user attempting to log in has a matching NameID. It could be that there is a case difference between the NameID in the SAML Response and the Foundry user’s SSO ID.
User Cannot Be Saved
This error message can happen for a number of reasons. At the root of all these errors is that in the course of SSO, Foundry is either attempting to add a new user, or update an existing user, and that attempt failed. Hence the message that the user cannot be saved.
User Cannot be Saved when attempting to Add a New User
- This error can happen if the user attempting to SSO does not already exist in Foundry. If the IDP config in Foundry has “allow registration via SAML” checked, then Foundry will add a new user with the values provided in the defaults set in the IDP config plus any mapped attributes. If the combination of values is invalid or incomplete, then the attempt to insert a new user will fail and this error message will be displayed. Common problems might be:
- A required field like first name, last name or email address is not in a mapped Attribute
- The email address, which must be unique, duplicates the email address of another user
- A mapped attribute for user type, role or location is invalid
User Cannot be Saved during Update of User
Foundry might attempt to update an existing user if the user signing in already exists in Foundry, and can be identified via the SAML Response’s NameID or mapped email attribute. Foundry may attempt to update the user if there are mapped attributes. Errors for this scenario are unusual but may happen when:
- There is a mapped attribute for email address, and the value provided in the Attribute is an email address that already belongs to another user. Since email addresses cannot be duplicated, the attempt to save the user will fail and you will get this error.
- There is a mapped attribute for a location or role where the Attribute value is invalid
Invalid SAML Response
- Capture the SAML Response using SAML Tracer or another tool.
- Go to a XML schema validator site like: https://www.freeformatter.com/xml-validator-xsd.html
- Enter the SAML Response in the XML field
- Enter the SAML 2.0 schema XSD from https://docs.oasis-open.org/security/saml/v2.0/saml-schema-assertion-2.0.xsd (“view source” in browser to get the raw text) in the XSD field
- Run the validation check and examine the errors.
- Correct the formatting in the SAML Response based on what the errors highlight.
404 Page Not Found Error during SP-initiated SSO
Q: We are certain the SSO/ACS login pages are entered correctly, but when we attempt SP-initiated SSO, we get a
404 “page not found” error when Foundry sends the user to our IDP’s login page. But when we initiate SSO from our identity provider, SSO works. Why is this
A: Normally, a 404 “page not found” error happens when the web page file does not exist, such as with a broken webpage link. But a
404 error can also be caused by other random backend errors. You may need to inspect your server’s event logs to find an explanation. We have seen examples where certificate mismatches or other configuration problems cause a
404 error; the IDP detects some problem and rather then outputting the real problem, it bombs out with an ambiguous
404. This kind of error can throw you off because normally a
404 error means “page not found” but in this case it is masking a different root problem.
In some cases, the real problem is the Maximum Querystring Length Error. Foundry’s SAML
AuthnRequest has a large querystring parameter value containing a certificate and digital signature and this can exceed the maximum querystring length value on some servers. If this is the case, the server returns a
404 error even though the webpage actually does exist. You may need to increase this limit to overcome this restriction and allow SP-initiated SSO to function. The reason this error might not occur during IDP-initiated SSO is because the SSO flow starts from your identity provider and there is no SAML Message sent from Foundry to your system.