Creating and Testing a Shibboleth SP

In the following, the Shibboleth

Service Provider. A Shibboleth term. Synonym for an AAI-enabled Resource, although used in a more technical sense.

See: Federated Identity

is assumed as your software solution to set up a

Security Assertion Markup Language

See: http://en.wikipedia.org/wiki/SAML

Service Provider. There are two main steps to complete to create and configure an SP, and to have it included in the CLARIN Service Provider Federation.

Do You Need to Set Up an SP?

Each different SP incurs a considerable overhead on both your centre's staff and the CLARIN SPF team. Each identity federation has its own processes for managing registered SPs. Registering a new SP can take a full working day. Technical and legal compliancy issues cause a lot of e-mail traffic between various parties. Maintaining an SP and its dependencies requires (extra) expert IT staff. Whenever some detail about your SP changes, this has to be communicated to all identity federations. For instance, certificates, used for various purposes in the context of SPs, have expiry dates and replacing them requires an error prone key rollover procedure that additionally requires careful planning and coordination between your centre, the CLARIN SPF team and identity federations' staff.

1. Do you have resources that need protection through user authentication? If not, there is no need to set up an SP.
2. Ask whether it is possible to use one SP for all your centre's services. It is likely that many services can be combined on a single host, esp. access to static resources (protected content) can be centralized through a frontend reverse proxy, with different web servers/host in the backend if you are concerned about excessive load on the central host. To gain a better understanding of multiple resources/applications per SP, please read NativeSPApplicationModel.
3. If the previous solution is not possible, e.g. you cannot avoid having SAML-protected applications across different hosts, there are still a number of solutions. To best cope with such a challenge, it is important for your centre to have clear hosting policy, about which services are hosted where and how individual hosts can communicate securely and reliably. You need a backend host that runs the Shibboleth SP daemon and a webserver, but you can proxy to this host from frontends in a clustering solution. See e.g. NativeSPClusteringByProxy or, for a more general solution, NativeSPClustering.

To Set Up an SP

A good collection of tips and some tools that can also be used for the SPF and a Best Current Practices document that also covers organisational aspects have been made available by SWITCHaai.

NOTE: A detailed tutorial explaining the items below is available via https://clarin-eric.github.io/SPF-tutorial/Shib_SP_tutorial.html (html) or https://github.com/clarin-eric/SPF-tutorial/blob/master/Shib_SP_tutorial.adoc (adoc). 

• If you are hosting a Service Provider and want to make it available for use within the CLARIN Service Provider Federation, you need to configure it to consume the information (SAML metadata) about all the federation Identity Providers (IdPs) that the SPF has ties with, and optionally (recommended) the CLARIN Identity Provider. See the fragment in the sample configuration between comment tags 'MetadataProvider'.
• Unless you have specific reasons not to, please connect your SP to the CLARIN Discovery Service. See the fragment in the sample configuration between comment tags 'SSO'.
• Be sure to keep current and complete SAML metadata available at central location that you manage yourself. Assuming you use Shibboleth SP, use its MetadataGenerator handler to make sure the SAML metadata as known by your SP matches the version of the SAML metadata you commit to the CLARIN github repository (see next section). See the fragment in the sample configuration between comment tags 'MetadataGenerator'.

To Specify SAML Metadata about Your SP for the Identity Federations

After this you need to prepare a specification of your SP, the SAML metadata about your SP. This is necessary for it to be registered with the various Identity Federations that CLARIN SPF has ties with. It is important that you are especially thorough, careful and complete in your SAML metadata: we have encountered many time-consuming issues in getting Identity Federation administrators to accept SAML metadata that does not meet their quality or other standards.

NOTE: It is especially instructive and productive to base your SAML metadata on existent md:EntityDescriptor elements in the SAML metadata about SPF production SPs for reference.

1. Please start by working through https://wiki.shibboleth.net/confluence/display/CONCEPT/MetadataForSP.  
2. Next, go through our guidelines for SAML metadata about SPF SPs. (!)
3. Ultimately you should put your md:EntityDescriptor file in the directory https://github.com/clarin-eric/SPF-SPs-metadata/tree/master/metadata creating a pull request on its 'master' branch as described in: https://github.com/clarin-eric/SPF-SPs-metadata/blob/master/README.md.
4. Do make sure the clarin-sp-metadata.xml file is still valid after your very last edit. To help you with this, after creating the pull request, the check_saml_metadata.sh script (https://github.com/clarin-eric/SAML-metadata-checker) will run automatically on you pull request and the result will be visible in the pull overview. Only pull requests that pass this check will be considered. After this, the central office will review your SAML metadata and if no outstanding issues are found, merge add it to the CLARIN SPF pre-production metadata source file.

If no problems occur it might still take a few hours before your new SAML metadata has been consumed by the CLARIN

Identity Provider, a (Shibboleth) server that authenticates users and conveys their attributes to requesting resources. In other terms it provides the digital identities of its users to other servers in the AAI.

See: Federated Identity

. Propagation to eduGAIN and other national identity federations might take longer since the process is not controlled by the central office.

User Acceptance Testing within the Service Provider Federation

As SP operators cannot test logging in for their application with Identity Providers they don't have an account with, we also use manual (user acceptance) testing of applications and resources connected to the SPF. Every centre's technical contact can request a test of their SP(s). This will give reassurance about the proper configuration of and SAML metadata registration for that SP.

In case you operate an SP, and wish to test the possibility to log in and make use of a relevant application/resource, please create a Trac ticket for the '

Authentication and Authorization Infrastructure

See: Federated Identity

' Trac Component. A list of persons that are willing to login in for certain countries is available on the Trac as well.

Please provide the link to the login page and a detailed description on where to find the right button/form that should be tested. This assures that the tester is able to help you quickly.

Further Help

Please test your SP yourself too, for instance with https://access-check.edugain.org or http://www.testshib.org/.

In case your own AAI team is definitely stuck at some point, please create a Trac ticket for the AAI component. The CLARIN

European Research Infrastructure Consortium

See: https://research-and-innovation.ec.europa.eu/strategy/strategy-2020-2024/our-digital-future/european-research-infrastructures/eric_en

SPF team can if needed organize a remote technical session where we work in a concentrated and coordinated effort to get your SP up and running, and SPF-enabled.

Do you have questions and suggestions? Then please e-mail spf /at/ clarin.eu.