Skip to Content

Configuring Shibboleth SP

Last modified by Jukka Karvonen on 2025/03/25 09:24

Main configuration file is /etc/shibboleth/shibboleth2.xml. In addition, attribute map, attribute policy, protocols and security policy are defined in separate files.

Generic recommendations

IdP metadata

IdP metadata will be loaded by automatically by the shibd process. Local copy of this will be saved and it's recommended to create /etc/shibboleth/metadata -path for this and add shibd process write access to this path.

mkdir /etc/shibboleth/metadata
chmod 755 /etc/shibboleth/metadata
chown shibd:shibd /etc/shibboleth/metadata

Note. In Debian and Ubuntu, process and user are "_shibd"

Certificates

Certificates used by the Shibboleth SP should be created as self-signed certificates and ensure that read access to key is only for shibd-user.

Below is an example to create self-signed certificates for both signing and encryption. It's recommended to use separate certificates for these, if your SAML implementation supports it. Change the service name sp1.test.helsinki.fi to your service address.

openssl req -new -x509 -nodes -newkey rsa:4096 -keyout /etc/shibboleth/sp1-test-shib-encrypt-key.pem -days 3650 -subj '/CN=sp1.test.helsinki.fi' -out /etc/shibboleth/sp1-test-shib-encrypt-cert.pem
openssl req -new -x509 -nodes -newkey rsa:4096 -keyout /etc/shibboleth/sp1-test-shib-signing-key.pem -days 3650 -subj '/CN=sp1.test.helsinki.fi' -out /etc/shibboleth/sp1-test-shib-signing-cert.pem
chmod 640 /etc/shibboleth/sp1-test-shib-*-key.pem
chown root:shibd /etc/shibboleth/sp1-test-shib-*-key.pem

Note. In Debian and Ubuntu, process and user are "_shibd"

shibboleth2.xml

Primary configuration file. This may change slightly with different versions, so it is advisable to use the file included with the installation package for configuring new services and modify that.

Below is an example file for running the service on Linux servers. The main changes compared to the Windows/IIS configuration are listed separately.

Example

Below is an example of a Linux/Apache shibboleth2.xml. The main differences from the service's included template file are as follows:

  • entityID is named according to the service, and message signing configurations have been added.
  • In the Sessions section, handlerSSL is enabled, and cookieProps are encrypted. These are practically mandatory.
  • checkAddress could theoretically increase security, but may cause issues in services behind NAT or if the client or service only supports IPv4/IPv6 protocols. consistentAddress is also enabled by default and addresses the same security threat as checkAddress, i.e., the service requests a new login if the session IP changes.
  • From SSO, the Discovery protocol configuration, which is only needed when using multiple IdPs (e.g., Haka), has been removed.
  • Single Logout (SLO):
    • In the Notify section, you can configure Shibboleth SP to notify the service of a logout request. More information at https://wiki.shibboleth.net/confluence/display/SP3/Notify
    • If the service is configured at the Apache level to deny access to everyone except logged-in users, the application may not need to be notified of the logout, and the Notify element can be removed.
    • If the service does not support SLO (mandatory in Haka federation!):
      • Remove "SAML2" from between the Logout tags, leaving only "Local".
      • Remove the "Notify" line from the configuration.
  • Errors supportContact section: The email address mentioned should be visible to the user if an unexpected error occurs in Shibboleth. This address must be the service's technical support address, not, for example, the IdP support address, as troubleshooting requires access to the service logs.
  • Local storage of metadata is fetched as mentioned above into a separate folder. Additionally, the RequireValidUntil value is commented out, as HY's local IdP's metadata currently does not provide a validity period. This is mandatory when using Haka's metadata.
  • In the CredentialResolver section, certificates and keys refer to previously created files.
<?xml version="1.0"?>
<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config" xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config" clockSkew="180">
  <OutOfProcess tranLogFormat="%u|%s|%IDP|%i|%ac|%t|%attr|%n|%b|%E|%S|%SS|%L|%UA|%a"/>
  <ApplicationDefaults entityID="https://sp1.test.helsinki.fi/sp" REMOTE_USER="eppn" signing="true" cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">
    <Sessions lifetime="28800" timeout="3600" relayState="ss:mem" checkAddress="false" handlerSSL="true" cookieProps="https" redirectLimit="exact">
      <SSO entityID="https://login.helsinki.fi/shibboleth">SAML2</SSO>
      <Logout>SAML2 Local</Logout>
      <LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1"/>
      <!-- <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/> -->
      <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
      <Handler type="Session" Location="/Session" showAttributeValues="false"/>
      <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
    </Sessions>
    <Errors supportContact="palvelun-kontakti-osoite@helsinki.fi" helpLocation="/about.html" styleSheet="/shibboleth-sp/main.css"/>
    <Notify Channel="front" Location="https://sp1.test.helsinki.fi/logout"/>
    <MetadataProvider type="XML" reloadInterval="7200" url="https://login.helsinki.fi/metadata/sign-hy-metadata-v2.xml" backingFilePath="/etc/shibboleth/metadata/sign-hy-metadata.xml">
      <MetadataFilter type="Signature" certificate="sign-login.helsinki.fi-v2.pem"/>
    </MetadataProvider>
    <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
    <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
    <CredentialResolver type="File" use="signing" key="sp1-test-shib-signing-key.pem" certificate="sp1-test-shib-signing-cert.pem"/>
    <CredentialResolver type="File" use="encryption" key="sp1-test-shib-encrypt-key.pem" certificate="sp1-test-shib-encrypt-cert.pem"/>
  </ApplicationDefaults>
  <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
  <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
</SPConfig>

Configuring discovery service for federated authentication

If your service is in Haka or eduGAIN federation, your users need to way to select the IdP they are using to log in. Discovery Service is the recommended way to do this.

If you have only some IdP's allowed, you can also create direct login links to them.

Instead of just setting SSO shorthand in sessions configuration, you can use following configuration to use Haka DS service for Haka and SeamlessAccess for eduGAIN.

    <SSO entityID="https://login.helsinki.fi/shibboleth">SAML2</SSO>
    <!-- SAML logout only -->
    <Logout>SAML2</Logout>

    <!-- Sessioninitiators for HAKA -->
    <SessionInitiator type="Chaining" Location="/HAKALogin" id="HAKA" relayState="cookie">
      <SessionInitiator type="SAML2" template="bindingTemplate.html"/>
      <SessionInitiator type="SAMLDS" URL="https://haka.funet.fi/shibboleth/WAYF"/>
    </SessionInitiator>

    <!-- Sessionionitiators for eduGAIN -->
    <SessionInitiator type="Chaining" Location="/eduGAINLogin" id="EDUGAIN" relayState="cookie">
      <SessionInitiator type="SAML2" template="bindingTemplate.html"/>
      <SessionInitiator type="SAMLDS" URL="https://service.seamlessaccess.org/ds/"/>
    </SessionInitiator>

Then you configure your service to redirect user to

  • /Shibboleth.sso/Login for University of Helsinki SSO
  • /Shibboleth.sso/HAKALogin for Haka login (user is redirected to Haka DS for IdP selection)
  • /Shibboleth.sso/eduGAINLogin for eduGAIN login (user is redirected to SeamlessAccess DS for IdP selection)

After selecting IdP, Shibboleth SP redirects user to that IdP if metadata for that IdP is available.

eduGAIN and embedded discovery service

It's also possible to use EDS (Embedded Discovery Service) where the list of allowed IdP's are created directly from the metadata.

SeamlessAccess includes all eduGAIN IdPs so if you are only allowing some, it is easier for users to receive filtered list.

Read more from the Haka wiki: https://wiki.eduuni.fi/pages/viewpage.action?pageId=27297748

Configuring metadata for federated authentication

Check metadata locations from: IdP metadata.

To use federations, you need to load federation metadata. Instead of loading only HY metadata, you load different metadata file for HY, Haka and/or eduGAIN. HY metadata is included in the Haka metadata so you could skip it.

Remember to load signing certificates and set correct locations to configuration.

    <!-- HY metadata -->
    <MetadataProvider type="XML" url="https://login.helsinki.fi/metadata/sign-hy-metadata-v2.xml"
        backingFilePath="/etc/shibboleth/metadata/sign-hy-metadata-v2.xml" reloadInterval="7200">
      <MetadataFilter type="Signature" certificate="/etc/shibboleth/sign-login.helsinki.fi-v2.pem"/>
    </MetadataProvider>

    <!-- Haka metadata -->
    <MetadataProvider type="XML" url="https://haka.funet.fi/metadata/haka-metadata-v9.xml"
        backingFilePath="/etc/shibboleth/metadata/haka-metadata.xml" reloadInterval="7200">
      <MetadataFilter type="Signature" certificate="/etc/shibboleth/haka-sign-v9.pem"/>
    </MetadataProvider>

    <!-- eduGAIN metadata -->
    <MetadataProvider type="XML" url="https://haka.funet.fi/edugain-nightly/gen-edugain/sp-XX-metadata-eduGain.xml"
        backingFilePath="/etc/shibboleth/metadata/edugain-metadata.xml" reloadInterval="86400">
      <MetadataFilter type="Signature" certificate="/etc/shibboleth/haka-edugain-sign.csc.fi.2024.pem"/>
    </MetadataProvider>

While you could load eduGAIN metadata in the same way as Haka metadata, if you allow all eduGAIN entities to log in, it's quite big metadata file to load and in addition to used bandwidth, processing takes time and may increase Shibboleth SP startup time to several minutes.

IT is possible to load and verify metadata separately, check the script from: eduGAIN metadata script.

Considerations with IIS

In Apache configuration, sites and locations using Shibboleth are defined in Apache's configuration files. On IIS, these are defined directly in Shibboleth's settings. Shibboleth's IIS instructions can be found at https://wiki.shibboleth.net/confluence/display/SP3/IIS

  • In ISAPI section you list all site identifiers where you want to use Shibboleth authentication.
  • In RequestMap you specify how, and in which locations.

The example below would require a Shibboleth session throughout the site https://site1.example.org/ and at https://site2.example.org:446/secure. In the latter, it would also require that the user has a staff value in the affiliation attribute.

<?xml version="1.0"?>
<SPConfig...>
  ...
  <InProcess logger="native.logger">
    <ISAPI normalizeRequest="true" safeHeaderNames="true">
      <Site id="1" name="site1.example.org" port="443" scheme="https"/>
      <Site id="2" name="site2.example.org" port="446" scheme="https"/>
    </ISAPI>
  </InProcess>...    
  <RequestMapper type="Native">
    <RequestMap>
      <Host name="site1.example.org" scheme="https" port="443" authType="shibboleth" requireSession="true"/>
      <Host name="site2.example.org" scheme="https" port="446">
        <Path name="secure" authType="shibboleth" requireSession="true">
          <AccessControl>
            <Rule require="affiliation">staff</Rule>
          </AccessControl>
        </Path>
      </Host>
    </RequestMap>
  </RequestMapper>
  ...
</SPConfig>

attribute-map.xml

In attribute-map.xml, the attributes fetched from the service's IdP are defined. At its simplest, there is one unique identifier fetched into the REMOTE_USER value, e.g., uid or eppn (eduPersonPrincipalName).

Example

Five common attributes are parsed from the user, ensuring the eppn value is in the form "value@scope". In the case of HY, this is "uid@helsinki.fi".

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
  </Attribute>
  <Attribute name="urn:oid:2.5.4.4" id="sn"/>
  <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
  <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
  <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="affiliation"/>
</Attributes>

attribute-policy.xml

In attribute-policy.xml, filters can be specified for received values, e.g., specific values or using regex. However, checks are often not made here but in the attribute-processing application. The example file works as a suitable policy in most cases, and it includes examples for modifications.

Attribute scoping in the test service

When working with a test-IdP, check the ScopingRules section, which is applied to attributes selected in attribute-map settings with ScopedAttributeDecoder, usually eduPersonPrincipalName.

By default, this restricts the scope to values according to the IdP's metadata, aiming to prevent, for example, another IdP from providing a "@helsinki.fi" scope.

In the test service, you can define user values, including scope yourself; if you want to use a scope other than "@helsinki.fi" provided in the test service's metadata, remove the <Rule xsi:type="saml:AttributeScopeMatchesShibMDScope"/> setting from under the ScopingRules section.

protocols.xml

In protocols.xml, the protocols accepted by the SP in different situations are defined. This could be left to default but it's better for security to remove unused protocols and enpoints.. The protocol families are defined in the SSO section of shibboleth2.xml (in the example, only SAML2 is left).

In practice, only protocols required are:

  • SAML2 SSO HTTP-POST is needed for login
  • SAML2 Logout HTTP-Redirect or Local Logout is needed for logout, depending on services SLO supported.

Example containing only the protocols and endpoints mentioning above:

<Protocols xmlns="urn:mace:shibboleth:2.0:native:sp:protocols">
  <!-- SAML 2.0 -->
  <Protocol id="SAML2">
    <Service id="SSO">
      <Initiator id="SAML2" />
      <Binding id="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" path="/SAML2/POST" />
    </Service>
    <Service id="Logout">
      <Initiator id="SAML2" />
      <Binding id="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" path="/SLO/Redirect" />
    </Service>
  </Protocol>
  <!-- Local Logout -->
  <Protocol id="Local">
    <Service id="Logout">
      <Initiator id="Local" />
    </Service>
  </Protocol>
</Protocols>

Service Metadata

In the shibboleth2.xml file, the MetadataGenerator section is commented out because it is a feature intended for test use. However, this can temporarily enable the technical base information of the service to be exported to the SP Registry after configuring the service.

Once the service is configured and set up as a module in Apache, go to https://sp1.test.helsinki.fi/Shibboleth.sso/Metadata (or whatever the service address is). The automatically generated metadata includes most of the required technical configuration and can be used to create a new service in SP Registry.