Info |
---|
Please start here if you want to connect your service to the SURFconext platform |
Shibboleth is a free, open-source web single sign-on system with rich attribute-exchange based on open standards, principally SAML. It supports both Apache (on several platforms, notably Linux, OSX, Solaris, and Windows), and several versions of Microsoft IIS (5, 6, 7).
...
Warning | ||
---|---|---|
| ||
Take note that the metadata and the metadata locations used for the test and production environments of SURFconext differ. Use them accordingly: |
...
Start by setting up Apache as you normally would. The The SP to connect to SURFconext should be using HTTPS with valid certificates (self-signed certificates do not suffice). An An example configuration file for the SP could look like this:
Code Block | ||||
---|---|---|---|---|
| ||||
<VirtualHost _default_:443> Servername mfspmysp.gadgetsexample.surfconext.nlorg ServerAdmin bas.zoetekouw@surfnet.nlserver-admin@example.org DocumentRoot /var/www/mfspmysp <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /var/www/> Options Indexes FollowSymLinks MultiViews AllowOverride None </Directory> SSLEngine on SSLCertificateFile /etc/ssl/certs/yourhostmy_https_server.crt SSLCertificateKeyFile /etc/ssl/private/yourhostmy_https_server.key </VirtualHost> |
Then, install Shibboleth. In In Debian and Ubuntu, the package is called libapache2called libapache2-mod-shib (or libapache2-mod-shib2 in older releases), and simply apt-getting will work fine.
Shibboleth consists of two parts: a daemon (shibd) that handles communication with the SP and IdPs, and an Apache module that handles the authentication in the web server. Make Make sure that the daemon is running, and that the Apache module is loaded (a2enmod shiba2enmod shib; apachectl -k graceful).
If everything is set up correctly, you should be able to reach https://mfspmysp.gadgetsexample.surfconext.nlorg/Shibboleth.sso/Status (substitute your local host name, obviously). This should show Shibboleth status information in XML form. Note Note that this link will only work from a remote machine if you modify the access control list (acl) attribute of the <Handler type="Status"> entry in the /etc/shibboleth/shibboleth2.xml
file (the file is named shibboleth2.xml
also in version 3 and later).
The file should look like this:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<StatusHandler time="2011-10-14T14:06:55Z"> <Version Xerces-C="3.2.1" XML-Tooling-C="3.0.3" XML-Security-C="2.0.2" OpenSAML-C="3.0.0" Shibboleth="3.0.3"/> <NonWindows sysname="Linux" nodename="mfspmysp" release="3.10.0-862.14.4.el7.x86_64" version="#1 SMP Wed Sep 26 15:12:11 UTC 2018" machine="i686"/> <SessionCache> <OK/> </SessionCache> <Application id="default" entityID="https://spmysp.example.org/shibboleth"/> <Handlers> <Handler type="ArtifactResolutionService" Location="/Artifact/SOAP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/> <Handler type="AssertionConsumerService" Location="/SAML2/POST" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/> <Handler type="AssertionConsumerService" Location="/SAML2/POST-SimpleSign" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign"/> <Handler type="AssertionConsumerService" Location="/SAML2/Artifact" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/> <Handler type="AssertionConsumerService" Location="/SAML2/ECP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS"/> <Handler type="AssertionConsumerService" Location="/SAML/POST" Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/> <Handler type="AssertionConsumerService" Location="/SAML/Artifact" Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/> <Handler type="SessionInitiator" Location="/Login"/> <Handler type="SingleLogoutService" Location="/SLO/SOAP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/> <Handler type="SingleLogoutService" Location="/SLO/Redirect" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/> <Handler type="SingleLogoutService" Location="/SLO/POST" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/> <Handler type="SingleLogoutService" Location="/SLO/Artifact" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/> <Handler type="LogoutInitiator" Location="/Logout"/> <Handler type="MetadataGenerator" Location="/Metadata"/> <Handler type="Status" Location="/Status"/> <Handler type="Session" Location="/Session"/> <Handler type="DiscoveryFeed" Location="/DiscoFeed"/> </Handlers> <Status> <OK/> </Status> </StatusHandler> |
...
Next, Shibboleth needs to be set up as an SP. The The configuration process is described more elaborately at https://wiki.shibboleth.net/confluence/display/SP3/GettingStarted, but the instructions below should get you up to speed quickly.
...
Start by generating a new SSL RSA key pair and a self signed certificate. This This key pair will be is used by Shibboleth to sign its SAML metadata and to sign SAML messages that are exchanged between SURFconext and your SPit sends to other partie like SURFconext.
Code Block |
---|
openssl req -newkey rsa:4096 -new -x509 -days 3652 -nodes -text -out shib.crt -keyout shib.key |
...
Change owner of the private key so shibd can read it:
Code Block | ||
---|---|---|
| ||
chown _shibd /etc/shibboleth/shib.key |
Then download the SURFconext metadata signing certificate. The wget command downloads the certificate and writes is to a filename of your choice, e.g:
...
from https://metadata.surfconext.nl/
...
...
.xml (production) or https://metadata.test.surfconext.nl/idp-metadata.xml (test).
Code Block |
---|
wget https://metadata.surfconext.nl/idp-metadata.xml --output-document=/etc/shibboleth/surfconext-idp-metadata.xml |
...
Edit /etc/shibboleth/shibboleth2.xml
and make the following changes:
Change the
entityID
in the<ApplicationDefaults>
section to the URI of your SP. This defines the name by which SURFconext will refer to your SP. The value should be a proper URL, for exampleCode Block <ApplicationDefaults entityID="https://mfspmysp.gadgetsexample.surfconext.nlorg/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">
In the
<ApplicationDefaults>
section, add the names of the key and certificate file that you have just created.Code Block <CredentialResolver type="File" key="shib.key" certificate="shib.crt"/>
Inside the
<ApplicationDefaults>
section, add a MetadataProvider for SURFconext. This This tells Shibboleth where to find SURFconext's SAML metadata:. In this step we use the meatadata that you just downloadedCode Block controls true language xml theme Default xml theme Default <MetadataProvider type="XML" url="https://metadata.surfconext.nl/idp-metadata.xml<MetadataProvider type="XML" backingFilePathpath="metadata-surfconext/etc/shibboleth/surfconext-idp-metadata.xml" reloadInterval="7200"> <MetadataFilter type="Signature" certificate="surfconext.pem"/> </MetadataProvider>
Inside the
<ApplicationDefaults>
section should be a<Sessions>
section. In there, add a Single Sign-On entry for SURFconext. This tells Shibboleth that SURFconext users can use Single Sign-On and that authentication information with SURFconext should be exchanged using SAML2.Code Block language xml <SSO entityID="https://engine.surfconext.nl/authentication/idp/metadata">SAML2</SSO>
Inside the
<ApplicationDefaults>
section should be a<Sessions>
section. In that section. aMetadataGenerator
handler should be defined. Here, you need to add additional information about your service and your organization. Edit the section to look like this:Code Block language xml <Handler type="MetadataGenerator" Location="/Metadata" signing="true"> <mdui:UIInfo> <mdui:DisplayName xml:lang="nl">Voorbeelddienst</mdui:DisplayName> <mdui:DisplayName xml:lang="en">Example Service</mdui:DisplayName> <mdui:Description xml:lang="nl">Een mooie voorbeelddienst om te laten zien hoe Shibboleth werkt</mdui:Description> <mdui:Description xml:lang="en">A nice example Service to show how to work with Shibboleth and SURFconext</mdui:Description> <mdui:Logo height="300" width="500">https://plaatjes.example.com/media/plaatje.png</mdui:Logo> </mdui:UIInfo> <md:Organization> <md:OrganizationName xml:lang="nl">Voorbeeld BV</md:OrganizationName> <md:OrganizationName xml:lang="en">Example BV</md:OrganizationName> <md:OrganizationDisplayName xml:lang="nl">Voorbeeld</md:OrganizationDisplayName> <md:OrganizationDisplayName xml:lang="en">Example</md:OrganizationDisplayName> <md:OrganizationURL xml:lang="nl">http://www.example.org</md:OrganizationURL> <md:OrganizationURL xml:lang="en">http://www.exampler.org/en</md:OrganizationURL> </md:Organization> <md:ContactPerson contactType="support"> <md:GivenName>Piet</md:GivenName> <md:SurName>Jansen</md:SurName> <md:EmailAddress>piet.Jansen@example.org</md:EmailAddress> </md:ContactPerson> <md:ContactPerson contactType="technical"> <md:GivenName>Klaas</md:GivenName> <md:SurName>Jansen</md:SurName> <md:EmailAddress>klaas.jansen@example.org</md:EmailAddress> </md:ContactPerson> <md:ContactPerson contactType="administrative"> <md:GivenName>Jans</md:GivenName> <md:SurName>Jansen</md:SurName> <md:EmailAddress>jans.jansen@example.org</md:EmailAddress> </md:ContactPerson> </Handler>
Additionally, make sure the
md
andmdui
xml namespaces are defined in the<SPConfig>
tag on the top ofshibboleth.xml
:Code Block <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" clockSkew="180">
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" clockSkew="180"> <ApplicationDefaults entityID="https://mfsp.gadgets.surfconext.nl/shibboleth" REMOTE_USER="eppn persistent-id targeted-id"> <Sessions lifetime="28800" timeout="3600" checkAddress="false" redirectLimit="exact" relayState="ss:mem" handlerSSL="false"> <SSO entityID="https://engine.surfconext.nl/authentication/idp/metadata">SAML2</SSO> <Logout>SAML2 Local</Logout> <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/> <Handler type="Status" Location="/Status"/> <Handler type="Session" Location="/Session" showAttributeValues="false"/> <Handler type="DiscoveryFeed" Location="/DiscoFeed"/> </Sessions> <Errors supportContact="root@localhost" logoLocation="/shibboleth-sp/logo.jpg" styleSheet="/shibboleth-sp/main.css"/> <MetadataProvider type="XML" uripath="https:/etc/metadata.surfconext.nl/shibboleth/surfconext-idp-metadata.xml" backingFilePath="metadata-surfconext.xml" reloadInterval="7200"> <MetadataFilter type="RequireValidUntil" maxValidityInterval="172800"/> <MetadataFilter type="Signature" certificate="surfconext.pem"/> </MetadataProvider></MetadataProvider> <AttributeExtractor type="XML" validate="true" path="attribute-map.xml"/> <AttributeResolver type="Query" subjectMatch="true"/> <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/> <CredentialResolver type="File" key="shib.key" certificate="shib.crt"/> </ApplicationDefaults> <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/> <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/> </SPConfig> |
...