In order to join a Shibboleth compatible federation, you need a way for your users to be able to say to another website, or VLE, “I am an authorised user of this Bodington VLE” and also to say to the other VLE, “I am a member of such and such Bodington group”. For example, another website or Bodington VLE may be hosting a Bodington sysadmins’ information page, which can only be accessed by Bodington system administrators. To access such a page, you have to prove that you are indeed a Bodington system administrator. This is where Guanxi comes in.
When you try and access the sysadmins’ site, that site, being a Shibboleth compatible Service Provider, will ask you “Where are you from?”. Normally this will direct you to a website where you can choose your institution. You are then redirected to your institution’s Shibboleth compatible Identity Provider. This is Guanxi.
Guanxi will then display a login page for you to enter your username and password. This authentication page is hosted within your Guanxi enabled Bodington and is accessed via HTTPS, so it’s pretty secure. If, however, you first logged in to your Bodington VLE and accessed the sysadmins’ page from within Bodington, then you won’t see the Guanxi authentication. Guanxi will know you’re already logged in.
Guanxi will then compose a special message using the Security Assertion Markup Language (SAML) to say to the sysadmin’s page Service Provider (SP), “the user you just sent to me is an authorised user of this system”. Guanxi won’t tell the SP who you are, just the fact that you’re an authorised user of the VLE.
The SP will then go directly to your Bodington VLE’s Guanxi and ask it for group membership information on you. Remember though, this is all done via anonymous “handles”, very long strings of digits. Guanxi gives these to the SP but knows how to translate them back to a user in the VLE. All the SP ever sees is a very long string of digits.
Guanxi will then automatically query your Bodington VLE for your groups membership and find out that you’re in the sysadmins group. It then has to tell the SP that you’re in the sysadmins group. However, before it can do that, it must look in it’s Attribute Release Policy to see if you’ve actually allowed Guanxi to release this information. If you’ve forbidden it to release the fact that you’re in the sysadmin group, then Guanxi will not tell the SP this fact. However, you won’t get access to the SP’s sysadmins’ page.
The last step is for Guanxi to compose another SAML message, containing your group information and send it to the SP. The SP then looks at this, sees you’re in a Bodington sysadmins group and lets you access the protected sysadmins’ page.
That’s the functionality your Bodington VLE now has.
So how do you enable Guanxi in Bodington?
The Guanxi IdP is embedded in Bodington and is ready to run. All you have to do is find a text editor and open the file:
[BODINGTON_HOME]/WEB-INF/web.xml
where [BODINGTON_HOME] is where your Bodington VLE is installed, e.g. /usr/local/tomcat/webapps/bodington.
In web.xml, at the bottom of the file, you’ll find instructions for enabling the Guanxi IdP.
All you have to do is delete a couple of lines and restart your servlet container, usually Tomcat.
The final step in enabling Guanxi is to open a web browser and go to the URL:
http://www.bodington.url/guanxi/SSO
where www.bodington.url is the URL of your installed Bodington, e.g.
http://www.bodington.site.ac.uk/guanxi/SSO
You should see a Guanxi login page. This means that Guanxi is now enabled. What’s it done? When you access the SSO component, if a keystore containing your commercial secure certificates is not present, Guanxi will create a self signed one for you and will also export the required certificate for you to use later in the process. The files you should be aware of are:
[BODINGTON_HOME]/WEB-INF/keystore/guanxi_idp.jks
This is the Guanxi keystore, used for signing SAML assertions. If you already have a keystore, you should copy it here and call it guanxi_idp.jks
[BODINGTON_HOME]/WEB-INF/keystore/guanxi_idp_cert.txt
This is the Guanxi IdP’s X509 certificate, containing it’s public key. You will use this later to configure the Service Provider.
[BODINGTON_HOME]/WEB-INF/config/idp.xml
This is the Guanxi IdP’s configuration file. If you’ve let Guanxi create you a keystore, you don’t have to modify this file. Remember where it is though, as you’ll use it later to configure the Service Provider. If you’ve copied your own keystore to guanxi_idp.jks, you should replace the example values with your own.
The default self-signed certificate and keystore that Guanxi creates is valid for 3 weeks. After that you should acquire commercially signed certificates and create your own keystore. The default keystore is only for evaluation and should not be used in a production environment. Indeed, most federations will not accept an IdP that is using self-signed certificates.
How to control what information is released about users
In the directory [BODINGTON_HOME]/WEB-INF/config/attributors, you’ll find a file called:
BodingtonAttributorARP.xml
This is an XML file that tells the IdP what it can and can’t release to a third party. The basic idea is you fill a bag with attributes then stack the bags on top of each other to form a set of rules. Whichever bag is matched first decides the policy. In the supplied file, there is a bag called “global“. This denotes all values of all groups. However, if you don’t want info on the sysadmin group being made available to third parties, you would put the restrictedBodington bag on top of the global bag. This would mean that during it’s processing of the user’s group memberships, the IdP would come across the sysadmin group. It would then ask the ARP if it’s ok to release this info. The ARP would find the restrictedBodington bag on top of everything else, see that it contained the sysadmin attribute and say, no, you can’t release this attribute. However, for all other attributes, you can release them.
What Service Provider (SP) changes do you need to make?
For a Shibboleth compatible SP to talk to your new Guanxi IdP, you must give it some information about the IdP.
A Shibboleth SP needs to update two of it’s files. These aren’t anything to do with Guanxi and you won’t find them in Bodington. They reside on the server that hosts the Shibboleth SP. In the examples that follow [SHIBBOLETH_HOME] is where Shibboleth is installed on the system, e.g.:
/usr/local/shibboleth
The first file we need to modify is:
[SHIBBOLETH_HOME]/etc/shibboleth/shibboleth.xml.
This tells the SP where your Guanxi IdP components are, i.e. the SSO and AA components. Remember[BODINGTON_HOME]/WEB-INF/config/idp.xml? This file contains the name under which Guanxi will issue SAML assertions. Open idp.xml in a suitable editor and locate the <issuer> element. If Guanxi has created the keystore for you, this element will look something like this:
<issuer>BodGuanxi-1283450654</issuer>
Copy the BodGuanxi-1283450654 part and paste it into your Service Provider’s FederationProvider section in shibboleth.xml. An example one is shown below. You can copy/paste this and change the parts shown in bold according to the <issuer> in idp.xml and the URL of your installed bodington:
<FederationProvider type=”edu.internet2.middleware.shibboleth.common.provider.XMLMetadata”>
<SiteGroup Name=”urn:mace:ac.uk:uhi.ac.uk:provider:identity:uhi.ac.uk” xmlns=”urn:mace:shibboleth:1.0″>
<OriginSite Name=”BodGuanxi-1283450654“>
<Alias>Bodington Guanxi IdP</Alias>
<Contact Type=”technical” Name=”The System Administrator” Email=”admin@admin.com“/>
<HandleService Location=”https://www.bodington.url/guanxi/SSO” Name=”BodGuanxi-1283450654“/>
<AttributeAuthority Location=”http://www.bodington.url/guanxi/AA” Name=”BodGuanxi-1283450654“/>
<Domain>bodington.url</Domain>
</OriginSite>
</SiteGroup>
</FederationProvider>
The last file we have to modify is:
[SHIBBOLETH_HOME]/etc/shibboleth/IQ-trust.xml:
This lets the Service Provider verify that your IdP is signing SAML assertions correctly. To proceed, you’ll need to locate the file we mentioned earlier:
[BODINGTON_HOME]/WEB-INF/keystore/guanxi_idp_cert.txt
This is the PEM certificate for the IdP. Open this text file in your favourite text editor and ignore the lines:
—–BEGIN CERTIFICATE—–
—–END CERTIFICATE—–
The bit you need is between these two lines and looks like a load of random text characters. In fact, it’s the IdP’s X509 certificate. We need to get this into the Service Provider’s IQ-trust.xml. To do this, copy all the text between the two lines to be ignored and paste it into the template shown below. Replace the random text characters shown in bold with the ones you copied from your guanxi_idp_cert.txt.
Next, replace the BodGuanxi-1283450654 shown in bold in the template below, with the value from the <issuer> element in your idp.xml:
<KeyAuthority VerifyDepth=”0″>
<ds:KeyName>BodGuanxi-1283450654</ds:KeyName>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>MIIDEDCCAs4CBEI6ogMwCwYHKoZIzjgEAwUAMG4xEDAOBgNVBAYTB1Vua25vd24x
EDAOBgNVBAgTB1Vua25vd24xEDAOBgNVBAcTB1Vua25vd24xEDAOBgNVBAoTB1Vu
a25vd24xEDAOBgNVBAsTB1Vua25vd24xEjAQBgNVBAMTCWJvZGluZ3RvbjAeFw0w
NTAzMTgwOTQwMTlaFw0wNTA2MTYwOTQwMTlaMG4xEDAOBgNVBAYTB1Vua25vd24x
EDAOBgNVBAgTB1Vua25vd24xEDAOBgNVBAcTB1Vua25vd24xEDAOBgNVBAoTB1Vu
a25vd24xEDAOBgNVBAsTB1Vua25vd24xEjAQBgNVBAMTCWJvZGluZ3RvbjCCAbcw
ggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUSKVLfSpwu7OTn9hG3UjzvRADDHj+A
tlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4AdNG/yZmC3a5lQpaSfn+gEexAi
wk+7qdf+t8Yb+DtX58aophUPBPuD9tPFHsMCNVQTWhaRMvZ1864rYdcq7/IiAxmd
0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1AoGBAPfhoIXWmz3ey7yrXDa4V7l5
lK+7+jrqgvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0SRZxI+hMKBYTt88JMozIpuE8
FnqLVHyNKOCjrh4rs6Z1kW6jfwv6ITVi8ftiegEkO8yk8b6oUZCJqIPf4VrlnwaS
i2ZegHtVJWQBTDv+z0kqA4GEAAKBgHa1O7ZJTSq+N4K/+uYgtQoi8MCKSszBx9Ww
kTT0wMWfVwBsVNQ2sTHcUQv3lS4LmPrzKBxMnX8ZQ2L3ZcWl374+2YdWVo+bwWKB
URU+L2d6a5HiZFaHYM0OyugmNiEpTYpCw2PU0W+SxZggG+kdOfO3PEc8pHoi5CO2
GvfiFvoZMAsGByqGSM44BAMFAAMvADAsAhR8bT7wZvjpq6vqo6vFv/oRY4rOCAIU
Oz6+hkVbMFCDwQNUV7tpfZ7+FV0=
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyAuthority>
You’re now ready to restart the Service Provider’s shar service and use your Guanxi enabled Bodington in a federation.
Guanxi Components
The Guanxi IdP comes with 3 components:
- Guanxi::Common – A library of common functionality shared throughout the Guanxi system
- Guanxi::IdP – The Identity Provider (IdP) servlet. This provides a shibboleth compatible Handle Service (HS) and Attribute Authority (AA)
- SAMUEL – The Guanxi partial SAML 1.1 implementation
Normally, Guanxi runs in standalone mode, as a separate servlet, handling requests from a Shibboleth compliant WAYF or SP but it’s also capable of running as a Bodington context. For example, the default installation of Guanxi within Bodington would provide the following contexts. Note, replace www.bodington.ac.uk with the URL of your own installed Bodington.
Normal Bodington VLE:
http://www.bodington.ac.uk/site – Normal Bodington VLE
Guanxi IdP:
http://www.bodington.ac.uk/guanxi/SSO – Guanxi shibboleth compatible HS
http://www.bodington.ac.uk/guanxi/AA – Guanxi shibboleth compatible AA
As you can see, only the Guanxi IdP is visible. The other two components, Guanxi::Common and SAMUEL are in the background, helping the IdP do it’s job.
The only interaction between the two contexts, /site and /guanxi comes via the Bodington Guanxi plugins:
BodingtonAuthenticator – Uses whatever class is in WEB-INF/bodington.properties to authenticate a user.
BodingtonCookieHandler – Intercepts Bodington cookies to bypass re-authentication if the user is already logged in to Bodington.
BodingtonAttributor – Uses the Bodington VLE’s group classes to gather group memberships for a user
In a Guanxi enabled Bodington, you’ll see some extra directories and files. In the examples that follow, [BODINGTON_HOME] refers to where, on your web server, your Bodington VLE is installed, e.g. /usr/local/tomcat/webapps/bodington.
Guanxi File Structure
[BODINGTON_HOME]/guanxi
This directory contains the user interface for the IdP. There are three main pages that you may want to customise, although they come with an attractive default Guanxi interface. All the files can be accessed via the URL http://www.bodington.ac.uk/guanxi
– authenticator.jsp This is the main Guanxi authentication page. You won’t see this if you’re already logged in to Bodington.
– index.html This is the main Guanxi information page
– bodhowto.html How to enable Guanxi within Bodington
– sso_error.jsp This is the error page that displays any authentication errors etc.
The following sub folders contain other subsidiary files:
– /images Contains all the Guanxi interface images
– /shibboleth Contains the auto submitted form for supporting Shibboleth Browser/POST profile communication.
[BODINGTON_HOME]/WEB-INF/config
This is where Guanxi stores it’s configuration files
– aa.xml The Attribute Authority configuration file
– idp.xml The Identity Provider configuration file
The following directories and files are used by the various Guanxi authentication, attributes and cookie handling plugins:
– /attributors/attributors.xml This file tells Guanxi what attributes it can use and what classes to load to access them
– /attributors/BodingtonAttributor.xml The configuration file of the Bodington attribute gathering class
– /attributors/BodingtonAttributorARP.xml The Attribute Release Policy to be applied to the Bodington attribute gathering class
– /authenticators/authenticators.xml This file tells Guanxi what authentication mechanisms it can use and what classes to load to access them
– /cookies/AuthCookieHandlers.xml This file tells Guanxi what cookies it can intercept and what classes to load to process them
– /cookie/BodingtonCookieHandler.xml This file tells the Bodington cookie handler about the cookie it must intercept to stop a user having to re-authenticate
[BODINGTON_HOME]/WEB-INF/keystore
This directory holds the certificates required for signing SAML Assertions. Guanxi comes with a default keystore that will sign all SAML Assertions as the identity “bodington”. This is fine for trying out Guanxi with Bodington but you should create your own keystore with secure commercial certificates for production use.
– guanxi_idp.jks The Guanxi certificate keystore
Where to find more information
Bodington VLE
Download the Bodington VLE
The Guanxi Project
Shibboleth
SAML
Required JAR files
Guanxi requires the following jar files. These are all included in the Guanxi distribution for Bodington.
Guanxi::Common – servlet-api.jar
Guanxi::IdP – guanxi-common.jar, samuel.jar, bodserver.jar, ldap.jar, saaj.jar
Guanxi::WAYF – guanxi-common.jar, samuel.jar
SAMUEL – servlet-api.jar, axis.jar, jaxrpc.jar, saaj.jar, xmlsec.jar, commons-discovery.jar