Versions Compared

Old Version 2

changes.mady.by.user Stephen Lovell

Saved on

compared with

New Version Current

changes.mady.by.user Héder Mihály

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Info

This guide describes how the Shibboleth v3 SP can be configured as a SAML Service Provider for eduTEAMS. 

Shibboleth (pronounced "Shibboleth") is the reference implementation of the OASIS SAML standard.

Setting Installing and setting up the Shibboleth Service Provider in full is beyond the scope of this document. Many resources are available, such as the Shibboleth Wiki (https://wiki.shibboleth.net) and the installation instructions supplied and maintained by SWITCH (https://www.switch.ch/aai/guides/sp/installation/).

It is assumed in the following that you are using Shibboleth's v3 SP alongside the Apache webserver. If you are using a different webserver, the configuration of the SP should remain the same, with any differences being a requirement of your chosen web server.


1. Shibboleth configuration

Locate the file shibboleth2.xml. For example, using the switch.ch instructions (see above) for an Ubuntu Linux system, you will find the file at /etc/shibboleth/shibboleth2.xml.


We show to the right, sections of the file in which you will need to enter information relevant to your installation.



Enter your [your_sp_entity_id]:

eg https://example.com/shibboleth

Code Block
languagexml
<!
[...]
<!
-- By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache are used. See example-shibboleth2.xml for samples of explicitly configuring them. -->


<!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->


<ApplicationDefaults entityID="
https://rohu.geant.org/shibboleth"
[your_sp_entity_id]"
    REMOTE_USER="
mail
eduPersonUniqueId"


    cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:


                  !TLSv1:!TLSv1.1"


    >
[...][...]
<!--
Configures SSO for a default IdP. To properly allow for >1 IdP, remove
entityID property and adjust discoveryURL to point to discovery service.
You can also override entityID on /Login query string, or in RequestMap/htaccess.
-->
<SSO entityID="https://login.terena.org/wayf/saml2/idp/metadata.php">
SAML2
</SSO>
[...]
[...]
<SessionInitiator type="Chaining" Location="/Login" isDefault="true" id="Login"
entityID="https://login.terena.org/wayf/saml2/idp/metadata.php"
target="https://rohu.geant.org/"


Make sure handlerSSL="true" cookieProps="https" exist as follows:

Code Block
languagexml
        <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                  checkAddress="false" handlerSSL="true" cookieProps="https">

We would also encourage you to consider redirectLimit="exact" in the above <Sessions .... > section. You might find the following useful : https://wiki.shibboleth.net/confluence/display/SP3/Sessions


Enter your [vo_entity_id]:

eg https://proxy.eduteams.org/proxy

Code Block
languagexml
<!--
Configures SSO for a default IdP. To properly allow for >1 IdP, remove
entityID property and adjust discoveryURL to point to discovery service.
You can also override entityID on /Login query string, or in RequestMap/htaccess.
-->
<SSO entityID="https://proxy.eduteams.org/proxy">
SAML2
</SSO>


Enter [your_support_email_address]:

eg support@example.com

Code Block
languagexml
<!--
        Allows overriding of error template information/filenames. You can
relayState="cookie">
<SessionInitiator type="SAML2" template="bindingTemplate.html"/>
also add your own attributes with values that can be plugged into the
<SessionInitiator type="Shib1"/>
</SessionInitiator>
[...]<!--
Allows overriding of error template information/filenames. You can
also add your own attributes with values that can be plugged into the
templates, e.g., helpLocation below.
-->
<Errors supportContact="support@rohu.geant.org"
templates, e.g., helpLocation below.
        -->
        <Errors supportContact="[your_support_email_address]"
            helpLocation="/about.html"


            styleSheet="/shibboleth-sp/main.css"/>


Add the filename of the local copy of the eduTEAMS proxy's metadata
Code Block
languagexml
Code Block
languagexml
<!--
        Allows overriding<!-- Example of errorlocally templatemaintained information/filenamesmetadata. You can-->
        also<!--
 add your own attributes with values that can be plugged into the<MetadataProvider type="XML" validate="true" path="partner-metadata.xml"/>
        templates, e.g., helpLocation below.
       -->
       <!-- Metadata for the eduTEAMS proxy -->
       <MetadataProvider <Errors supportContacttype="support@rohu.geant.orgXML"
            helpLocation="/about.html"
            styleSheet="/shibboleth-sp/main.css"/>

 validate="true" path="proxy.eduteams.org-frontend.xml" />


Now save a copy of the eduTEAMS proxy metadata to the file /etc/shibboleth/proxy.eduteams.org-frontend.xml

eg

wget "https://<your-proxy-endpoint>/metadata/frontend.xml" -O /etc/shibboleth/proxy.eduteams.org-frontend.xml


Finally, set up the signing and encryption certificates.
Please note the filenames used for the signing and encryption certificates. See note below the following snippet for help with these files if required.

Code Block
languagexml
Code Block
languagexml
<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" />

    <!--
    By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache
    are used. See example-shibboleth2.xml for samples of explicitly configuring them.
    -->

    <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
    <ApplicationDefaults entityID="https://rohu.geant.org/shibboleth"
        REMOTE_USER="mail"
        cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1"
        >
        <!--        sessionHook="/Shibboleth.sso/AttrChecker"-->
        <!--
        Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
        Each Application has an effectively unique handlerURL, which defaults to "/Shibboleth.sso"
        and should be a relative path, with the SP computing the full value based on the virtual
        host. Using handlerSSL="true" will force the protocol to be https. You should also set
        cookieProps to "https" for SSL-only sites. Note that while we default checkAddress to
        "false", this makes an assertion stolen in transit easier for attackers to misuse.
        -->
        <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                  checkAddress="false" handlerSSL="true" cookieProps="https">

            <!--
 Simple file-based          Configures SSO resolvers for aseparate defaultsigning/encryption IdP. To properly allow for >1 IdP, remove
     keys. -->
       entityID property and adjust discoveryURL to point to discovery service.
<CredentialResolver type="File" use="signing"
            key="sp-key.pem" certificate="sp-cert.pem"/>
     You can also override entityID on /Login query string, or in RequestMap/htaccess.
<CredentialResolver type="File" use="encryption"
                 -->
            <!--<SSO entityID="https://idp.example.org/idp/shibboleth"
                 discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">-->
            <!--<SSO entityID="https://terena.org/sp"-->
                <SSO entityID="https://login.terena.org/wayf/saml2/idp/metadata.php"
                >
              SAML2key="sp-key.pem" certificate="sp-cert.pem"/>

You can use the command shib-keygen to create the signing and encryption pairs in the correct directory:

shib-keygen -h [your_sp_domain]

eg

cd /etc/shibboleth/

shib-keygen -h example.com




Next, edit the file /etc/shibboleth/attribute-map.xml


The eduTEAMS service provides a number of attributes for users who have authenticated. The attribute "eduPersonUniqueId" (see Attributes available to Relying Parties#eduTEAMSIdentifier) is the preferred attribute for identifying a remote user, and works alongside the REMOTE_USER="eduPersonUniqueId" edit you made in the shibboleth2.xml file.


The other "Attribute name=" lines refer to the remaining attributes nominally made available by the eduTEAMS service.



Add the following lines before the closing "</Attributes>" :

Code Block
languagexml
   <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.13" id="eduPersonUniqueId">
      <AttributeDecoder      </SSO>

     xsi:type="StringAttributeDecoder" caseSensitive="false"/>
   </Attribute>

   <Attribute name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/>
  <!-- SAML and local-only logout. --<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
   <Attribute name="urn:oid:2.5.4.4" id="surname"/>
       <Logout>SAML2 Local</Logout>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="email"/>
            <!-- Administrative logout. --<Attribute name="urn:oid:1.3.6.1.4.1.25178.4.1.11" id="voPesonExternalAffiliation"/>
   <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.11" id="eduPersonAssurance"/>
       <LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />

            <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
            <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>

     <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.16" id="eduPersonOrcid"/>


2. Apache configuration


You will need to configure Apache to recognize Shibboleth as an authorization "gatekeeper".


You can do this at the VirtualHost level, for example. Here we show a very basic example. Other recipes are available. See for instance the Shibboleth Wiki at https://wiki.shibboleth.net/confluence/display/SP3/Apache

<VirtuaHost example.com:443>
   ...
   ...
   <Location />
      AuthType shibboleth
      <IfVersion <
!-- Status reporting service. --> 
 2.3>
         ShibCompatWith24 On
<!--<Handler type="Status" Location="/Status" acl="127.0.0.1 ::1 62.40.105.39"/>--> 
 </IfVersion>
      ShibRequestSetting requireSession true
      ShibUseEnvironment On
      require shibboleth
   </Location>
   ...
</VirtualHost>


2a. Entitlements (authorization)

An authenticated user will have a number of "entitlements" associated with their account.

These entitlements are presented to your SP in the form of the following:

Attribute FriendlyName="eduPersonEntitlement" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"

 - within the SAML assertion.

The apache webserver populates the server environment with the variable "entitlements" and populates it accordingly.


See the example to the right.



Code Block
languagexml
 <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>

            <!-- Session diagnostic service. -->
            <!--<Handler type="Session" Location="/Session" showAttributeValues="false"/>-->
            <Handler<ns1:Attribute typeFriendlyName="Session" Location="/Session" showAttributeValues="true"/>

  eduPersonEntitlement"
          <!-- JSON feed of discovery information. -->
            <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
    Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7"
            <Handler type="AttributeChecker" Location="/AttrChecker" template="attrChecker.html" attributes="uid eppn displayName" flushSession="true"/>

<SessionInitiator type="Chaining" Location="/Login" isDefault="true" id="Login"
    entityIDNameFormat="https://login.terena.org/wayf/saml2/idp/metadata.php"
    target="https://rohu.geant.org/"
    relayState="cookie">
urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
                         <SessionInitiator type="SAML2" template="bindingTemplate.html"/>
                <SessionInitiator type="Shib1"/>
</SessionInitiator><ns1:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
        </Sessions>


        <!--
        Allows overriding of error template information/filenames. You can
        also add your own attributes with values that can be plugged into the
xsi:type="xs:string"
                templates, e.g., helpLocation below.
        -->
        <Errors supportContact="support@rohu.geant.org"
 >urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS#acc.eduteams.org</ns1:AttributeValue>
                helpLocation<ns1:AttributeValue xmlns:xs="/about.htmlhttp://www.w3.org/2001/XMLSchema"
             styleSheet="/shibboleth-sp/main.css"/>

        <!-- Example of locally maintained metadata. -->

        <MetadataProvider xsi:type="XML" validate="true" path="metadata.php"/>

xs:string"
        <!-- Example of remotely supplied batch of signed metadata. -->
        <!-- 
        <MetadataProvider type="XML" validate="true"
 >urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:gitlab#acc.eduteams.org</ns1:AttributeValue>
                 url<ns1:AttributeValue xmlns:xs="httpshttp://loginwww.terenaw3.org/wayf/module.php/saml/sp/metadata.php/default-sp"
2001/XMLSchema"
                                   backingFilePath="login.terena.org-metadata.xml" maxRefreshDelay="7200"> xsi:type="xs:string"
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
        -->    <!--<MetadataFilter type="Signature" certificate="fedsigner.pem" verifyBackup="false"/>-->
        <!-- <DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true" 
 >urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:gitlab:admin#acc.eduteams.org</ns1:AttributeValue>
                 attributeName<ns1:AttributeValue xmlns:xs="http://macedirwww.w3.org/2001/entity-categoryXMLSchema"
              attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
              attributeValue="http://refeds.org/category/hide-from-discovery" />
          </MetadataProvider>
xsi:type="xs:string"
            -->


        <!-- Example of remotely supplied "on-demand" signed metadata. -->
        <!-->urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:Developers#acc.eduteams.org</ns1:AttributeValue>
        <MetadataProvider type="MDQ" validate="true" cacheDirectory="mdq"
               baseUrl<ns1:AttributeValue xmlns:xs="http://mdqwww.federationw3.org" ignoreTransport="true">/2001/XMLSchema"
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
            <MetadataFilter type="Signature" certificate="mdqsigner.pem" />
        </MetadataProvider>xsi:type="xs:string"
        -->

        <!-- Map to extract attributes from SAML assertions. -->
        <!--<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>-->
 >urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:gitlab:audit#acc.eduteams.org</ns1:AttributeValue>
         <AttributeExtractor type="XML" validate="true" reloadChanges="true" path="attribute-map.xml"/>

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->
        <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>

        <!-- Simple file-based resolvers for separate signing/encryption keys. -->
        <CredentialResolver type="File" use="signing"
            key="sp-key.pem" certificate="sp-cert.pem"/>
        <CredentialResolver type="File" use="encryption"
            key="sp-key.pem" certificate="sp-cert.pem"/>

    </ApplicationDefaults>

    <!-- Policies that determine how to process and authenticate runtime messages. -->
    <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>

    <!-- Low-level configuration about protocols and bindings available for use. -->
    <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

</SPConfig>
Apache configuration
 </ns1:Attribute>


.... Is presented to your Apache instance as:


[entitlement] => urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS#acc.eduteams.org;urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:gitlab#acc.eduteams.org;urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:gitlab:admin#acc.eduteams.org;urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:Developers#acc.eduteams.org;urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:gitlab:audit#acc.eduteams.org


 - that is, a colon (":") separated list.


Apache also allows server and .htaccess - level directives to control access.


eg

Code Block
languagexml
<Location /login>
   AuthType shibboleth
   ShibRequestSetting requireSession 1
   ShibUseEnvironment On
   <RequireAny>
      Require shib-attr entitlement "urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:Developers#acc.eduteams.org"
                                    "urn:geant:eduteams.org:service:eduteams-acc:group:eduTEAMS:gitlab:audit#acc.eduteams.org"
   </RequireAny>
</Location>


3. Restarting the shibd and apache2 services



systemctl restart apache2 && systemctl restart shibd

You can run the command

shibd -t

to check for errors, and also look inside the log file

/var/log/shibboleth/shibd.log

in case things do not work first time (for example, file permissions on the local copy of the proxy's metadata)

4. Conclusion

You should now have a working integration of Apache and Shibboleth v3 SP services on your machine.