Installation

  1. Before continuing installation you should ensure you have all required dependencies for deployment available on your server.
  2. Your Apache HTTPD and Tomcat instances should be shutdown at this stage
  3. For new federation establishment you'll need to have already created a bilateral trust agreement between your first IDP and the federation registry SP before continuing. To successfully login to federation registry an attribute release policy similar to the following is required: 
      <AttributeFilterPolicy id="afp_for:<SP ENTITYID>">
    <PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="<SP ENTITYID>" />
        <AttributeRule attributeID="displayName">
      <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="eduPersonTargetedID">
      <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="email">
      <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="givenName">
      <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="homeOrganization">
      <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="homeOrganizationType">
      <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
    <AttributeRule attributeID="surname">
      <PermitValueRule xsi:type="basic:ANY" />
    </AttributeRule>
  </AttributeFilterPolicy>
  4. Create the database federationregistry and an account with read/write access for the application to utilize, we recommend the username 'fr'.
  5. Configure your Apache HTTPD and Tomcat servers for your domain. Ensure that mod_jk is able to successfully route requests to Tomcat. For security purposes Federation Registry should be only available over SSL connections.
  6. Ensure the mysql-connector jar is located in your Tomcat lib directory
  7. A location should be configured in your virtual host to direct requests for federationregistry to Tomcat. Below is sample configuration to achieve this, you'll need to edit to suit your environment. Do note the use of lazy sessions. This allows some parts of Federation Registry such as registering new Organizations, Identity Providers and Service Providers to be made available to folks who may not yet have an identity within your federation.
    <VirtualHost 1.1.1.1:443>
    	ServerName fr.host.edu.au:443
    	DocumentRoot /var/www/hosts/fr.host.edu.au

    	Include include/ssl-defaults.conf

    	SSLCertificateFile ...
    	SSLCertificateKeyFile ...
    	SSLCertificateChainFile ...

    	# Federation Registry
          	ProxyPass /federationregistry ajp://localhost:8009/federationregistry retry=2
      	<Location /federationregistry>
            	AuthType shibboleth
            	ShibRequireSession Off
            	ShibUseHeaders On
            	require shibboleth

    		# Insert filter
    		SetOutputFilter DEFLATE

    		# Netscape 4.x has some problems...
    		BrowserMatch ^Mozilla/4 gzip-only-text/html

    		# Netscape 4.06-4.08 have some more problems
    		BrowserMatch ^Mozilla/4\.0[678] no-gzip

    		# MSIE masquerades as Netscape, but it is fine
    		BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
    		# Don't compress images
    		SetEnvIfNoCase Request_URI \
    		\.(?:gif|jpe?g|png)$ no-gzip dont-vary

    		# Make sure proxies don't deliver the wrong content
    		Header append Vary User-Agent env=!dont-vary
    	</Location>
    </VirtualHost>
  8. Create a directory structure such as /opt/federationregistry to hold binaries, configuration and log files. We'll refer to this as $FRHOME (Don't literally enter this in configuration, you must manually expand it when referenced)
  9. Create $FRHOME/config, $FRHOME/logs and $FRHOME/war
  10. Copy your Federation Registry war file from your customized branding environment to $FRHOME/war. Generally this will be of the form federationregistry-X.Y.Z.war
  11. Copy fr-config.groovy.example from your packaging environment to $FRHOME/config/fr-config.groovy note we drop the .example extension here
  12. Edit your fr-config.groovy file (The following documentation uses dot notation. In the configuration file itself different levels are shown within braces. For example fedreg.bootstrap is equivalent to fedreg { bootstrap = ... }):
    • Set grails.serverURL to the location FR will be accessed by end users eg https://manager.aaf.edu.au/federationregistry
    • Set fedreg.deployment.environment equal to one of production|test|development|demo depending on your usage
    • Set fedreg.bootstrap to true
    • Set fedreg.enabledemonstration to false
    • Set fedreg.shibboleth.url to the main web URL for your federation
    • Set shibboleth.federationprovider.spactive to true
    • The value of fedreg.metadata.federation will appear in your Metadata document as the value of the attribute Name in your top level EntitiesDescriptor. Ensure this is correctly specified if you have pre-existing metadata
    • Configure values for nimble.messaging.mail to match your local mail server, this should be able to relay to other domains for workflow messaging purposes.
    • Uncomment the dataSource indicated for use in production environments, remove the definition for dataSource in development environments
    • Set log4j.appenders fr-app and stacktrace file attributes to the value of $FRHOME/logs/fr-app.log and $FRHOME/logs/stacktrace.log respectively
    • Most other values should be correct by default but do carefully audit the file against your federations requirements.
  13. Create the a webapp descriptor file with the name federationregistry.xml in your $TOMCAT/conf/Catalina/localhost directory.  Below is sample content for this descriptor, you'll need to edit to suit your environment 
    <Context docBase="<FRHOME>/war/federationregistry-X.Y.war"
             privileged="true"
         antiResourceLocking="false"
         antiJARLocking="false"
         unpackWAR="false"
         swallowOutput="true"
	 reloadable="true">
    <Resource name="jdbc/FEDERATIONREGISTRY"
     auth="Container"
     type="javax.sql.DataSource"
     driverClassName="com.mysql.jdbc.Driver"
     url="jdbc:mysql://127.0.0.1/federationregistry"
     username="fr" password="<YOUR PASSWORD>"
     maxActive="20" maxIdle="10" maxWait="-1" />

	<Environment name="fr_config" value="<FRHOME>/config" type="java.lang.String"/>

</Context>
  14. Start your Tomcat and Apache HTTPD instances
  15. You should be able to navigate to https://<server>/federationregistry/
  16. Assuming all is well you'll be presented the FR bootstrap screen, this console will directly execute groovy code and as a result populate your base system
  17. You'll now want to package a number of the base setup files for ease of use. Switch to the directory scripts/setup  in your branding environment and execute groovy buildFRFullSetup.groovy 
  18. Copy the content from the newly created file scripts/setup/frFullSetup.groovy and paste in the bootstrap window, click the execute button and ensure completion without error.
  19. Clear all code from the console
  20. Copy the content from scripts/setup/aafAttributePopulation.groovy file (or similar depending on the attribute set required for your federation) and paste in the bootstrap window, click the execute button.
  21. Clear all code from the console
  22. Copy the content from scripts/setup/createBaseEnvironment.groovy and paste in the bootstrap window - DO NOT EXECUTE YET
  23. Carefully review what this script will create as it is going to populate your initial IDP record
    1. Set federationName to value specified for fedreg.metadata.federation in your configuration
    2. otName, otDisplayName and otDescription define the initial OrganizationType that will be associated with your IDP. Should you wish to change these values ensure that otName appears in the set of values for fedreg.metadata.wayf.generateconfig.orgtypes in your configuration. You may reduce this list to a single entry if you don't expect to have multiple types of organization in your federation.
    3. orgName, orgDisplayName and orgURL should all be set to values describing the Organization the initial IDP belongs to
    4. contactName, contactSurname and contactEmail should describe the initial contact, this is probably your personal details
    5. hostname, scope, displayName and description should all be set to values describing the initial IDP. The value of hostname is used in EntityID generation as such entityID:"https://$hostname/idp/shibboleth" - If your IDP is not using a standard Shibboleth generated EntityID you'll want to tweak what is set for entityID to match IDP configuration.
  24. Click the execute button
  25. Clear all code from the console
  26. At this point your base federation is setup and you should be ready to login to the system
  27. Copy and paste the code application.config.fedreg.bootstrap = false into the console and click execute.
  28. Edit fr-config.groovy again setting the value of fedreg.bootstrap to false
  29. Refresh the page, you'll be presented with the default welcome screen which details attribute requirements to login and allows public registration of Organizations, Identity Providers and Service Providers
  30. Click 'Login' after which you should need to establish a session with your IDP.
  31. Once this process has completed you'll be presented with the personalized Federation Registry dashboard screen for your account. You'll also have super administrator access for Federation Registry.
  32. Use the Identity Provider interface to add certificates, attribute support and NameID support as well as administrators for the initial Identity Provider you've created.
  33. Create a service provider to represent the service provider protecting the Federation Registry instance.
  34. Once these stages are complete FR should be generating minimal but valid data exports to start expanding your federation with.
  35. Enjoy!
Comments