A common task when running a SAML Identity Provider (IdP) is integrating additional SAML service providers (SP). This task is not a trivial one, especially when compared to integrating CAS clients. New IdP administrators can run into problems before they even start with the technical task at hand because they aren't given the correct information to be successful. The request to do an integration usually goes something like this:
Project Lead: "Hey Johnny (IdP Admin), we need you to integrate *insert latest and greatest web-based software acquisition* with SSO. The vendor said it's fully supported. Here are the instructions. They don't make sense to me but you are the expert."
Within seconds a seasoned admin will recognized that there are many un-answered questions. They expect it. Unfortunately, rookie IdP admins don't know that they are doomed. They probably have just enough information to start configuring the integration but will quickly realized that they are stumped.
This post should be helpful to IdP admins, as well as others involved in the process, when integrating a new service provider. These questions need to be answered before an IdP admin starts to configure the IdP for the new provider:
1. Is the service provider vendor-hosted or an on-prem(esis) app? If on-prem, does the application natively support SAML or will something like the Shib SP need to be configured?
Background: IdP admins need to know the terrain of the implementation. Where are the moving parts? This really sets up every other question.
Commentary: I once helped a client with an SP integration and had done our side of the implementation based on the instructions found online that someone forwarded to us. It was only when we were ready to test that we found out that the organization actually hosted their own deployment. The directions we had been given did not apply to us... there was another set of instructions for us to follow.
2. Who is my contact on the service provider side?
Background: Very few applications (SPs) make the authentication logs available through a user accessible interface. An IdP admin needs to know who to contact for answers because once the SAML request has left the IdP, an IdP admin will not know the cause of any SP-side authentication failures. It is often necessary to have a phone call or mutliple back and forths emails between the IdP and SP admins.
Commentary: Integrating an IdP and SP is a more like a dance than solitaire. Even if both sides know the dance steps well, there is still nuance to how each side performs them. Do not feel bad asking for the tech (yes, the tech) that understands how the SP needs the IdP to be configured.
3. Where is the service provider metadata, and where do I send my metadata?
Background: Metadata is what is used to establish trust and communication between the IdP and the SP. Both sides have their own and both sides need the other's.
Commentary: This is where everyone prays that the other side is an active InCommon member. If so, then this step is done for you. If they are not, then hopefully the SP supports the OASIS metadata standard format. If not and you are using Shibboleth IdP, you'll be mucking around in XML for a while to create what Shib IdP needs.
4. How is the SAML-based SSO actually enabled within the application?
Background: The IdP is only one side of the equation. How and who is responsible for enabling it on the SP? Some applications provide a nice UI to configure, and enable SSO, on the SP side. Other times it requires manual configuration on the application server side and must be done by the vendor (if cloud hosted).
Commentary: There is nothing like the feeling of completing your work on the IdP side and informing the project lead that your work is done and getting a response of "Uhm, I still see the normal login page, not the our's". Know upfront whose job it is to flip the switch... Again it is a dance. It works better when you have a partner and know who it is. Then again, maybe it is yourself... In many cases, the app owner will ask the IdP admin to finish their side of the config because they do not underdstand what needs to go where when setting up the SAML config on the SP.
5. What url do I need to visit to see the SSO actually get invoked?
Background: Knowing how the SSO is invoked is helpful when testing. Some (cloud) apps require a completely new URL to be used by the user to invoke the SAML SSO. Going to the "standard" (old) url will never invoke SSO because the app was not designed that way. It can support multiple authentication methods.
Commentary: Similar to item #4, we did our side and as far as we can tell the SP side has been configured, but the project lead says it's not working. Surprise, surprise, there is a magic URL that is used for SAML-based auth, but it was not documented anywhere. Save yourself some time and ask beforehand. In some cases, especially when SSO-enabling an existing service "deep-links" found throughout the organizations website had to be changed. Someone had a worse day than we did.
6. Does the service provider support encrypted assertions?
Background: After successfully configuring the IdP and running a test, the AuthnResponse will be sent to the SP and it fails, why? Many SPs cannot handle encrypted responses and many IdPs do it by default.
Commentary: This is the primary scenario of nothing being apparently wrong on our side, but it failed and we cannot see the logs on the SP side. Turn off assertion encryption and it just might work. The plus side is that you can now easily decode the AuthnResponse and look at what is actually being sent to the SP.
7. What attributes does the service provider need, and how is the user id presented?
Background: In SAML, the user's identity can be sent in two places: the Subject's NameId or as an attribute. The IdP has to be configured to place it in the same location the SP will be looking for it. For attributes you will also need to know what the SAML name is of the attributes that are to be sent to the SP. The "SAML" name of an attribute should (almost) never be something like "givenName", "sn", etc. It will be a URI. Something that looks like a URL ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname") or something that looks like "urn:oid:2.5.4.42".
Commentary: This should be so simple, but often is overly complicated. Vendors just do not understand this. If you can't get a list of attributes that look valid, then see your answer for question #2.
Bonus Question: Do you have a sample SAML Response that I can reference?
Background: Having a sample response is more valuable than any documentation.
Commentary: If you can get a sample, you will feel like you are cheating. It will answer all your questions, unless of course the vendor gave you something that they just "googled". *sigh* If that's the case, good luck and give Unicon a call. We will be the bad guy so you do not have to be.
If you can't find the answers to these questions in the SP documentation, then work with the project lead to get the answers... before you start changing the IdP configuration. Unicon IAM staff cannot even do the integration if we do not have these answers. :)
