SAML IDP / SP - In-Depth Configuration Details
In SAML, there are 3 roles:
A SAML IDP generates a SAML response based on the configuration that is mutually agreed to by the IDP and the SP. After receiving the SAML assertion, the SP needs to validate that the assertion comes from a valid IdP and then parse the necessary information from the assertion: the username, attributes, and so on.
There are two ways to implement it:
In our system, we are using the latter, and our system plays the SP role. In the following document, the SP is equated to OL.
From this diagram, you could see the SP initiated flow always starts with SAML Request from the SP end, and the IDP end will send a SAML Response.
Configure the IDP in OpenLearning
You should find the IDP configuration settings under Institution Settings > Integrations > SAML Identity Provider(IDP) Configuration.
We could add multiple IDPs to one institution.
Name: you could name your IDP under your institution, so this name should be unique under your institution.
And for these fields: “Entity ID”, “Sign-in URL”, and “certificate”, you could find them from the IDP metadata or the IDP SAML configuration in the IDP application. But it is always easier to find them from the metadata because each application has its own naming rules, they might be called differently, but in the metadata, they are applying the same standard. I’ll show you how to find them from the metadata.
At first, you should make sure the metadata has an element
IDPSSODescriptor which is distinguished from the SP metadata.
Entity ID/Issuer URL
Sign-In URL: SAML requestors and responders communicate by exchanging messages. The mechanism to transport these messages is called SAML binding. As a requester, we are using HTTP redirect bindings. In IDP metadata, you might see some other bindings, so make sure you’re choosing the right sign-in URL under the element
Certificate: for some IDP, they might have different certificate elements, but we only need that one for “signing”.
Configure the SP in IDP application
Reply(ACS) Url: https://www.openlearning.com/saml/
SP Public Key: you could find it from our metadata https://www.openlearning.com/saml-metadata/, and we use the same key for signing and encryption, so just choose any element
Attributes: If the IDP is registered in the Austrian Access Federation, most of the attributes are added to AAF core attributes, possibly the IDP needs to add
dsdStudentIDto their IDP if they prefer to use it as the external id.
Description: Email address.
Description: Preferred name of a person to be used when displaying entries.
Description: eduPerson affiliation attribute, emits scoped affiliation based on LBNL employee status as stored in the LDAP directory. Possible values are Staff@uni, Guest@uni, Other@luni, and Member@uni.
Description: eduPersonPrincipalName is an attribute from the eduPerson schema and is released as a primary username for our participation in the InCommon identity federation..
Description: This is generally the student's id number. Usually, we use this as the institution external id, if this is not provided, we will use
Troubleshooting & testing the integration
There are two ways to start a test.
If you only have one IDP, you could copy that IDP launch URL from SAML Identity Provider(IDP) Configuration.
Another entry point:
https://www.openlearning.com/saml-sso/<institution_path>/, you could test any IDP from this entry point.
Here are some useful tools to help you identify the configuration problem.
Let’s start from the launch URL, and open the SAML chrome panel.
After launching, the end user will be redirected to IDP. You might notice that the request URL is the sign-in URL in the IDP configuration.
After sign-in, it sends the SAML Response to the Reply(ACS) Url.
Due to some mistakes in the SP and IDP configuration, you might see some errors when you get the SAML response, that’s because the response is not what we want, here are some response examples: SAML Response, but we expect to receive the SAML Response with Signed Message & Encrypted Assertion.
Signature validation failed. SAML Response rejected
Reason: the IDP might use the wrong certificate in the IDP configuration (Institution admin → Integrations → SAML Identity Provider(IDP) Configuration).
The assertion of the Response is not encrypted and the SP require it
Reason: the IDP might need to set the SP public key in the SP configuration.
The Message of the Response is not signed and the SP require it
Reason: the IDP might need to change the signing option to “Sign SAML response and assertion”.
eduPersonPrincipalName is not set
- Reason: the IDP doesn’t add this attribute.
UPDATE: Incompatibility of Shibboleth 4 with Python 3
OpenLearning's SAML implementation is currently using Python version 3.7 and if your IDP has recently been updated to Shibboleth 4, you would need to make some changes to your configuration.
In order to get this working with the platform, you will need to set an exception to the configuration allowing the AES128-CBC encryption, as explained in the link here:
Example of the updated metadata-providers.xml file.
<MetadataFilter xsi:type="Algorithm"> <!-- CBC-only SPs. --> <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc" /> <Entity> https://www.openlearning.com/saml-metadata/</Entity> </MetadataFilter>