Difference between revisions of "Shibboleth and gCube"

Latest revision as of 14:51, 27 November 2015

Overview

Shibboleth is an implementation of SAML web browser SSO profile and SAML ECP profile.

Shibboleth is composed by two Web Services:

• Identity Provider
• Service Provider

In gCube Shibboleth is used for obtaining web browser SSO for portal based authentication, and is integrated with SOA3 in order to obtain Federated Authentication for services. For Federated Authentication is intended a type of Authentication based on a signed SAML Token indirectly referenced in a SOAP message, containing the authentication information of an user authenticated in a federated, trusted domain.

More information on SAML Federation and Shibboleth can be found in Shibboleth site and on gCube Federated Authentication in SOA3 Authentication Service page. In this section detailed information on the installation and configuration of Shibboleth in gCube infrastructure is provided.

The installation and configuration procedures described have been tested on Centos 6.4.

Shibboleth Identity Provider

Shibboleth Identity Provider (IdP) enables users to share authentication information in a SAML Federation. It is not mandatory in the infrastructure but it is required for domains which need to federate with IMarine.

Preconfiguration

Prepare your VM

Check to see what IP address the VM has been assigned by using ifconfig and looking for eth0.In your host environment, assign a unique FQDN hostname of the form host.domain.tld to your VM by editing the hosts file. Edit the hosts file generally at /etc/hosts using a text editor of your choice. Add a line following the existing mapping definitions with your chosen FQDN and the VM's IP address to create the mapping. The following is an example:

127.0.0.1 localhost
255.255.255.255 broadcasthost

x.y.z.w my.special.name 

(perhaps you need to configure iptables)

Shibboleth requires that messages passed between the IdP and the SP are in close synchronization time-wise. Please check the ntpd service is running with:

service ntpd status

If it is not, please start the ntpd service:

service ntpd start

If it is not installed, please install with:

yum install ntp 

Prepare to install Shibboleth IdP

Create a directory for IdP installation

mkdir /opt/shibboleth-idp 

Download the latest version of Shibboleth IdP to /opt/shibboleth-idp and untar/zip the file

cd /opt/shibboleth-idp
curl -O http://shibboleth.net/downloads/identity-provider/latest/shibboleth-identityprovider-2.3.8-bin.zip 
unzip shibboleth-identityprovider-2.3.8-bin.zip 

Prepare Java/Tomcat

Install java and tomcat6

yum install java-1.6.0-openjdk java-1.6.0-openjdk-devel 
yum install tomcat6 
service tomcat6 start 

Copy all libraries from download/unzip directory's "endorsed" sub-directory (/opt/shibboleth-idp/endorsed) to Tomcat's $CATALINA_HOME/endorsed directory (you may need to create this folder)

mkdir $CATALINA_HOME/endorsed 
cp /opt/shibboleth-idp/shibboleth-identityprovider-2.3.8/endorsed/*.jar $CATALINA_HOME/endorsed 

Download the file "tomcat6-dta-ssl-1.0.0.jar" and copy it to $CATALINA_HOME/lib.

curl -o $CATALINA_HOME/lib/tomcat6-dta-ssl-1.0.0.jar 
           https://build.shibboleth.net/nexus/content/repositories/releases/edu/internet2/middleware/security/tomcat6/tomcat6-dta-ssl/1.0.0/tomcat6-dta-ssl-1.0.0.jar

Configure Tomcat for endpoints on both ports 443 for SSL and 8443 in Tomcat's server.xml. Port 8443 will require client certificates on incoming connection (this is called the SOAP endpoint and the file you configure the endpoints in is called the server.xml which is found in $CATALINA_HOME/conf).

Add these endpoints next to the existing port 8080 Connector element.

Remember the password you used; you will need it when you run the installation script.

Here is a basic port 443 Configuration, the 8443 connector is documented on the wiki (see link below) and has been included below for clarity:

<Connector 
   port="443" 
   protocol="HTTP/1.1" 
   SSLEnabled="true" 
   maxThreads="150" 
   scheme="https" 
   secure="true" 
   clientAuth="false" 
   sslProtocol="TLS" 
   keystoreFile="/opt/shibboleth-idp/credentials/idp.jks" 
   keystorePass="YourSecretPassword" />

<Connector port="8443" 
   protocol="org.apache.coyote.http11.Http11Protocol"
   SSLImplementation="edu.internet2.middleware.security.
   tomcat6.DelegateToApplicationJSSEImplementation" 
   scheme="https" 
   SSLEnabled="true" 
   clientAuth="true" 
   keystoreFile="/opt/shibboleth-idp/credentials/idp.jks" 
   keystorePass="YourSecretPassword" />

The easiest way to allow Tomcat to listen on port 443 is to run it as root. Please modify /etc/sysconfig/tomcat6 by uncommenting TOMCAT_USER and changing the TOMCAT_USER to root. We'll also tell it where the endorsed directory is located.

# What user should run tomcat 
TOMCAT_USER="root" 
# Where the endorsed directory is located 
JAVA_ENDORSED_DIRS="$CATALINA_HOME/endorsed"

Production deployments should use a Tomcat "context deployment fragment" to automatically load the war file that is built by the Shibboleth installer. Upgrades and changes to the Shibboleth IdP's source that require a re-build (like the login page content) can then be done without messing with Tomcat's folder structure and caching. Create the file $CATALINA_HOME/conf/Catalina/localhost/idp.xml and place the following content in it:

<Context docBase="/opt/shibboleth-idp/war/idp.war" 
   privileged="true" 
   antiResourceLocking="false" 
   antiJARLocking="false" 
   unpackWAR="false" 
   swallowOutput="true" />

Finally, set JAVA_HOME. We'll set JAVA_HOME for all users by adding it to /etc/profile, and then export it into the current shell so you don't need to relog:

echo "export JAVA_HOME=/path/to/jre" >> /etc/profile 
export JAVA_HOME=/path/to/jre

Install Shibboleth IdP

Run the install.sh script found in the location you unzipped the shibboleth download:

cd /opt/shibboleth-idp
./install.sh

Accept default values other than hostname; enter the fully-qualified hostname for your IdP host (the external name your users' browsers will use and see). (use <MyIdPSpecialName> from above).

Enter the password for the java keystore created by the installer. This password should be the same password you configured in Tomcat's server.xml in the previous step.

Now, you will need to start tomcat.

Configure User Authentication

Configure your IdP to authenticate your users using the UsernamePassword authentication handler

Configure the LDAP section of login.config in your shibboleth install:

Switch to the directory where the config file is kept [i.e. /opt/shibboleth-idp/conf]

Edit login.config

A completely configured login.config file will look like this:

ShibUserPassAuth { 
   edu.vt.middleware.ldap.jaas.LdapLoginModule required 
      host="idp.training.incommon.org" 
      port="389" 
      base="ou=people,dc=example,dc=org" 
      bindDn="uid=IdPServiceAcct,ou=people,dc=example,dc=org" 
      bindCredential="password" 
      userField="uid={0}"; 
};

Edit handler.xml:

Uncomment the UsernamePassword login handler in handler.xml

Comment the RemoteUser login handler

Restart Tomcat.

Configure User Attributes/Attribute Resolver

Uncomment/reconfigure/add the attribute definitions in the IdP's conf/attribute-resolver.xml file.

<resolver:AttributeDefinition xsi:type="ad:Simple" id="uid" sourceAttributeID="uid"> 
        <resolver:Dependency ref="myLDAP" /> 
        <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:uid" /> 
        <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:0.9.2342.19200300.100.1.1" friendlyName="uid" /> 
    </resolver:AttributeDefinition> 
...

Uncomment and configure the resolver:DataConnector called myLDAP (towards the bottom of the file) to connect to your LDAP directory and retrieve information for the authenticated user:

<resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory" 
        ldapURL="ldap://idp.training.incommon.org:389" 
        baseDN="ou=people,dc=example,dc=org" 
        principal="uid=IdPServiceAcct,ou=people,dc=example,dc=org" 
        principalCredential="password"> 
        <dc:FilterTemplate> 
            <![CDATA[ 
                (uid=$requestContext.principalName) 
            ]]> 
        </dc:FilterTemplate> 
    </resolver:DataConnector> 

Configure Attribute Release Policies

Create a new rule to release attributes to the SP located by adding this to your attribute-filter.xml inside the main <AttributeFilterPolicyGroup> element:

<afp:AttributeFilterPolicy id="releaseToAnyone"> 
<afp:PolicyRequirementRule xsi:type="basic:ANY" /> 
     <afp:AttributeRule attributeID="uid"> 
             <afp:PermitValueRule xsi:type="basic:ANY"/> 
        </afp:AttributeRule> 
        <afp:AttributeRule attributeID="mail"> 
            <afp:PermitValueRule xsi:type="basic:ANY" /> 
        </afp:AttributeRule> 
</afp:AttributeFilterPolicy> 

Verify that your new IdP is up and running

Access the following URL from the IdP server itself by running the following command:

curl -k https://localhost/idp/status

You should see lots of information about your IdP that starts with the following:

<tt>### Operating Environment Information

    operating_system: Linux

You can also try from your web browser the old deprecated status handler at this URL (it simply responds with "ok"):

https://<MyIdPSpecialName>/idp/profile/Status

Shibboleth SP

Preconfiguration

Prepare your VM for the Session

Check to see what IP address the VM has been assigned by using ifconfig and looking for eth0.In your host environment, assign a unique FQDN hostname of the form host.domain.tld to your VM by editing the hosts file. Edit the hosts file generally at /etc/hosts using a text editor of your choice. Add a line following the existing mapping definitions with your chosen FQDN and the VM's IP address to create the mapping. The following is an example:

127.0.0.1 localhost
255.255.255.255 broadcasthost

x.y.z.w my.special.name 

(perhaps you need to configure iptables)

Shibboleth requires that messages passed between the IdP and the SP are in close synchronization time-wise. Please check the ntpd service is running with:

service ntpd status

If it is not, please start the ntpd service:

service ntpd start

If it is not installed, please install with:

yum install ntp

Installation

Download Shibboleth repo to /etc/yum.repos.d/:

curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security://shibboleth/CentOS_CentOS-6/security:shibboleth.repo 

Install the Shibboleth SP software on your web server:

yum install shibboleth 

Basic Apache configuration:

Turn on canonical name support. This is necessary because the SP uses the server name that is provided by the browser and web environment when constructing a variety of links. If the server name is variable, some string matches can fail and trust failures may occur.

Disable http:// access to sensitive resources that require Shibboleth protection.

    RewriteEngine On 
    RewriteCond %{HTTPS} off 
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} 

Add mod_ssl

yum install mod_ssl

Import the SP's certificate in the Java keystore

keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts -file sp-cert.pem -alias sp

Turn on canonical name use by Apache in /etc/httpd/conf/httpd.conf:

    UseCanonicalName On 
    ServerName <MySPSpecialName>:80 

Verify that your new Shibboleth SP is alive

First, start/restart Apache on your server to load mod_shib using:

service httpd restart

Next, start shibd using:

service shibd start

The status handler is protected by an IP address ACL, which means you need to either perform this task from the web server itself or edit the ACL for the /Statushandler in /etc/shibboleth/shibboleth2.xml. Keep in mind that the list is space delimited for example:

<Handler type="Status" Location="/Status" acl="127.0.0.1 10.0.0.2 10.0.0.3"/>

Access the URL https://127.0.0.1/Shibboleth.sso/Status from inside your VM: 
curl -k https://127.0.0.1/Shibboleth.sso/Status

Configure Shibboleth SP

Edit /etc/shibboleth/shibboleth2.xml file for configure the SP to support CASShib. Each service needs to have its own protected Shibboleth address for CAS validation. For mapping URLs with services we add these rows in the shibboleth configuration file.

Under the root tag SPConfig you need to add:

<RequestMapper type="Native"> 
    <RequestMap applicationId="default" exportAssertion="true"> 
          <Host name="MySPSpecialName" port="443" scheme="https"> 
                <PathRegex regex="casshib/shib/app2" applicationId="app2"                 authType="shibboleth" requireSession="true"/> 
            </Host> 
      </RequestMap> 
</RequestMapper> 

The attribute exportAssertion="true" is needed to enable Web Service Federation inside gCube infrastructure. After this, you need to configure the section with fake service. This means that if the request doesn't match the regular expressions return an error page. For configuring the registrated service we add these lines under the tag ApplicationDefaults:

<ApplicationOverride id="app2" 
                     entityID="https://MySPSpecialName/casshib/app2" 
                     homeURL="https://MySPSpecialName/app2/" 
                     REMOTE_USER="shibattr-mail"> 
        <Sessions lifetime="28800" timeout="3600" checkAddress="false" 
          handlerURL="/casshib/shib/app2/Shibboleth.sso" handlerSSL="true" 
            exportLocation="/casshib/shib/app2/Shibboleth.sso/GetAssertion" 
             exportACL="MySPSpecialAddress" 
            idpHistory="false" idpHistoryDays="7" 
            cookieProps="; path=/casshib/shib/app2"> 
      </Sessions> 
</ApplicationOverride> 

Then, it is necessary to tell the Service Provider where the idp is located. In general this is done by the Where are you From Service or Discovery Service, whose endpoint is configured in the following way:

<ApplicationDefaults>
 <Sessions>
   <SSO discoveryProtocol="SAMLDS" discoveryURL="https://gcube-internal-sp.res.eng.it/shibboleth-ds/index.html">
      SAML2 SAML1
   </SSO>
 </Sessions>
<ApplicationDefaults>

If we wanted to test a configuration with a single identity provider, the previous element should be replaced by the following:

<SSO entityID="https://gcube-internal-idp.res.eng.it/idp/shibboleth" discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
   SAML2 SAML1
</SSO>

Edit /etc/shibboleth/attribute-map.xml file to define the attributes used by Shibboleth SP:

<Attribute name="urn:mace:dir:attribute-def:uid" id="shibattr-uid"/> 
<Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="shibattr-uid"/> 
<Attribute name="urn:mace:dir:attribute-def:mail" id="shibattr-mail"/> 
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="shibattr-mail"/> 

Prepare Java/Tomcat

Install java and tomcat6

yum install java-1.6.0-openjdk java-1.6.0-openjdk-devel 
yum install tomcat6 

Configure APR connector in Tomcat by editing the server.xml file:

<Connector port="8009" protocol="AJP/1.3" enableLookups="false" address="127.0.0.1" tomcatAuthentication="false"/> 

Start Tomcat server:

service tomcat6 start 

Connect Tomcat with Apache Web Server

yum install httpd-devel

    cd /tmp
    download tomcat-connector source from mirror (tomcat website) 
    untar it

    cd /tmp/tomcat-connectors-current.version-src /native
    ./buildconfig.sh
    yum install gcc* 
    ./configure --with-apxs=/usr/sbin/apxs 
    make 
    cd ./apache-2.0 
    cp mod_jk.so /usr/lib64/httpd/modules/

touch /etc/httpd/workers.properties
vi /etc/httpd/workers.properties

create a workers.properties file in your /etc/httpd/ dir, with at least:

workers.tomcat_home=/srv/tomcat7 
workers.java_home=/usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0.x86_64/jre 

worker.list=worker1 
worker.worker1.type=ajp13 
worker.worker1.host=localhost 
worker.worker1.port=8009 

create a httpd-jk-init.conf file:

LoadModule jk_module modules/mod_jk.so 
<IfModule jk_module> 
   JkWorkersFile conf/workers.properties 
   JkShmFile logs/mod_jk.shm 
   JkLogFile logs/mod_jk.log 
   JkLogLevel info 
   JkLogStampFormat "[%a %b %d %H:%M:%S %Y]" 
</IfModule> 

create a httpd-jk-mount.conf file:

<IfModule jk_module> 
   JkMount /casshib/* worker1 
   JkUnMount /casshib/shib/*/Shibboleth.sso worker1 
   JkUnMount /casshib/shib/*/Shibboleth.sso/* worker1 
</IfModule> 

Protect the login and Shibboleth.sso URLs

In your /etc/httpd/conf/httpd.conf the <LocationMatch> element activates mod_shib to protect a resource:

<LocationMatch "/casshib/shib/[^/]*/(login|Shibboleth.sso(/[^/]*)?)">

            AuthType shibboleth 
           ShibRequireSession On 
          ShibUseHeaders On 
         require valid-user 
       </LocationMatch> 

Restart shibd

CASShib

Installation (on the same machine of Shibboleth Service Provider)

cd /tmp

wget http://casshib.googlecode.com/files/casshib-server-3.4.2a-release.tar.gz

    tar xzf casshib-server-3.4.2a-release.tar.gz
    cd  casshib-server-3.4.2a/modules/
    cp casshib-server-webapp-3.4.2a.war $CATALINA_HOME/webapps/casshib.war

Configuration

You need to modify the CASShib Service Registrations file, i.e. $CATALINA_HOME/webapps/casshib/WEB-INF/classes /casshib-service-registrations.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<casShibServiceRegistrations> 
  <service id="https://<MygCubePortalSpecialName>/c/portal/login" 
           appname="app2" 
           passcode="12345" /> 
</casShibServiceRegistrations> 

GCube Portal

Installation of the Federated Portal

GCube Portal installation procedure is described here. In order to enable SAML federation the Portal must run in [D4Science Portal HTTPS x509 Certificate Authentication|HTTPS mode] and CAS authentication must be configured by using Liferay CAS Feature together with CASShib.

In order to configure CAS Authentication select the page

 Manage/Control Panel/Settings/Authentication/CAS

and configure Liferay to use CASShib in the following way:

Configure the Federation

The last operation to be performed is the configuration of SAML Federation by associating (at least) an Identity Provider and a Service Provider. In particular IdP and SP must trust each other by exchanging their metadata. This configuration process is currently manual and is described in the next subsection; then it will be described the configuration of the Discovery (or Where are You From) Service that redirects the user to his/her home domain.

Metadata

Download and store SP Metadata

curl -o /opt/shibboleth-idp/metadata/sp-metadata.xml https://sp.d4science.org/Shibboleth.sso/Metadata (on the IdP)

Download and store App2 Metadata

curl -o /opt/shibboleth-idp/metadata/app2-metadata.xml https://sp.d4science.org/casshib/shib/app2/Shibboleth.sso/Metadata (on the IdP)

Open the file relying-party.xml of Shibboleth IdP and change the Metadata Provider entry to:

<metadata:MetadataProvider id="ShibbolethMetadata"  xsi:type="metadata:ChainingMetadataProvider"> 
            <metadata:MetadataProvider id="FileIDPMD" xsi:type="metadata:FilesystemMetadataProvider"
                           metadataFile="/opt/shibboleth-idp/metadata/idp-metadata.xml" maxRefreshDelay="P1D" /> 

            <metadata:MetadataProvider id="FileSPMD" xsi:type="metadata:FilesystemMetadataProvider" 
                           metadataFile="/opt/shibboleth-idp/metadata/sp-metadata.xml" maxRefreshDelay="P1D" /> 

            <metadata:MetadataProvider id="FileApp2MD" xsi:type="metadata:FilesystemMetadataProvider" 
                           metadataFile="/opt/shibboleth-idp/metadata/app2-metadata.xml" maxRefreshDelay="P1D" /> 
           </metadata:MetadataProvider>

Download and store IdP Metadata

curl -o /opt/shibboleth/idp-metadata.xml https://<MyIdPSpecialName>/idp/profile/Metadata/SAML (on the SP)

Open the file shibboleth2.xml of Shibboleth SP and change the MetadataProvider entry to:

<MetadataProvider type="XML" file="/opt/shibboleth/idp-metadata.xml"/> 

Discovery Service

A Discovery or Where are you from Service should be used to help the user to choice his/her home domain. Shibboleth provides a Discovery Service, but any other similar service can be used. A pre configured and customized version of Shibboleth DS is provided in WP5 workspace of IMarine gateway.

Please, refer to Embedded Discovery Service installation page for a detailed guide. In general, Shibboleth Embedded DS is composed by some jsp pages and requires an http server (such as Apache HTTP Server).

After the installation of the rpm (or via yum), the file /etc/shibboleth-ds/idpselect_config.jsp contains the configurations needed for loading the trusted IdPs. In particular the field:

this.dataSource

contains the relative or absolute path of the url of the service provided by the Service Provider, where the list of trusted IdP is provided. The path is relative when the SP and the DS are on the same machine (suggested deployment):

'/casshib/shib/app2/Shibboleth.sso/DiscoFeed'

absolute, otherwise.

Authorization of Federated Portals

Each federated portal using CasShib must be enabled by editing the following file: /usr/share/tomcat6/webapps/casshib/WEB-INF/classes/casshib-service-registrations.xml

References

Shibboleth Identity Provider

Shibboleth Service Provider

CASShib Official Wiki

CASShib Installation

Liferay Official Documentation