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:
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:
where www.bodington.url is the URL of your installed Bodington, e.g.
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:
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
This is the Guanxi IdP’s X509 certificate, containing it’s public key. You will use this later to configure the Service Provider.
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:
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.:
The first file we need to modify is:
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:
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:
<SiteGroup Name=”urn:mace:ac.uk:uhi.ac.uk:provider:identity:uhi.ac.uk” xmlns=”urn:mace:shibboleth:1.0″>
<Alias>Bodington Guanxi IdP</Alias>
<Contact Type=”technical” Name=”The System Administrator” Email=”firstname.lastname@example.org“/>
<HandleService Location=”https://www.bodington.url/guanxi/SSO” Name=”BodGuanxi-1283450654“/>
<AttributeAuthority Location=”http://www.bodington.url/guanxi/AA” Name=”BodGuanxi-1283450654“/>
The last file we have to modify is:
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:
This is the PEM certificate for the IdP. Open this text file in your favourite text editor and ignore the lines:
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:
You’re now ready to restart the Service Provider’s shar service and use your Guanxi enabled Bodington in a federation.
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
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
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.
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
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
Download the Bodington VLE
The Guanxi Project
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