SSO Setup with Shibboleth

NameIDFormat

The Foundry SAML service provide metadata contains the following NameIDFormat:

<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> 

Be aware that Shibboleth default settings might automatically set the NameIDFormat to transient when you initially generate a service provider with a SP metadata file like EVERFI’s that uses the unspecified format. You will need to change that setting to use the appropriate format.

Foundry does not request a preferred NameIDFormat in the service provider metadata file because that decision needs to be made based on the values you plan to set, or already have, in the Foundry users’ SSO ID field, and may be different for each institution. Most institutions use email address, a student ID, or a persistent ID, but EVERFI has no preference, as long as it’s not transient. 

---

NameID Format

NameIDFormat

The Foundry SAML service provide metadata contains the following NameIDFormat:

<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> 

Be aware that Shibboleth default settings might automatically set the NameIDFormat to transient when you initially generate a service provider with a SP metadata file like EVERFI’s that uses the unspecified format. You will need to change that setting to use the appropriate format for your institution.

Foundry cannot request a preferred NameIDFormat in the service provider metadata file because that decision needs to be made based on the values you plan to set, or already have, in the Foundry users’ SSO ID field, and may be different for each institution. Most institutions use email address, a student ID, or a persistent ID, but EVERFI has no preference, as long as it’s not transient.

According to one EVERFI client with a Shibboleth identity provider, here is a way to instruct the Foundry identity provider to use your preferred NameID value. EVERFI is not able to provide additional Shibboleth instructions beyond this information so if you require additional guidance, please consult the Shibboleth community.

How to specify NameIDFormat

Shibboleth allows you to override what is presented in a metadata file. There is a file called relying-party.xml that allows you to set this up. Here is an example for Foundry.
First, make sure to have a NameIdentificationGenerator that is appropriate. This is in saml-nameid.xml:
<bean parent="shibboleth.SAML2AttributeSourcedGenerator"
p:omitQualifiers="true"
p:format="urn:oid:1.3.6.1.4.1.10177.1.101"
p:attributeSourceIds="#{ {'uniUnivID'} }" />

In this case, the institution uses the student/employee number. This is registered as a URN, and defined with a NameID generator. Note — you can use a comma separated list here — and the first value that is released will be used. If you don’t release anything from that list then it will send a blank NameID.

Here is an example that sets up a NameID generator for emailAddress — you may already have this, if manually changing the metadata works:

<bean parent="shibboleth.SAML2AttributeSourcedGenerator"
p:omitQualifiers="true"
p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
p:attributeSourceIds="#{ {'mail','Email'} }" />

You may have some vendors that prefer ‘mail’, and some that prefer it be called ‘Email’, so the above code aliases both of them, and if it releases either of them, this generator will work.

Now we can edit relying-party.xml — this allows you to set up a lot of overrides. In this case, we are going to tell Shibboleth to ignore the metadata’s request for unspecified, and send an email, instead:
<!-- place your institutions own specific Foundry entityID here in c:relyingPartyIds -->
<bean parent="RelyingPartyByName" c:relyingPartyIds="https://admin.fifoundry.net/org_slug/saml/sp">;
<property name="profileConfigurations">
<list>
<bean parent="SAML2.SSO" p:nameIDFormatPrecedence="urn:oid:1.3.6.1.4.1.10177.1.101" />
</list>
</property>
</bean>

The above has to go inside the XML element called shibboleth.RelyingPartyOverrides.

Again, this uses the URN here, since we send a student/employee number, and not an email address. Based on the earlier example, for email you can instead put urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, and email will be used.  Just like in the generator, you can set this up with a list of values — but it has to have a bean list format, not a comma separated list. If I recall correctly, the logic will be “use the first non-null element from the list that is also in the metadata, or the first non-null element from relying-parties.xml, or the first non-null element from the metadata, or return null, whichever comes first”.

The key is just making sure that all the pieces line up — you need to use the same URN in both places, as well as making sure that the entityID matches.

---

FAQ

Service Provider-initiated SSO Error

Q: When the learner clicks the SSO login button on the Foundry customer login page, they get an immediate error on my institution’s login page saying “The request cannot be fulfilled because the message received does not meet the security requirements of the login service.” Why is this happening?

A: This probably means that your identity provider cannot validate Foundry’s signature in the AuthnRequest that Foundry sends to your IDP. Be sure that you have the correct Foundry signing certificate and issuer (entityID) in the Foundry service provider entry in your IDP.

Foundry signs with the certificate specified in the identity provider configuration in Foundry. Check that setting and be sure your IDP has the same certificate as a signing certificate.

Assuming that SSO had been working successfully earlier, then this type of error would only happen if changes were made to certificates which resulted in a certificate mismatch.