Skip navigation.
Home
codeBrane
Home

Registering a commercial grade Guard

Submitted by alistair on Wed, 02/02/2011 - 11:38

Introduction

As you know, the Engine masquerades as Guards, which are the "real" Service Providers, visible in a federation. At the SSL level, this means the Engine has to sign all communications using Guard credentials. But how does it do that? Two-ways comms require a way to trust an incoming connection and a way to retrieve credentials to sign an outgoing connection. The truststore performs the former function, while the keystore performs the latter. When the Engine communicates with an IdP on behalf of a Guard, it takes the Guard's private key from the Guard's keystore and uses it to sign the connection. When the reply comes back from the IdP (usually the AA), the Engine checks in its truststore to see if the IdP's certificate is in there. If not, the Engine won't trust the IdP and will not communicate with it.

What happens when you register a Guard

Let's say you want to register a Guard that protects a web application and you've assigned the Guard an ID:

urn_bond_hq_top_secret_guard

You can use the Engine's registration page to register the new Guard:

https://spy.central.com/samlengine/register/guard

The Engine will then create a directory for the new Guard:

ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/metadata/guards/urn_bond_hq_top_secret_guard

with two files in it:

urn_bond_hq_top_secret_guard.jks
urn_bond_hq_top_secret_guard.xml

The first is the keystore that contains the Guard's private key and certificate, which is signed by the Engine, as the Engine is also a Certificate Authority (CA). Normally this is just for testing and you should replace the certificate with one that is signed by a commercial CA. The next section will cover this.
The Engine also puts the Guard's certificate in its truststore:

ENGINE_HOME/WEB-INF/guanxi_sp_engine/truststore/samlengine.jks

This means when the Guard asks for the WAYF location from the Engine via an HTTPS request, the Engine will trust the Guard over SSL.

How to manually register a Guard

If you have a web application for which you have a commerical certificate, normally it's stored in a keystore (.jks). We can follow the process from scratch:
First, create the initial Guard certificate:

keytool -genkey -keyalg RSA -alias bond.hq.ac.uk -keystore bond.hq.ac.uk.jks
 
Enter keystore password:  secretpassword
What is your first and last name?
  [Unknown]:  bond.hq.ac.uk
What is the name of your organizational unit?
  [Unknown]:  Special Ops
What is the name of your organization?
  [Unknown]:  MI5
What is the name of your City or Locality?
  [Unknown]:  London
What is the name of your State or Province?
  [Unknown]:  England
What is the two-letter country code for this unit?
  [Unknown]:  GB
Is CN=bond.hq.ac.uk, OU=Special Ops, O=MI5, L=London, ST=England, C=GB correct?
  [no]:  yes

next, create a Certificate Signing Request (CSR):

keytool -certreq -alias bond.hq.ac.uk -keyalg RSA -file bond.hq.ac.uk.csr -keystore bond.hq.ac.uk.jks

send the file bond.hq.ac.uk.csr to your commercial CA of choice (e.g. Thawte etc) and get the signed certificate back. Add this to the keystore:

keytool -import -alias bond.hq.ac.uk -trustcacerts -file bond.hq.ac.uk.crt -keystore bond.hq.ac.uk.jks
 
where the file bond.hq.ac.uk.crt is the signed certificate you got back from the CA.

You now have a commercial grade Guard. The next step is to register it with the Engine. Create a new directory at the Engine:

ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/metadata/guards/bond.hq.ac.uk

and copy the keystore into it:

ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/metadata/guards/bond.hq.ac.uk/bond.hq.ac.uk.jks

and create a metadata file in the directory:

ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/metadata/guards/bond.hq.ac.uk/bond.hq.ac.uk.xml

using the template:

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:gxmeta="urn:guanxi:metadata" entityID="bond.hq.ac.uk">
  <RoleDescriptor>
    <Extensions>
      <gxmeta:GuanxiGuardService>
        <gxmeta:VerifierURL>https://bond.hq.ac.uk:8443/webapp/guard.sessionVerifier</gxmeta:VerifierURL>
        <gxmeta:AttributeConsumerServiceURL>https://bond.hq.ac.uk:8443/webapp/guard.guanxiGuardACS</gxmeta:AttributeConsumerServiceURL>
        <gxmeta:PodderURL>https://bond.hq.ac.uk:8443/webapp/guard.guanxiGuardPodder</gxmeta:PodderURL>
        <gxmeta:Keystore>ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/metadata/guards/bond.hq.ac.uk/bond.hq.ac.uk.jks</gxmeta:Keystore>
        <gxmeta:KeystorePassword>secretpassword</gxmeta:KeystorePassword>
      </gxmeta:GuanxiGuardService>
    </Extensions>
  </RoleDescriptor>
  <Organization>
    <OrganizationName xml:lang="en">MI5</OrganizationName>
    <OrganizationDisplayName xml:lang="en">MI5</OrganizationDisplayName>
    <OrganizationURL xml:lang="en">http://bond.hq.ac.uk</OrganizationURL>
  </Organization>
  <ContactPerson contactType="technical">
    <Company>MI5</Company>
    <GivenName>James</GivenName>
    <SurName>Bond</SurName>
    <EmailAddress>007@bond.hq.ac.uk</EmailAddress>
    <TelephoneNumber>007</TelephoneNumber>
  </ContactPerson>
</EntityDescriptor>

of course, change the variables in the file to suit your particular Guard configuration.

Next you must add the Guard's certificate to the Engine's truststore. First extract the Guard's certificate:

cd ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/metadata/guards/bond.hq.ac.uk
keytool -keystore ./bond.hq.ac.uk.jks -export -alias bond.hq.ac.uk -rfc -file bond.hq.ac.uk.x509
 
remembering the password for the keystore (secretpassword in our case)
 
the file bond.hq.ac.uk.x509 should look something like this:
 
-----BEGIN CERTIFICATE-----
MIIDeDCCAzigAwIBAgIGARwjXOAMMAkGByqGSM44BAMwIjEgMB4GA1UEAwwXR3VhbnhpLkVuZ2lu
ZS5sb2NhbGhvc3QwHhcNMDgwOTAyMTM1MDAxWhcNMDgwOTIyMTQwMDAxWjBpMQswCQYDVQQGEwJH
QjESMBAGA1UECBMJSGlnaGxhbmRzMQ0wCwYDVQQHEwRTa3llMQwwCgYDVQQKEwNVSEkxDDAKBgNV
BAsTA1dXVzEbMBkGA1UEAxMScHJvdGVjdGVkYXBwLWd1YXJkMIIBtzCCASwGByqGSM44BAEwggEf
AoGBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs
14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy
9nXzrith1yrv8iIDGZ3RSAHHAhUAl2BQjxUjC8yykrmCouuEC/BYHPUCgYEA9+GghdabPd7LvKtc
NrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotU
fI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7P
SSoDgYQAAoGAEKnvX9jkrEzMZ+83gkseKYY27lE+7BkLFfWXadtSxY3GuxkTMtv0C+Ghplb1E+bG
vKQ9+KRcNs6TUAGI95w4NSWOXCQGYQcjrexPxMNqQsbpaj888L1vINvyLclbI3fXri9sI0mGC17/
Wgo1eaXsAEwqKSEwhsA4I+9Uw3FL7cWjgbMwgbAwWQYDVR0jBFIwUIAUVF9zgzBXZeVPfG1Hz8uY
+3CDTtOhJqQkMCIxIDAeBgNVBAMMF0d1YW54aS5FbmdpbmUubG9jYWxob3N0ghAbYtB7mBe9fMKK
Q4hqtd5uMB0GA1UdDgQWBBRWBJgX824a2B/2Xxwic+Lvekg+JzAMBgNVHRMBAf8EAjAAMA4GA1Ud
DwEB/wQEAwIFoDAWBgNVHSUBAf8EDDAKBggrBgEFBQcDAjAJBgcqhkjOOAQDAy8AMCwCFDMDcn0p
j2meE9fCmHuv91Ffc6gmAhQjPZZ9NP0gG//H/sJhUuD4LPrCIQ==
-----END CERTIFICATE-----

then add it to the Engine's truststore:

cd ENGINE_HOME/WEB-INF/guanxi_sp_engine/truststore
keytool -import -alias bond.hq.ac.uk -trustcacerts -file ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/metadata/guards/bond.hq.ac.uk/bond.hq.ac.uk.x509 -keystore ./samlengine.jks
 
you should see something like:
 
Owner: CN=bond.hq.ac.uk, OU=Special Ops, O=MI5, L=London, ST=England, C=GB
Issuer: CN=Thawte
Serial number: 11c235ce00c
Valid from: Tue Sep 02 14:50:01 BST 2008 until: Mon Sep 22 15:00:01 BST 2008
Certificate fingerprints:
	 MD5:  97:BA:78:CA:D1:B9:1F:5F:47:8A:F8:68:76:B5:6A:60
	 SHA1: 5F:79:38:0F:BA:FF:22:0E:4E:71:42:56:A9:75:FA:E5:13:CE:8F:32
Trust this certificate? [no]:  yes
Certificate was added to keystore

If you can't remember where your Engine's truststore is or what its password is, you can get that information from the file:

ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/spring/application/config.xml
 
<property name="trustStore"><value>/WEB-INF/guanxi_sp_engine/truststore/samlengine.jks</value></property>
<property name="trustStorePassword"><value>changeme</value></property>

Restart the Engine and you're ready to use the Guard.

How to extract a Guard certificate to give to an IdP

The easiest way to extract a Guard's certificate is to extract it from the Engine's truststore. To do this, you need to know the Guard's ID, e.g. bond.hq.ac.uk:

cd ENGINE_HOME/WEB-INF/guanxi_sp_engine/truststore
keytool -keystore ./samlengine.jks -export -alias bond.hq.ac.uk -rfc -file bond.hq.ac.uk.x509
 
for details of where the Engine's truststore is, see the previous section. You can then send the file bond.hq.ac.uk.x509 to the IdP.

»