Skip navigation.
Home
codeBrane
Home

Guanxi Localhost Tutorial

Introduction

This tutorial takes you through all the steps required to setup a mini federation on your localhost machine, using Guanxi version 2. You'll access a protected page, using SAML2 Web Browser SSO or Shibboleth, that displays attributes as request headers.

Guanxi versions for this tutorial

This tutorial applies to these versions of the Guanxi modules:

  • IdP v2.2.0 and greater
  • Engine v2.2.0 and greater
  • Guard v2.2.0 and greater
  • Provider v1.0.0 and greater
  • WAYF v1.2.8 and greater
  • Next one

What do I need?

To keep things simple, we'll be using Tomcat. This lets us concentrate on Guanxi. So you'll need the following before continuing with this tutorial:

Tomcat. We'll be using 6.0.20, although you're free to use whatever version you prefer, which you can download from http://tomcat.apache.org

  • Guanxi IdP
  • Guanxi SP::Guard
  • Guanxi SP::Engine
  • Guanxi Provider
  • Guanxi WAYF

details of how to obtain the Guanxi modules will be discussed later in the tutorial.
You will also need a browser that can accept localhost cookies. Internet Explorer, Safari, Opera or Lynx, as far as I can ascertain do not reliably support localhost cookies. Firefox does.

Definitions

TOMCAT_HOME

This is where you've installed Tomcat. Please refer to the current installation instructions for Tomcat. Normally it's just a case of unpacking the Tomcat distrubtion and putting it somewhere. For this tutorial, my Tomcat lives in:

/Users/alistair/apps/apache-tomcat-6.0.20-localhost

GUANXI_HOME

This is where you will install the Guanxi webapps. For this tutorial, I normally install them in the directory:

/Users/alistair/web/localhost

SRC_HOME

This is where you checkout the Guanxi source from CVS. I normally use:

/Users/alistair/dev/Guanxi

Assumptions

We're going to deploy the following web applications:

  • guanxi_idp
  • guanxi_wayf
  • protectedapp
  • samlengine

The tutorial is written for Unix so there are Unix commands such as mv, gunzip and tar. If you are using Windows you can use the Windows equivalents. We are going to run Tomcat on port 8080 (HTTP) and 8443 (HTTPS). If you wish to use different ports, just change the URLs accordingly.

What's going to happen?

What we're going to do is install Guanxi in localhost configuration to allow you to see how everything fits together. To let you see how much configuration is required and how much is configured automatically.
If you've read the section titled "Assumptions" you'll see there a number of directories in the Guanxi installation. What's going to happen is this:

What can I expect at the end of the tutorial?

At the end of this tutorial you will have a localhost Guanxi system installed in Tomcat. You will run everything over HTTPS and your IdP's Attribute Authority (AA) will be set up to use client authentication. You will be able to access a page protected by a Guanxi Guard and inspect the attributes that the IdP is releasing.

Who needs what?

What does the IdP need?

  • Properly configured idp.xml. This is created when the container starts. You will also modify this.
  • Keystore to hold it's signing certificate. This is created when the container starts.
  • RFC format certificate to be sent to federation managers and SPs. This is created when the container starts.
  • Config file to tell it where to authenticate users. This is preconfigured for the FlatFlatAuthenticator.
  • Config file to tell it where to get attributes from. This is preconfigured for the FlatFlatAttributor.
  • A set of Attribute Release Policy (ARP) files. You will not need to modify these.
  • A set of Attribute Mapping Policy (AMP) files. You will not need to modify these.

What does the WAYF need?

  • A config file that it uses to display a list of IdPs. You will modify this.

What does the Guard need?

  • A config file to tell it what domain it's working in and where it's Engine is. You will modify this.
  • A keystore which holds its SSL certificate. This is created automatically by the Engine and stored at the Engine, when the Guard is registered with the Engine.

What does the Engine need?

  • Config file telling it where it can find it's various bits 'n bobs. You will not need to modify this.
  • Keystore to hold it's SSL certificate for communicating with Guards via HTTPS. This is created when the container starts.
  • Truststore to hold Guard certificates when using HTTPS. This is created when the container starts.
  • A WAYF config file. This tells the Engine what WAYF location to give to various Guards. You will modify this.
  • Metadata for each Guard that the Engine looks after. All Guard metadata is created automatically when you register a Guard using the special web page.
  • Metadata for each IdP the Engine will communicate with. All IdP metadata is created automatically when you register an IdP using the special web page.

Tomcat configuration

Setting up Tomcat for the Guanxi webapps

Open the file TOMCAT_HOME/conf/server.xml and locate the section:

<Host name="localhost" appBase="webapps"
       unpackWARs="true" autoDeploy="true"
       xmlValidation="false" xmlNamespaceAware="false">

change the "appBase" to:

appBase="GUANXI_HOME"

replace GUANXI_HOME with a suitable path to a directory where you will store the Guanxi webapps. I normally use:

appBase="/Users/alistair/web/localhost"

go to the end of the "Host" section and just before the last

</Host>

add the following:

 <Context path="/guanxi_idp" docBase="guanxi_idp" debug="0" reloadable="true">
    <Logger className="org.apache.catalina.logger.FileLogger" prefix="guanxi_idp_" suffix=".txt" timestamp="true"/>
  </Context>
  <Context path="/guanxi_wayf" docBase="guanxi_wayf" debug="0" reloadable="true">
    <Logger className="org.apache.catalina.logger.FileLogger" prefix="guanxi_wayf_" suffix=".txt" timestamp="true"/>
  </Context>
  <Context path="/samlengine" docBase="samlengine" debug="0" reloadable="true">
    <Logger className="org.apache.catalina.logger.FileLogger" prefix="samlengine_" suffix=".txt" timestamp="true"/>
  </Context>
  <Context path="/protectedapp" docBase="protectedapp" debug="0" reloadable="true">
    <Logger className="org.apache.catalina.logger.FileLogger" prefix="protectedapp_" suffix=".txt" timestamp="true"/>
  </Context>

Setting up SSL support in Tomcat

To enable SSL support in Tomcat, you'll need to create a keystore, containing a public/private keypair which Tomcat will use to handle SSL connections on the SSL port. I normally store this keystore in a security directory in my Tomcat. So let's start by creating a new directory under TOMCAT_HOME:

cd TOMCAT_HOME
mkdir security
cd security

next, create a keystore:

keytool -genkey -alias tomcat -keyalg RSA -keystore ./tomcat.jks

enter a keystore password (and remember it as we'll need it later).

What is your first and last name?
  [Unknown]:  sgarbh.smo.uhi.ac.uk

as you can see, you should set the "first and last name" to the domain name of your server, on which tomcat will serve. My server is called sgarbh.smo.uhi.ac.uk but your one will have a different domain name. Use that instead. Whatever you enter for "first and last name" will be used by the browser to identify the server. What we're really doing is creating a self-signed certificate, so the browser will display a warning dialogue when you access HTTPS on the server but don't worry about that. This is just for setting up the localhost environment. For a production system, you would get a real certificate from a Certificate Authority, such as Thawte or Verisign.
Here is my configuration for the certificate. Just change it to suit your environment. I just kept the key password the same as the keystore password to keep things simple:

What is your first and last name?
  [Unknown]:  sgarbh.smo.uhi.ac.uk 
What is the name of your organizational unit?
  [Unknown]:  WWW
What is the name of your organization?
  [Unknown]:  UHI
What is the name of your City or Locality?
  [Unknown]:  Skye
What is the name of your State or Province?
  [Unknown]:  Skye
What is the two-letter country code for this unit?
  [Unknown]:  GB
Is CN=sgarbh.smo.uhi.ac.uk, OU=WWW, O=UHI, L=Skye, ST=Skye, C=GB correct?
  [no]:  yes
 
Enter key password for <tomcat>
	(RETURN if same as keystore password):

You should now have a keystore:

ls -l TOMCAT_HOME/security
-rw-r--r--  1 alistair  staff  1348  3 Jun 09:17 tomcat.jks

The next step is to tell Tomcat on which ports it will be serving and how to enable SSL on the HTTPS port. Open the file:

TOMCAT_HOME/conf/server.xml

there should already be a section ready to use:

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
    <Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true" />

make sure it's ready to use (not commented out) and then find this section:

 <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
    <!--
    <Connector port="8443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />
    -->

uncomment the section and add the following extra fields, so the section ends up looking like this:

 <Connector port="8443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="want"
               keystoreFile="TOMCAT_HOME/security/tomcat.jks"
               keystorePass="KEYSTORE_PASSWORD"
               truststoreFile="TOMCAT_HOME/security/tomcat.jks"
               truststorePass="KEYSTORE_PASSWORD"
               truststoreAlgorithm="GuanxiProvider"
               sslProtocol="TLS"
               />

add a new section immediately after the one you uncommented. This is for a secure port on 8444. We need this to run the IdP's Attribute Authority using client authentication, which forces the SP to send its certificate on the connection. If we used full client authentication on the default 8443 port we couldn't connect to any of the web applications in the browser as we would not have a certificate to offer.

  <Connector port="8444" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="true"
               keystoreFile="TOMCAT_HOME/security/tomcat.jks"
               keystorePass="KEYSTORE_PASSWORD"
               truststoreFile="TOMCAT_HOME/security/tomcat.jks"
               truststorePass="KEYSTORE_PASSWORD"
               truststoreAlgorithm="GuanxiProvider"
               sslProtocol="TLS"
               />

replace TOMCAT_HOME with the full path to your Tomcat installation and replace KEYSTORE_PASSWORD with the password you choose when creating the keystore. Note that we're using the same file for the keystore and truststore. This is due to the fact we do not need a normal truststore as the Guanxi Provider takes its place.

Installing the Guanxi Provider

Normally, Tomcat requires a truststore to authenticate incoming HTTPS connections but this does not scale in a large federation of hundreds or thousands of entities, so Guanxi provides its own SSL authentication mechanism via the Guanxi Security Provider. This is a lightweight module that passes incoming X509 certificates to the Guanxi modules to allow authentication to take place at the web application level. To install the provider, first download the JAR file from the following URL:

http://source.uhi.ac.uk/mvn/org/guanxi/guanxi-provider/1.0.0/guanxi-provider-1.0.0.jar

Copy this jar to the following directory:

Unix : JAVA_HOME/jre/lib/ext
OS X : JAVA_HOME/lib/ext

or:

/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/lib/ext

Windows:

JAVA_HOME/jre/lib/ext

Next, register the Guanxi provider with the JRE. To do this, go into the directory:

JAVA_HOME/lib/security

and open the file:

java.security

You will see a list of registered providers, e.g.:

security.provider.1=sun.security.provider.Sun
security.provider.2=com.apple.crypto.provider.Apple
security.provider.3=sun.security.rsa.SunRsaSign
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider

add the Guanxi provider to the list as the last provider. In the case of the above list of registered providers, the new list will look like this:

security.provider.1=sun.security.provider.Sun
security.provider.2=com.apple.crypto.provider.Apple
security.provider.3=sun.security.rsa.SunRsaSign
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider
security.provider.8=org.guanxi.security.provider.GuanxiProvider

The Guanxi Security Provider is now installed, registered and ready for use by Tomcat.
You can now test your Tomcat by using the following URLs:

http://localhost:8080
https://localhost:8443

Setting up the Guanxi webapps

Building from source

To build from source, you'll need to install Maven2 and then get the latest version from the GitHub site. We'll checkout the source to SRC_HOME:

mkdir SRC_HOME
cd SRC_HOME
git clone git@github.com:guanxi/guanxi-beans.git
git clone git@github.com:guanxi/guanxi-core.git
git clone git@github.com:guanxi/guanxi-build.git
git clone git@github.com:guanxi/guanxi-common.git
git clone git@github.com:guanxi/guanxi-idp.git
git clone git@github.com:guanxi/guanxi-provider.git
git clone git@github.com:guanxi/guanxi-sp-engine.git
git clone git@github.com:guanxi/guanxi-sp-guard.git
git clone git@github.com:guanxi/guanxi-wayf.git

you should then have the directory structure:

guanxi-beans
guanxi-core
guanxi-build
guanxi-common
guanxi-idp
guanxi-provider
guanxi-sp-engine
guanxi-sp-guard
guanxi-wayf

now edit the file:

guanxi-idp/src/main/webapp/WEB-INF/guanxi_idp/config/spring/farm/persistence.xml

changing:

<property name="databaseDirectory"><value>/tmp/derby</value></property>

to whatever path you think is a suitable replacement for
/tmp/derby

for example, if you are using Windows you should change it to something like:
C:\tmp\derby

This setting tells the Apache Derby implementation of the attribute Persistence Engine, where to create the database that will hold persistent attributes. It's not really meant for production use. For production, you can comment this out and uncomment either the JDBCPersistenceEngine, which is configured to work with MySQL or the PostgresPersistenceEngine. Persistent attributes are important for preserving personalisation settings at an SP. For example, a lot of SPs use the value eduPersonTargetedId to allow an otherwise anonymous user to personalise a resource. Thus it's important that for that SP, the value of eduPersonTargetedId for that user must remain the same for every resource access session. So it must only be generated once and persisted in the database. If it's not persisted, any changes in the backend system from which the attribute value is generated will cause loss of personalisation for the user.
Now build and run the tests:

cd guanxi-build
mvn clean install

if you have trouble with the tests, build without running them:

mvn -Dmaven.test.skip=true clean install

Once it's built, copy the directories as follows. You'll need to remember what you set GUANXI_HOME to when configuring Tomcat:

cd SRC_HOME
cp -r guanxi-idp/target/guanxi-idp-x.x.x GUANXI_HOME/guanxi_idp
cp -r guanxi-wayf/target/guanxi-wayf-x.x.x GUANXI_HOME/guanxi_wayf
cp -r guanxi-sp-engine/target/guanxi-sp-engine-x.x.x GUANXI_HOME/samlengine
cp -r guanxi-sp-guard/target/guanxi-sp-guard-x.x.x GUANXI_HOME/protectedapp

Don't start up tomcat yet as we need to make some small configuration changes.

Binary installation

If you would rather not build Guanxi from source, you can download the binary distributions of the Guanxi components. Download the binaries from the sourceforge site:
https://sourceforge.net/project/showfiles.php?group_id=134770

Uncompress each binary file and edit the file:

guanxi-idp-x.x.x/WEB-INF/guanxi_idp/config/spring/farm/persistence.xml

changing:

<property name="databaseDirectory"><value>/tmp/derby</value></property>

to whatever path you think is a suitable replacement for
/tmp/derby

for example, if you are using Windows you should change it to something like:
C:\tmp\derby

For the reasons for this see the source building notes above.

For each module, copy the directories as follows:

cp -r guanxi-idp-x.x.x GUANXI_HOME/guanxi_idp
cp -r guanxi-wayf-x.x.x GUANXI_HOME/guanxi_wayf
cp -r guanxi-sp-engine-x.x.x GUANXI_HOME/samlengine
cp -r guanxi-sp-guard-x.x.x GUANXI_HOME/protectedapp

Pre-startup configuration

Now it's time to make the manual configuration changes to the Guanxi modules. I'll assume you are now in the GUANXI_HOME directory:

cd GUANXI_HOME

Configure the Guard

Open the file:

protectedapp/WEB-INF/guanxi_sp_guard/config/guanxi-sp-guard.properties

change it to this:
host.name=localhost
entityid=protectedapp-guard
attribute.prefix=HTTP_
default.entity.id=ENTITYID_OF_IDP
 
cookie.domain=localhost
cookie.path=/
cookie.age.units=transient
cookie.age=minutes
cookie.prefix=GUANXI_GUARD_SERVICE_PROVIDER_
 
engine.gps.service.url=https://localhost:8443/samlengine/gps
engine.gps.service.timeout=10

"transient" Age units means the cookie will be deleted when the browser is closed.

Configure the WAYF

Open the file

guanxi_wayf/WEB-INF/config/wayf.xml

change the idp section to this:
<idp name="localhost" url="https://localhost:8443/guanxi_idp/SSO" />

Configure the Engine

Open the file:

samlengine/WEB-INF/guanxi_sp_engine/config/spring/services/generic/generic-profile-service.xml

look for the section:
<bean id="shibbolethProfileService"
        class="org.guanxi.sp.engine.service.shibboleth.ShibbolethProfileService"
        init-method="init">

change the "wayfs" property to:
    <property name="wayfs">
      <map>
        <entry key="__DEFAULT__" value="https://localhost:8443/guanxi_wayf/WAYF" />
        <entry key="protectedappguard" value="https://localhost2/guanxi_wayf/WAYF" />
      </map>
    </property>

and the "attributeConsumerService" property to:
<property name="attributeConsumerService"><value>https://localhost:8443/samlengine/shibb/acs</value></property>

then look for the section:
<bean id="saml2ProfileService"
        class="org.guanxi.sp.engine.service.saml2.SAML2ProfileService"
        init-method="init">

and change the "assertionConsumerServiceURL" property to:
<property name="assertionConsumerServiceURL"><value>https://localhost:8443/samlengine/s2/wbsso/acs</value></property>

Configure the IdP

Open the file:

guanxi_idp/WEB-INF/guanxi_idp/config/idp.xml

and change the Cookie section to:
  <Cookie>
    <Domain/>
    <Path>/</Path>
    <Age units="transient" />
    <Prefix>GUANXI_IDP_</Prefix>
  </Cookie>

the Domain should be empty for localhost. "transient" Age units means the cookie will be deleted when the browser is closed.

At the bottom of the file, enable syphoning of SAML assertions, to allow you to see what is being sent on the wire to the SP:

  <Debug>
    <SypthonAttributeQueries>yes</SypthonAttributeQueries>
    <SypthonAttributeAssertions>yes</SypthonAttributeAssertions>
  </Debug>

The raw SAML will be logged to the IdP log files:
GUANXI_HOME/guanxi_idp/WEB-INF/guanxi_idp/logs/sso-service.log - AuthenticationStatement
GUANXI_HOME/guanxi_idp/WEB-INF/guanxi_idp/logs/aa-service.log - Attribute assertions

Starting tomcat

Run the following command:

TOMCAT_HOME/bin/catalina.sh start

and inspect:
TOMCAT_HOME/logs/catalina.out

to make sure there are no errors. The next steps take care of registering the various modules with each other.

Registering the IdP with the Engine

This step requires that you shutdown Tomcat as the Engine will need to reload its list of configured IdPs:

TOMCAT_HOME/bin/catalina.sh stop

using the template below, create a new file:
samlengine/WEB-INF/guanxi_sp_engine/config/metadata/idp/localhost.xml

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor entityID="GUANXI--300538258" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol urn:mace:shibboleth:1.0">
      <KeyDescriptor use="signing">
          <ds:KeyInfo>
              <ds:X509Data>
                <ds:X509Certificate>
		 MIICfDCCAjugAwIBAgIRANwF9joZS5P3P2L1VLi0mdwwCQYHKoZIzjgEAzAcMRow
		 GAYDVQQDDBFHVUFOWEktLTMwMDUzODI1ODAeFw0wOTEyMTcxMDU1NDZaFw0xMDAx
		 MDYxMTA1NDZaMBwxGjAYBgNVBAMMEUdVQU5YSS0tMzAwNTM4MjU4MIIBuDCCASwG
		 ByqGSM44BAEwggEfAoGBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZp
		 RV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up
		 1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHH
		 AhUAl2BQjxUjC8yykrmCouuEC/BYHPUCgYEA9+GghdabPd7LvKtcNrhXuXmUr7v6
		 OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotU
		 fI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6A
	         e1UlZAFMO/7PSSoDgYUAAoGBAKHIXohtBS5O7MD59wG/HE8urc2CPvJhccGt1vgK
		 wE3qDUxA7pqljTIZpqMLEQcrUtAGoeH5m3CTlNRMwuzU0U2sBSHfOmFt/UinZNms
		 mzQo2jsQbmy/SOg1+zaoaKoR4EkNlbA9fGb+jDrsEAi86H7QgJF3NRxfUi8ecmA/
		 yDjjMAkGByqGSM44BAMDMAAwLQIVAJS4X6i7l7KArYpXyLw9cPmkcpfxAhQ35N1r
		 gwOyB8YBHDcTsu9Qnvdjzw==
	      </ds:X509Certificate>
            </ds:X509Data>
          </ds:KeyInfo>
      </KeyDescriptor>
    <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
	<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
	<SingleSignOnService Binding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" Location="https://localhost:8443/guanxi_idp/SSO"></SingleSignOnService>
	<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8443/guanxi_idp/WBSSO"></SingleSignOnService>
	<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://localhost:8443/guanxi_idp/WBSSO"></SingleSignOnService>
  </IDPSSODescriptor>
  <AttributeAuthorityDescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol">
    <KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
        <ds:X509Certificate>
	 MIICfDCCAjugAwIBAgIRANwF9joZS5P3P2L1VLi0mdwwCQYHKoZIzjgEAzAcMRow
	 GAYDVQQDDBFHVUFOWEktLTMwMDUzODI1ODAeFw0wOTEyMTcxMDU1NDZaFw0xMDAx
	 MDYxMTA1NDZaMBwxGjAYBgNVBAMMEUdVQU5YSS0tMzAwNTM4MjU4MIIBuDCCASwG
	 ByqGSM44BAEwggEfAoGBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZp
	 RV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up
	 1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHH
	 AhUAl2BQjxUjC8yykrmCouuEC/BYHPUCgYEA9+GghdabPd7LvKtcNrhXuXmUr7v6
	 OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotU
	 fI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6A
	 e1UlZAFMO/7PSSoDgYUAAoGBAKHIXohtBS5O7MD59wG/HE8urc2CPvJhccGt1vgK
	 wE3qDUxA7pqljTIZpqMLEQcrUtAGoeH5m3CTlNRMwuzU0U2sBSHfOmFt/UinZNms
	 mzQo2jsQbmy/SOg1+zaoaKoR4EkNlbA9fGb+jDrsEAi86H7QgJF3NRxfUi8ecmA/
	 yDjjMAkGByqGSM44BAMDMAAwLQIVAJS4X6i7l7KArYpXyLw9cPmkcpfxAhQ35N1r
	 gwOyB8YBHDcTsu9Qnvdjzw==
	</ds:X509Certificate>
       </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    <AttributeService Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding" Location="https://localhost:8443/guanxi_idp/AA"></AttributeService>
    <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
  </AttributeAuthorityDescriptor>
 
  <Organization>
    <OrganizationName xml:lang="en">Guanxi Localhost</OrganizationName>
    <OrganizationDisplayName xml:lang="en">Guanxi Localhost</OrganizationDisplayName>
    <OrganizationURL xml:lang="en">http://www.guanxi.uhi.ac.uk/</OrganizationURL>
  </Organization>
 
  <ContactPerson contactType="technical">
    <Company>Guanxi Localhost</Company>
    <GivenName>Guanxi</GivenName>
    <SurName>Localhost</SurName>
    <EmailAddress>test@test.com</EmailAddress>
    <TelephoneNumber>1234</TelephoneNumber>
  </ContactPerson>
 
</EntityDescriptor>

Open the file:

guanxi_idp/WEB-INF/guanxi_idp/config/idp.xml

and look for the section:
<identity name="exampleIdentity">

replace the entityID in the above template with the value of "issuer" from "exampleIdentity":
entityID="GUANXI--300538258"

Now open the file:
guanxi_idp/WEB-INF/guanxi_idp/keystore/guanxi_idp_cert.txt

and replace the ds:X509Certificate element contents in the above template, with the contents of guanxi_idp_cert.txt, without the BEGIN/END CERTIFICATE stuff.
You can now restart Tomcat:
TOMCAT_HOME/bin/catalina.sh start

Runtime configuration

This section deals with configuring the Guanxi modules to trust each other. Tomcat does not need to be restarted for this.

Registering the Guard with the Engine

Point your browser to the following URL:

https://localhost:8443/samlengine

and click on the "Register a Guard" link. To be able to register a Guard, we need some information from the Guard configuration.

open the file:

protectedapp/WEB-INF/guanxi_sp_guard/config/guanxi-sp-guard.properties

and copy/paste the value of the entityid key into the "Please choose an ID for your Guard" form field.
Choose "HTTPS" under "Please state whether http or https" and enter "8443" under "Please state the port".
Enter "localhost" under "The site name you wish to protect".
Enter "protectedapp" under "The name of the web application you wish to protect". This is the name of the webapp in which the Guard is running. In our case, it's "protectedapp", i.e. https://localhost:8443/protectedapp. The general rule is:

HTTP(S)://sitename:PORT/webapplication_name

under the remaining fields, enter whatever takes your fancy. You can use the following completed form as a guide:

Registering a Guard with the Engine
Registering a Guard with the Engine
Registering a Guard with the Engine

Registering the Guard with the IdP

Point your browser to the following URL:

https://localhost:8443/guanxi_idp

and click on the "Register Service Provider" link. To be able to register an SP, we need some information from the Guard configuration.

open the file:

protectedapp/WEB-INF/guanxi_sp_guard/config/guanxi-sp-guard.properties

and copy/paste the value of the "entityid" key into the "Service Provider's providerId" form field. Leave the rest of the form fields as they are.
The completed form should look like:
Registering the Guard with the IdP

Now you must resgister the Guard's SAML2 metadata with the IdP. To do this we need to shutdown Tomcat. Then create the file:

guanxi_idp/WEB-INF/guanxi_idp/metadata/protectedapp-guard.xml

with the contents:

<?xml version="1.0" encoding="UTF-8"?>
<EntitiesDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Name="http://ukfederation.org.uk" xsi:schemaLocation="urn:oasis:names:tc:SAML:2.0:metadata sstc-saml-schema-metadata-2.0.xsd   urn:mace:shibboleth:metadata:1.0 shibboleth-metadata-1.0.xsd   <a href="http://www.w3.org/2001/04/xmlenc#" title="http://www.w3.org/2001/04/xmlenc#">http://www.w3.org/2001/04/xmlenc#</a> xenc-schema.xsd   <a href="http://www.w3.org/2000/09/xmldsig#" title="http://www.w3.org/2000/09/xmldsig#">http://www.w3.org/2000/09/xmldsig#</a> xmldsig-core-schema.xsd">
<EntityDescriptor entityID="protectedapp-guard" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
	<SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol         urn:oasis:names:tc:SAML:1.0:protocol         urn:oasis:names:tc:SAML:2.0:protocol">
		<KeyDescriptor use="signing">
			<ds:KeyInfo>
				<ds:KeyName>protectedapp-guard</ds:KeyName>
				<ds:X509Data>
					<ds:X509Certificate>
						MIID5DCCAsygAwIBAgILAQAAAAABHxOLnfcwDQYJKoZIhvcNAQEFBQAwXzELMAkGA1UEBhMCQkUx
						EzARBgNVBAoTCkN5YmVydHJ1c3QxFzAVBgNVBAsTDkVkdWNhdGlvbmFsIENBMSIwIAYDVQQDExlD
						eWJlcnRydXN0IEVkdWNhdGlvbmFsIENBMB4XDTA5MDEyNjE0MjUwOFoXDTEyMDEyNjE0MjUwOFow
						gY8xCzAJBgNVBAYTAkdCMREwDwYDVQQIEwhTY290bGFuZDEVMBMGA1UEBxMMSXNsZSBvZiBTa3ll
						MSEwHwYDVQQKExhVSEkgTWlsbGVubml1bSBJbnN0aXR1dGUxDDAKBgNVBAsTA0xJUzElMCMGA1UE
						AxMcc3AudGVzdC5zZ2FyYmguc21vLnVoaS5hYy51azCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkC
						gYEAjNWugt4RSNtbQrmN54m5TLBxFDcQJIyKRFc6VLC8RnnRVURsNnDp2rOLkqdhxN1mrbyuNfxa
						JjSlCenQkC4l1rYUTVKW41A2LCqWx/K2rhlKvhdX1bKfx6WWMhFhAWSSVk0yBxIf7x0Hh7tZKimc
						MJNCRmolLY8kLONBwTMz2YECAwEAAaOB8zCB8DAOBgNVHQ8BAf8EBAMCBaAwHwYDVR0jBBgwFoAU
						ZWWjPdc7EaMKByU3yUJKW3Z3UOEwHQYDVR0OBBYEFJ7mwJ1jtjg34l4K4Z/z6d+vDP3tMDoGA1Ud
						HwQzMDEwL6AtoCuGKWh0dHA6Ly9jcmwuZ2xvYmFsc2lnbi5uZXQvZWR1Y2F0aW9uYWwuY3JsME8G
						CCsGAQUFBwEBBEMwQTA/BggrBgEFBQcwAoYzaHR0cDovL3NlY3VyZS5nbG9iYWxzaWduLm5ldC9j
						YWNlcnQvZWR1Y2F0aW9uYWwuY3J0MBEGCWCGSAGG+EIBAQQEAwIGwDANBgkqhkiG9w0BAQUFAAOC
						AQEAVeCEwWW/hNe5PYFTcG/Men7wjzO74Ki/XkP7DJbNngWIHrzVeUWJAO4nFeYwVlaSukJK/0gn
						qZXqmJt4KGUs3fMjwgnVY4WD+Mkkiure7x7wsGEXgnZ9t2XVh6G+PAjS0UcMalJVK4OFlSu8XezB
						J+Rrsee+/BCjyD757qWCBaRTeyB+E8UkMLaY9jqpJcpxmF3hEB7KxGNtUTXBVlvKNceuFEd+NOKi
						OwNsn7mXjt0ynLVE3Io0Fzg/td9+GzHUI/6Ai6Z0KNNAoqUnQlWyH3XcY5fmFa6xPOUygVnGCW8G
						4xWuOP42NyG1ytHceQYKYPa33Cdc4dnNB3yRM5oJbw==
					</ds:X509Certificate>
				</ds:X509Data>
			</ds:KeyInfo>
		</KeyDescriptor>
		<KeyDescriptor use="encryption">
			<ds:KeyInfo>
				<ds:KeyName>protectedapp-guard</ds:KeyName>
				<ds:X509Data>
					<ds:X509Certificate>
						MIID5DCCAsygAwIBAgILAQAAAAABHxOLnfcwDQYJKoZIhvcNAQEFBQAwXzELMAkGA1UEBhMCQkUx
						EzARBgNVBAoTCkN5YmVydHJ1c3QxFzAVBgNVBAsTDkVkdWNhdGlvbmFsIENBMSIwIAYDVQQDExlD
						eWJlcnRydXN0IEVkdWNhdGlvbmFsIENBMB4XDTA5MDEyNjE0MjUwOFoXDTEyMDEyNjE0MjUwOFow
						gY8xCzAJBgNVBAYTAkdCMREwDwYDVQQIEwhTY290bGFuZDEVMBMGA1UEBxMMSXNsZSBvZiBTa3ll
						MSEwHwYDVQQKExhVSEkgTWlsbGVubml1bSBJbnN0aXR1dGUxDDAKBgNVBAsTA0xJUzElMCMGA1UE
						AxMcc3AudGVzdC5zZ2FyYmguc21vLnVoaS5hYy51azCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkC
						gYEAjNWugt4RSNtbQrmN54m5TLBxFDcQJIyKRFc6VLC8RnnRVURsNnDp2rOLkqdhxN1mrbyuNfxa
						JjSlCenQkC4l1rYUTVKW41A2LCqWx/K2rhlKvhdX1bKfx6WWMhFhAWSSVk0yBxIf7x0Hh7tZKimc
						MJNCRmolLY8kLONBwTMz2YECAwEAAaOB8zCB8DAOBgNVHQ8BAf8EBAMCBaAwHwYDVR0jBBgwFoAU
						ZWWjPdc7EaMKByU3yUJKW3Z3UOEwHQYDVR0OBBYEFJ7mwJ1jtjg34l4K4Z/z6d+vDP3tMDoGA1Ud
						HwQzMDEwL6AtoCuGKWh0dHA6Ly9jcmwuZ2xvYmFsc2lnbi5uZXQvZWR1Y2F0aW9uYWwuY3JsME8G
						CCsGAQUFBwEBBEMwQTA/BggrBgEFBQcwAoYzaHR0cDovL3NlY3VyZS5nbG9iYWxzaWduLm5ldC9j
						YWNlcnQvZWR1Y2F0aW9uYWwuY3J0MBEGCWCGSAGG+EIBAQQEAwIGwDANBgkqhkiG9w0BAQUFAAOC
						AQEAVeCEwWW/hNe5PYFTcG/Men7wjzO74Ki/XkP7DJbNngWIHrzVeUWJAO4nFeYwVlaSukJK/0gn
						qZXqmJt4KGUs3fMjwgnVY4WD+Mkkiure7x7wsGEXgnZ9t2XVh6G+PAjS0UcMalJVK4OFlSu8XezB
						J+Rrsee+/BCjyD757qWCBaRTeyB+E8UkMLaY9jqpJcpxmF3hEB7KxGNtUTXBVlvKNceuFEd+NOKi
						OwNsn7mXjt0ynLVE3Io0Fzg/td9+GzHUI/6Ai6Z0KNNAoqUnQlWyH3XcY5fmFa6xPOUygVnGCW8G
						4xWuOP42NyG1ytHceQYKYPa33Cdc4dnNB3yRM5oJbw==
					</ds:X509Certificate>
				</ds:X509Data>
			</ds:KeyInfo>
		</KeyDescriptor>
		<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https://localhost:8443/samlengine/shibb/acs" index="0"/>
		<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://localhost:8443/samlengine/s2/wbsso/acs" index="1"/>
		<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://localhost:8443/samlengine/s2/wbsso/acs" index="3"/>
	</SPSSODescriptor>
	<Organization>
		<OrganizationName xml:lang="en">ORG</OrganizationName>
		<OrganizationDisplayName xml:lang="en">ORG</OrganizationDisplayName>
		<OrganizationURL xml:lang="en">http://org.ac.uk/</OrganizationURL>
	</Organization>
	<ContactPerson contactType="support">
		<GivenName>First</GivenName>
		<SurName>Last</SurName>
		<EmailAddress>mailto:test@test.com</EmailAddress>
	</ContactPerson>
	<ContactPerson contactType="technical">
		<GivenName>First</GivenName>
		<SurName>Last</SurName>
		<EmailAddress>mailto:test@test.com</EmailAddress>
	</ContactPerson>
</EntityDescriptor>
</EntitiesDescriptor>

Open the file:

samlengine/WEB-INF/guanxi_sp_engine/config/metadata/guards/protectedapp-guard/protectedapp-guard.xml

and copy the X509Certificate blocks into the above file, replacing the blocks already there.

Now create the file:

guanxi_idp/WEB-INF/guanxi_idp/config/spring/application/jobs/protectedapp-guard.xml

with the contents:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           <a href="http://www.springframework.org/schema/beans/spring-beans-2.0.xsd"></p>
<p>" title="http://www.springframework.org/schema/beans/spring-beans-2.0.xsd"></p>
<p>">http://www.springframework.org/schema/beans/spring-beans-2.0.xsd"></p>
<p></p></a>  <bean id="idpProtectedappMetadataParser" class="org.guanxi.common.job.SAML2MetadataParserConfig" init-method="init">
    <property name="jobClass"><value>org.guanxi.idp.job.SAML2MetadataParser</value></property>
    <property name="key"><value>protectedappMetadataParser</value></property>
    <property name="cronLine"><value>10 0/59 * * * ?</value></property>
    <property name="startImmediately"><value>true</value></property>
    <property name="metadataURL">
      <value>file:///Users/alistair/web/WWW/guanxi_idp/WEB-INF/guanxi_idp/metadata/protectedapp-guard.xml</value>
    </property>
    <property name="signed"><value>false</value></property>
    <property name="who"><value>Guanxi::IdP::MetadataParser</value></property>
    <!-- For caching offline versions of the metadata -->
    <property name="cacheDir"><value>/WEB-INF/guanxi_idp/metadata</value></property>
    <property name="cacheFile"><value>protectedapp-guard-cached-metadata.xml</value></property>
  </bean>
 
</beans>

changing 'metadataURL' to your correct path to protectedapp-guard.xml.

Now open the file:

guanxi_idp/WEB-INF/guanxi_idp/config/spring/application/entity.xml

and add the line:
<entry key="file:///Users/alistair/web/WWW/guanxi_idp/WEB-INF/guanxi_idp/metadata/protectedapp-guard.xml" value-ref="idpEntityManager"/>

to 'idpEntityFarm' under the existing 'ukfederation-metadata.xml' key.

Now open the file:

guanxi_idp/WEB-INF/guanxi_idp/config/spring/application/bootstrap.xml

and add the line:
<ref bean="idpProtectedappMetadataParser" />

under the existing 'idpUKFederationMetadataParser' bean ref.

Now go back to:

protectedapp/WEB-INF/guanxi_sp_guard/config/guanxi-sp-guard.properties

and set the default IdP to use, using the IdP's entityID from its idp.xml:
default.entity.id=GUANXI-1944500581

restart tomcat before proceeding.

Viewing the attributes

We are now ready to use Shibboleth, provided by Guanxi, to extract and view attributes for a user from an IdP.

SAML2 Web Browser SSO

Point your browser at the following URL:

https://localhost:8443/protectedapp/protected/headers.jsp?entityID=IDP_ENTITY_ID

where IDP_ENTITY_ID is obtained from the IdP's config file:
guanxi_idp/WEB-INF/guanxi_idp/config/idp.xml

and is the value of "issuer" in the section:
<identity name="exampleIdentity">

or you can omit the entityID parameter by adding it to the Guard configuration:
default.entity.id=GUANXI-1944500581

When logging in to the IdP, use the username "harrymcd" and the password "growl". These can be found/changed in the file:

guanxi_idp/WEB-INF/guanxi_idp/config/shared/flatfile.xml

Click on the "Login" button.

The next page you should see contains the attributes from the IdP:
Attributes

Shibboleth

Point your browser at the following URL:

https://localhost:8443/protectedapp/protected/headers.jsp

You should see the following WAYF page. Click on the "Proceed" button. You should then see the IdP login page. Use the username "harrymcd" and the password "growl". These can be found/changed in the file:
guanxi_idp/WEB-INF/guanxi_idp/config/shared/flatfile.xml

Click on the "Login" button.

The next page you should see contains the attributes from the IdP:
Attributes

Logging out of the IdP and SP

You can play about with the logout links thus:
Click on "Logout of the SP" then hit the Back button on the browser and refresh the page with the attributes. You will be redirected to the WAYF as you have logged out of the SP. You won't have to login at the IdP again, as you haven't logged out of the IdP, so your session is still active.
Click on "Logout of the SP" then hit the Back button on the browser and click on "Logout of the IdP", hit the Back button again and refresh the page with the attributes. This time you will be redirected to the WAYF (logged out of SP) and you'll also have to login at the IdP again (logged out of the IdP).
You can also logout of both the SP and the IdP by closing the browser as the cookies are set to transient.

Troubleshooting

The browser is always redirected to the WAYF after logging in to the IdP

This means the localhost cookie is not being set at the Guard. Check the file:

TOMCAT_HOME/webapps/protectedapp/WEB-INF/guanxi_sp_guard/config/guanxi-sp-guard.properties

and make sure the cookie domain is set to:
cookie.domain=localhost

Currently, only Firefox is reliable for setting localhost cookies. IE and Safari do not work in this respect.

Invalid value: not encoded properly error

If you see the following error while registering an IdP with the Engine:

org.apache.xmlbeans.impl.values.XmlValueOutOfRangeException: Invalid value: not encoded properly

it means you have copy pasted the BEGIN CERTIFICATE, END CERTIFICATE lines as well as the certificate lines. Do not copy/paste those BEGIN, END lines.

Download a preconfigured localhost installation

You can download a preconfigured localhost installation from here (44M).