Shibboleth 2 IdP Setup Guide

This document is a guide to setting up a Shibboleth 2.0 Identity Provider (IdP) on CentOS v5 using LDAP for authentication against Windows Active Directory. The information provided is based on my experience in setting up a test Shibboleth implementation, and is not intended to be an exhaustive guide to installing and configuring Shibboleth. The Shibboleth installation was successfully tested against the TestShib server provider. This does not guarantee that the IdP will work in a production environment. To access learning resources, the identity provider institution must join the UK Federation (http://www.ukfederation.org.uk).

Document Conventions
Commands are displayed on a light green background, as shown in the examples below. # ls -l # command executed as root user $ ls -l # command executed as non-root user # cp /etc/profile \ > /tmp/profile # multi-line command # wget -P /tmp http://shibboleth.internet2.edu/downloads/shibboleth/idp/latest/shibbolethidentityprovider-2.1.2-bin.tar.gz # wrapped single-line command The first character in a command is the command prompt and should not be typed in. A hash symbol (#) anywhere other than the first character indicates a comment. File contents are displayed on a light blue background, as shown in the example below: APACHE_SERVER_FLAGS="-D SSL"

Network Configuration
The Shibboleth IdP server must be accessible by name from the Internet, and the domain name against which it authenticates must be a valid Internet domain name. The recommendation is to place the IdP server in a demilitarized zone (DMZ) and open the appropriate ports on the internal and external firewalls. See Table 1 for port settings.
Table 1

Firewall Port Map To Comment Internal 389 Internal 88 External 80 External 443 N/A N/A 80 443 LDAP queries from IdP to domain controller Kerberos connection to domain controller. HTTP HTTPS Shibboleth single sign-on Shibboleth attributes

External 8442 8442 External 8443 8443

Note: Only ports 389, 80 and 443 were opened for successful TestShib authentication.

Installation
All commands are executed as the root user, unless otherwise specified. 1. Install CentOS with: Base packages Text editors Command-line Internet Software required for Shibboleth will be downloaded and installed after the operating system installation. X-Windows and a windows manager are not required. 2. Open the firewall ports listed in Table 1 # iptables -A INPUT # iptables -A INPUT # iptables -A INPUT # iptables -A INPUT 3. -p tcp --dport 80 -j ACCEPT -p tcp --dport 443 -j ACCEPT -p tcp --dport 8442 -j ACCEPT -p tcp --dport 8443 -j ACCEPT

Shibboleth requires the service and identity providers clocks are in sync. On a physical server, install and enable the time service and edit /etc/ntp.conf to synchronize with the JANET time servers listed at http://www.ja.net/services/ntp. # yum -y install ntp # vi /etc/ntp.conf # add JANET time servers (line 17) # ntpdate ntp0.ja.net # service ntpd start # chkconfig ntpd on On a virtual server follow the instructions for synchronizing the clock with the host server for VMWare or Windows Virtual Server.

4.

Install OpenLDAP client. Not required for Shibboleth, used for testing LDAP queries against Active Directory server # yum -y install openldap-clients

5.

Download and install the Java Runtime Environment version 6.

# wget -O /tmp/jre.rpm.bin http://javadl.sun.com/webapps/download/AutoDL?BundleId=27972

# chmod +x /tmp/jre.rpm.bin # /tmp/ jre.rpm.bin

6.

Set the Java environment variables # touch /etc/profile.d/idp.sh # chmod +x /etc/profile.d/idp.sh # echo export JAVA_HOME=/usr/java/default >> /etc/profile.d/idp.sh # echo export JAVA_OPTS=\-server\ >> /etc/profile.d/idp.sh # source /etc/profile

7.

Install Apache HTTP server and the SSL module # yum -y install httpd mod_ssl # chkconfig httpd on

8.

Download and install Tomcat 6 # wget -P /tmp http://apache.mirror.infiniteconflict.com/tomcat/tomcat-6/v6.0.18/bin/apachetomcat-6.0.18.tar.gz # this command is on one line # tar xvzf /tmp/apache-tomcat-6.0.18.tar.gz -C /usr/local # ln -s /usr/local/apache-tomcat-6.0.18 /usr/local/apache-tomcat

9.

Add the CATALINA_HOME variable to the environment. # echo export CATALINA_HOME=/usr/local/apache-tomcat >> /etc/profile.d/idp.sh # source /etc/profile

10.

Create the tomcat user account # useradd tomcat # groupadd tomcat

11.

Change the ownership of the Tomcat directory structure to tomcat chown -R tomcat:tomcat /usr/local/apache-tomcat

12.

Edit $CATALINA_HOME/conf/tomcat-users.xml and add an admin user, for example: <tomcat-users> <user username=admin password=Pa$2w0rd roles=admin,manager /> </tomcat-users>

13.

Download and install Shibboleth 2.1.2 identity provider by executing install.sh. # wget -P /tmp http://shibboleth.internet2.edu/downloads/shibboleth/idp/latest/shibbolethidentityprovider-2.1.2-bin.tar.gz # one line # tar xvzf /tmp/shibboleth-identityprovider-2.1.2-bin.tar.gz -C /tmp # cd /tmp/shibboleth-identityprovider-2.1.2 # sh install.sh

Provide the following information in response to the installer prompts: The folder in which to install the IdP (IDP_HOME). The Internet-visible DNS name of the IdP server. A password for the self-signed certificate The self-signed certificate is stored in $IDP_HOME/credentials. Before going live, this should be replaced with an X.509 digital certificate recognised by the federation. 14. Make the tomcat user the owner of IDP_HOME and its contents. # chown -R tomcat:tomcat /usr/local/shibboleth-idp 15. Edit $CATALINA_HOME/conf/catalina.properties /lib/endorsed/*.jar to the common.loader entry. and append /usr/local/shibboleth-idp

16.

Copy $IDP_HOME /war/idp.war to $ CATALINA_HOME/webapps as the tomcat user. # su tomcat $ cp /usr/local/idp/war/idp.war $CATALINA_HOME/webapps $ exit

Configuration
Configuration of the Shibboleth IdP requires: Enabling SSL on Apache. Configuring Apache to accept connections on behalf of Tomcat. Enabling LDAP authentication for the IdP. Defining source of user attributes and mapping between attribute names. Define which attributes to release to service provider. The following sections describe what files are to be edited to configure the IdP. The paths used reflect the test installation and should be changed to reflect your configuration.

Enable SSL on Apache

1. Edit /etc/httpd/conf.d/ssl.conf and configure a virtual host listening on port 443 by replacing the existing virtual host with the following:
<VirtualHost _default_:443> SSLEngine on SSLProtocol all -SSLv2 SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM:+LOW SSLOptions +StdEnvvars ################## replace with signed certificate SSLCertificateFile "/usr/local/shibboleth-idp/credentials/idp.crt" SSLCertificateKeyFile "/usr/local/shibboleth-idp/credentials/idp.key" # may need to include an entry for SSLCertificateChainFile ################################################################### ErrorLog logs/ssl_443_error_log" TransferLog logs/ssl_443_access_log" LogLevel warn CustomLog logs/ssl_443_request_log" \ "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" </VirtualHost>

2.

Create

virtual

host

that

listens

on

port

8443

by

adding

the

following

to

/etc/httpd/conf.d/ssl.conf:
<VirtualHost _default_:8443> SSLEngine on SSLProtocol all -SSLv2 SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM:+LOW SSLOptions +StdEnvvars +ExportCertData SSLVerifyClient optional_no_ca SSLVerifyDepth 10

################## replace with signed certificate SSLCertificateFile "/usr/local/shibboleth-idp/credentials/idp.crt" SSLCertificateKeyFile "/usr/local/shibboleth-idp/credentials/idp.key" # may need to include an entry for SSLCertificateChainFile ################################################################### ErrorLog logs/ssl_8443_error_log" TransferLog logs/ssl_8443_access_log" LogLevel warn CustomLog logs/ssl_8443_request_log" \ "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" </VirtualHost>

Configure Apache to Accept Connections on Behalf of Tomcat

1. Append the following to /etc/httpd/conf.d/proxy-ajp.conf:
ProxyPass /idp/ ajp://localhost:8009/idp/

Configure Tomcat
1. Configure a connector on port 8009 in $CATALINA_HOME/conf/server.xml as follows:
<Connector port="8009" request.tomcatauthentication="false" address="127.0.0.1" enableLookups="false" protocol="AJP/1.3" redirectPort="8443" />

Testing
1. Restart Apache server
# service httpd restart

2.

Restart Tomcat
# su tomcat -c $CATALINA_HOME/bin/shutdown.sh # su tomcat -c $CATALINA_HOME/bin/startup.sh

3.

Browse to home page

# curl http://localhost

HTML content of default home page is printed to the terminal window. 4. Browse to home page over SSL
# curl -k https://localhost

HTML content of default home page is printed to the terminal window. 5. Browse to IdP status page
# curl http://localhost/idp/profile/Status

ok is printed to the terminal window 6. Review $CATALINA_HOME/logs/catalina.out and $IDP_HOME/logs/idp-process.log files for errors.

Enable LDAP Authentication for IdP

1. Edit $IDP_HOME/conf/login.config and uncomment the LdapLoginModule section. See Table 2 for the parameters to set that will allow IdP to login to and verify credentials against Active Directory.
Table 2

Parameter host base port ssl userField subtreeSearch serviceUser

Description Space separated list of full DNS names of domain controllers Path of directory from which to begin searching LDAP port (must be open on internal firewall) true if SSL connection to domain controllers, false otherwise Name of field containing user id true to search entire subtree of base, false to search only immediate children Account that IdP uses to connect to Active Directory

Example rsc-dns3.rscwmsystems.org.uk dc=rscwmsystems,dc=org,dc=uk 389

samAccountName

cn=Idp Login,ou=Shibboleth, dc=rscwmsystems,dc=org,dc=uk

serviceCredential Password for serviceUser account

2.

Edit $IDP_HOME/conf/handler.xml, activate the UsernamePassword login handler and remove the RemoteUser login handler, as follows:
<!-- ------------------------------------------------ COMMENTED OUT ----------------------<LoginHandler xsi:type="RemoteUser"> <AuthenticationMethod> urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified </AuthenticationMethod> </LoginHandler> ------------------------------------------------------------------------------------------------------------<LoginHandler xsi:type="UsernamePassword"

-->

jaasConfigurationLocation="file:///usr/local/shibboleth-idp/conf/login.config"> <AuthenticationMethod> urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport </AuthenticationMethod> </LoginHandler>

Attribute Resolution Configuration

The IdP can retrieve attributes from either LDAP or a relational database; generate attributes based on other attributes; or define them statically. The $IDP_HOME/conf/attribute-resolver.xml file defines data connectors (resolver:DataConnector) for connecting to the attribute sources, and attribute definitions (resolver:AttributeDefinition) that define the attribute type (xsi:type) and how it maps to the source attribute (sourceAttributeID). Attribute definitions are associated with a data connector via the ref parameter of the resolver:Dependency child node. See https://spaces.internet2.edu/display/SHIB2/IdPAddAttribute for details. The service provider will specify the attributes that it requires. The UK Federation defines the following core attributes: eduPersonScopedAffiliation: users role in the organisation, e.g. [email protected]. eduPersonTargetedID: service provider-specific user id eduPersonPrincipalName: user id defined by identity provider eduPersonEntitlement: extensible list of URIs for extra properties Restart the IdP web application after modifying the attribute-resolver file. Examples
<resolver:DataConnector id="conLDAP" xsi:type="LDAPDirectory" xmlns="urn:mace:shibboleth:2.0:resolver:dc" ldapURL="ldap://rsc-dns3.rscwmsystems.org.uk:389" baseDN="ou=Shibboleth,dc=rscwmsystems,dc=org,dc=uk" principal="[email protected]" principalCredential="Pa$2w0rd"> <FilterTemplate> <![CDATA[ (samAccountName=$requestContext.principalName) ]]> </FilterTemplate> </resolver:DataConnector>

Figure 1: LDAP Data Connector

10

<resolver:DataConnector id="conStatic" xsi:type="Static" xmlns="urn:mace:shibboleth:2.0:resolver:dc"> <Attribute id="eduPersonAffiliation"> <Value>member</Value> </Attribute> <Attribute id="eduPersonEntitlement"> <Value>urn:example.org:entitlement:entitlement1</Value>

<Value>urn:mace:dir:entitlement:common-lib-terms</Value>
</Attribute> </resolver:DataConnector>

Figure 2: Static Data Connector

<resolver:DataConnector xsi:type="ComputedId" xmlns="urn:mace:shibboleth:2.0:resolver:dc" id="conComputed" generatedAttributeID="attComputed" sourceAttributeID="objectGUID" salt="your random string here"> <resolver:Dependency ref="conLDAP" />

</resolver:DataConnector>
Figure 3: Computed Data Connector

<resolver:AttributeDefinition id="email" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="mail"> <resolver:Dependency ref="conLDAP" /> <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:mace:dir:attribute-def:mail" /> <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" /> </resolver:AttributeDefinition>

Figure 4: LDAP Attribute

11

<resolver:AttributeDefinition id="eduPersonAffiliation" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="eduPersonAffiliation"> <resolver:Dependency ref="conStatic" /> <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:mace:dir:attribute-def:eduPersonAffiliation" /> <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" friendlyName="eduPersonAffiliation" /> </resolver:AttributeDefinition>

Figure 6: Static Attribute

<resolver:AttributeDefinition id="eduPersonTargetedID" xsi:type="SAML2NameID" xmlns="urn:mace:shibboleth:2.0:resolver:ad" nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" sourceAttributeID="attComputed"> <resolver:Dependency ref="conComputed" /> <resolver:AttributeEncoder xsi:type="SAML1XMLObject" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" /> <resolver:AttributeEncoder xsi:type="SAML2XMLObject" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" friendlyName="eduPersonTargetedID" /> </resolver:AttributeDefinition>

Figure 5: Computed Attribute

12

<resolver:AttributeDefinition id="eduPersonAffiliation" xsi:type="Script" xmlns="urn:mace:shibboleth:2.0:resolver:ad" > <resolver:Dependency ref="conLDAP" /> <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:mace:dir:attribute-def:eduPersonAffiliation"/> <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" friendlyName="eduPersonAffiliation"/> <Script> <![CDATA[ importPackage(Packages.edu.internet2.middleware.shibboleth.common.attribute.provider); eduPersonAffiliation = new BasicAttribute("eduPersonAffiliation"); dn = distinguishedName.getValues().get(0).toLowerCase(); if (dn.contains("ou=staff")) { eduPersonAffiliation.getValues().add("staff"); } else if (dn.contains("ou=student")) { eduPersonAffiliation.getValues().add("student"); } else { eduPersonAffiliation.getValues().add("member"); } ]]> </Script> </resolver:AttributeDefinition>

Figure 7: Scripted Attribute

13

<resolver:AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="Scoped" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="eduPersonAffiliation" scope="rscwmsystems.org.uk"> <resolver:Dependency ref="eduPersonAffiliation" /> <resolver:AttributeEncoder xsi:type="SAML1ScopedString" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" /> <resolver:AttributeEncoder xsi:type="SAML2ScopedString" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" friendlyName="eduPersonScopedAffiliation" /> </resolver:AttributeDefinition>

Figure 8: Attribute Derived From Another Attribute

Attribute Release Policy Definition

The $IDP_HOME/conf/attribute-filter.xml file defines which attributes to release to specific service providers. The file contains a set of attribute filter policy (AttributeFilterPolicy) nodes that define rules (PolicyRequirementRule) for allowing a service provider access to the attributes, and attribute filters that define which attributes are released. Restart the IdP web application after modifying the attribute-filter file.

14

Examples

<AttributeFilterPolicy> <PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://sp1.example.org" /> <AttributeRule attributeID="eduPersonScopedAffiliation"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="eduPersonAffiliation"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="eduPersonEntitlement"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="eduPersonTargetedID"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> </AttributeFilterPolicy>

Figure 9: Release Policy For Specific Service Provider

<AttributeFilterPolicy> <PolicyRequirementRule xsi:type="saml:AttributeRequesterInEntityGroup" groupID="http://ukfederation.org.uk" /> <AttributeRule attributeID="eduPersonAffiliation"> <PermitValueRule xsi:type="basic:OR"> <basic:Rule xsi:type="basic:AttributeValueString" <basic:Rule xsi:type="basic:AttributeValueString" <basic:Rule xsi:type="basic:AttributeValueString" <basic:Rule xsi:type="basic:AttributeValueString" </PermitValueRule> </AttributeRule> </AttributeFilterPolicy>

value="faculty" ignoreCase="true" /> value="student" ignoreCase="true" /> value="staff" ignoreCase="true" /> value="employee" ignoreCase="true" />

Figure 10: Release Policy For Specific Service Provider Group

15

Testing
The Shibboleth IdP 2 installation can be tested against the TestShib service as follows: 1. 2. Register with TestShib (http://www.testshib.org/testshib-two/join.jsp) Modify $IDP_HOME/conf/relying-party.xml as described on http://www.testshib.org/testshibtwo/configure.jsp. Add an attribute filter policy to $IDP_HOME/conf/attribute-filter.xml to release the eduPersonScopedAffiliation and eduPersonTargetedID attributes to https://sp.testshib.org /shibboleth-sp (see examples in previous section). Restart the IdP web application. Create a test Active Directory account. Use ldapsearch to verify that the principal account specified in login.config and attributeresolver.xml can connect to Active Directory. For example:
# > > > > ldapsearch -x -L \ -b "ou=Shibboleth,dc=rscwmsystems,dc=org,dc=uk" \ -H "ldap://rsc-dns3.rscwmsystems.org.uk:389" \ -D "cn=Idp Login,ou=Shibboleth,dc=rscwmsystems,dc=org,dc=uk" -W \ "samAccountName=*"

3.

4. 5. 6.

7.

Browse to https://sp.testshib.org, specify the DNS name of the IdP server and log in with the test account.

If successful, a result similar to the following will be returned:

Shibboleth-protected TestShib Content

This page is protected by the TestShib Service Provider. If you're reading this, your IdP successfully provided authentication information. If you have data about you and an assertion below, then your IdP also released attribute and authorization information. Cool! Here are some pieces of information I can tell about you using the information Shibboleth gives me: Keep-Alive is: 300 Shib-Session-ID is: _5e3c154ea5ca0c9b93bcc89345e95ad0 Shib-Identity-Provider is: https://dns1.rscwmsystems.org.uk/idp/shibboleth Shib-Authentication-Instant is: 2009-03-26T11:17:39.512Z Shib-AuthnContext-Decl is: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport affiliation is: [email protected] unscoped-affiliation is: member entitlement is: urn:example.org:entitlement:entitlement1;urn:mace:dir:entitlement:common-lib-terms persistent-id is: https://dns1.rscwmsystems.org.uk/idp/shibboleth!https://sp.testshib.org/shibbolethsp!ajV02X7Yv9s2WKk9L4WB2Mz6/5k= Shib-Application-ID is: default
16

Useful Links
UK Federation joining instructions. UK Federation technical recommendations for participants (pdf). login.config documentation. attribute-resolver.xml documentation. attribute-filter.xml documentation. relying-party.xml documentation. Nottingham Trent University Windows IdP Installation wiki. EduGate Shibboleth 2.1 installation lab exercise Active Directory schema attributes.

17