what is guanxi beans

Wed, Jun 17, 2009

I’ve been asked quite a few times where people can find the source code for Guanxi::Beans, i.e. guanxi-beans-x.x.x.jar, so I thought I’d just jot down a few notes on this module.

Guanxi::Beans contains a load of Java classes that the other modules (IdP, Engine, Guard) use to work with SAML and their own XML configuration files. The confusing thing is, there’s no source code. The beans are generated using XMLBeans, which process the various XML schemata that Guanxi uses. The main ones are:

  • Beans/xsd/saml - SAML1.1 and SAML2 metadata XML schemata
  • Beans/xsd/shibboleth - the Shibboleth SAML Profile schema
  • Beans/xsd/guanxi-*.xsd - the Guanxi configuration files
There are various others such as the SOAP schema which allows the IdP and Engine to work with SOAP using Java classes. Indeed, none of the Guanxi modules have to bother with raw XML. They manipulate SAML, SOAP and Guanxi configuration files using the beans in guanxi-beans-x.x.x.jar

There is source that is generated by XMLBeans when creating the Guanxi beans, which can be found in Beans/src but it’s not meant to be modified.

The bean generation is started from Beans/pom.xml using the command:

mvn clean install

which creates the source files, compiles them and puts all the classes in guanxi-beans-.x.x.x.jar. All Java package and class names are controlled from the file:

Beans/xsd/guanxi.xsdconfig

<xb:namespace uri=“urn:guanxi:idp”>
  <xb:package>org.guanxi.xal.idp</xb:package>
</xb:namespace>
the above tells XMLBeans to put all objects in the “urn:guanxi:idp” schema, found in guanxi-idp.xsd into the Java org.guanxi.xal.idp package.

If we consider the IdP attribute mapping config file, vars.xml:

<var name=“affiliation.member” value=“member” />
we can work with this using the beans from the xsdconfig controlled schema to Java classname mappings in guanxi.xsdconfig:
<xb:qname name=“gxidp:mapVarType” javaname=“MapVar”/>
so a &lt;var&gt; node can be accessed from Java using the class:

org.guanxi.xal.idp.MapVar

where xal stands for XML Abstraction Layer. It’s the same for creating and parsing SAML:

org.guanxi.xal.saml_1_0.protocol.RequestDocument.Factory.newInstance();
will create a new SAML Request, to send an AttributeQuery to an IdP for example. The org.guanxi.xal.saml_1_0.protocol package is created from the Beans/xsd/saml/*.xsd schemata, with RequestDocument being the Java class that handles SAML Request elements, which is defined in the SAML schema.

So XMLBeans provides a great way to work with XML. The Guanxi modules work entirely with Java objects and only have to break out to DOM-land, i.e. raw XML, when they need to sign the SAML messages but they immediately go back into Bean-land to send and receive the SAML messages.

comments powered by Disqus