Superseded install guide

Note: This version of the IdP Install Guide has been superseded. Please refer to the IdP Overview page for the latest version of this guide.

Installing a Shibboleth 2.x IdP

 Software  Version Provide by  Since
 Shibboleth  2.3.4 A Project of the Internet2 Middleware Initiative Oct 27th, 2011
 uApprove     2.3.1 SWITCHaai Oct 10th, 2011

This page is a guide to installing a Shibboleth 2.3.4 and later IdP. This page assumes the IdP would be installed on a blank Linux system (typically a virtual machine) and follows from that point on. The same process can be used to bootstrap a generic VM. The IdP will be installed both with the Shibboleth IdP software and the uApprove attribute release approval web application.

This guide is periodically updated as new versions of the software installed become available. This guide is current for IdP 2.3.4 and uApprove 2.3.1. The guide is written with assumption that CentOS/RHEL 6 as the OS and Tomcat6 as the web application server.

During the installation there will be a number of tests to confirm previous steps have been performed correctly. These tests are tagged with the  icon to the left. For a successful installation please ensure all tests are completed before moving to the next step. If you have difficulty completing a test please contact the AAF support desk for assistance.


A Linux system (VM) preinstalled with base OS distribution, with current updates installed.

    • Minimum hardware recommendation: 1GB RAM, 16GB diskspace minimum
    • Linux distribution: recommended: RHEL 6 or CentOS 6 (Differences between RHEL 5/Centos 5 will be noted).
Network requirements:
    • Allocating a hostname (typically and a static IP address.
Setup firewall rules:
    • Enable incoming and outgoing TCP connections to ports 80, 443, 8443. Note that these connections MUST be direct connections and cannot go through a proxy. In particular, the port 8443 connections use client SSL authentication and will not work with proxies that try to step in the middle of an SSL connection, even if the server certificate is pre-loaded onto the proxy.
    • Enable connections to an external NTP server or provide an internal NTP server.
Provide an X509 certificate for the allocated hostname issued by a CA trusted by major browsers.
    • There are no further requirements on the certificate, it would be only accessed from inside a browser
Access to an institutional LDAP server (with a system account allowed to read all attributes needed for the federation). This typically includes the following information:
    • LDAP server hostname and port number
    • Search base (subtree DN)
    • Bind DN for a generic reader account
    • Bind password for this account
    • Search filter - i.e. what attribute contains the user's login name?

Modifications to Identity Management system

Your Identity Management System (IdMS) will very likely have most of the attributes asked for by the federation - or will have enough information to synthesize the specific attribute values on the fly inside the IdP. But for some attributes, the IdMS might not have enough information. The following information should be considered for adding into your IdMS:
  • eduPersonEntitlement: The eduPersonEntitlement attribute is a storage container for values representing privileges to access resources within the federation. It is a multi-valued string attribute. The values will have the form of a URI - with specific values that are yet to be defined. The attribute definition details are (source: Attribute Recommendation 2.1 (PDF), page 14):


eduPerson [eduPerson]
SAML attribute name: urn:mace:dir:attribute-def:eduPersonEntitlement 
LDAP syntax:  directoryString [] 
Number of values:  Multiple 
Example values:
  • auEduPersonSharedToken: The auEduPersonSharedToken uniquely identifies users when accessing certain resources - particularly within the computational grid and data grid. The values should be opaque, non-reassignable and persistent - and transferrable when a user moves between institutions. Even though the values are typically created as hash-values on first use, they MUST be stored and each institution must be ready to accept values users already have when coming from another institution. The attribute can be stored in either the IdMS directly (preferred), or in a database. The attribute definition details are (source: Attribute Recommendation 2.1 (PDF), pages 9-10, with OID updated to correct value):


Origin/ObjectClass:  auEduPerson 
SAML attribute name: 
LDAP syntax:  directoryString [] 
Number of values:  Single 
Example values:  ZsiAvfxa0BXULgcz7QXknbGtfxk 

  • eduPersonAssurance: This attribute represents the Levels of Assurance. Either add the attribute into the IdMS directly, or start collecting enough information to synthesize the values later in a scripted attribute definition (like done for Affiliation below).  The attribute definition details are (source: Attribute Recommendation 2.1 (PDF), page 13):


Origin/ObjectClass:  eduPerson 
SAML attribute name:  urn:oid: 
LDAP syntax:   directoryString [] 
Number of values:  multiple 
Example values:  See AAF IdentityLoA Vocabulary 


System firewall configuration

  • Edit /etc/sysconfig/iptables and add rules to permit incoming traffic to ports 80, 443, and 8443; add the following just below the rule for port 22:
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 8443 -j ACCEPT

  • Restart iptables:
service iptables restart

Bootstrapping the VM

We assume a standard install of either CentOS or RHEL, version 6. 

NOTE: CentOS/RHEL 5: The IdP web application will run inside Tomcat  6. CentOS/RHEL 5 comes with Tomcat5 but can NOT be used by Shibboleth. Tomcat6 can be installed from JPackage or installing from a tar-ball from Apache

Note: Shibboleth has not been tested with Tomcat 7 yet, use the latest Tomcat 6 version only.

Install packages

  • Apache with mod_ssl, Java (with javac) and Tomcat:
yum install httpd mod_ssl java-1.6.0-openjdk java-1.6.0-openjdk-devel ant tomcat6

  • MySQL (needed for storing sharedToken values and uApprove attribute release approvals)
MySQL is not strictly required and an alternative database system may be used if already available on site - just use the corresponding JDBC drivers for the alternative database.
yum install mysql mysql-server

  • Install NTP (if time synchronization is to be done inside the VM)
yum install ntp

Local configuration

  • Configure NTP: time synchronization is crucial for the Shibboleth IdP to correctly interact with Service Providers in the federation. Please gather beforehand the hostname or IP address of the time server provided within your organisation. Further on, we'll assume it's If your organisation is not providing one, you may use an external source (including the default servers listed in /etc/ntp.conf) - but make sure your firewall allows the NTP traffic through (outgoing UDP port 123 traffic + reply packets).
    • Do a one-off synchronization
ntpdate -s

    • Edit /etc/ntp.conf and:
      • Comment out local server (server and fudge
      • Comment out CentOS servers (all lines starting with server)
      • The local time server:

    • Make ntpd start on system startup
chkconfig ntpd on

    • Start ntpd now
service ntpd start

    • Check ntpd is running and synchronizing: run
ntpdc -p

  • Disable SELinux: the Apache LDAP module does not work with SELinux - SELinux would not allow the module to open outgoing TCP connections.
    • Disable SELinux now:
echo 0 > /selinux/enforce

    • And for future restarts, edit /etc/sysconfig/selinux and change:

Basic Shibboleth IdP and uApprove installation

Rationale and planning

From the very beginning, we will install the Shibboleth IdP:
  • as a web application WAR file managed by Tomcat
  • with uApprove integrated into the web application
  • with a Tomcat login screen used for authentication
Having done these steps early in the installation prevents them from slipping later on.

The installation paths will be (as close to defaults as possible, putting everything under /opt:)

Note: As of uApprove 2.3.1 the configuration is integrated into the Shibboleth IdP.
  • IDP_HOME - /opt/shibboleth-idp (default)
  • Tomcat home: /var/lib/$TOMCAT_NAME (where Tomcat web applications and common files live)
Your IdP hostname will be
Your scope, home organization name and security domain will be
Your IdP entityId will be

  • The Shibboleth IdP installation directory (from where Shibboleth IdP software is installed) will be /opt/shib-src/shibboleth-identityprovider-<version> - and the name of the directory will be stored in SHIB_INST_HOME (here, we assume version is 2.3.4)
  • Configure the corresponding environment variable: create /etc/profile.d/ with the following content (and make the file executable):





Basic Shibboleth Installation

  • Create an installation directory and download Shibboleth
mkdir /opt/shib-src
cd /opt/shib-src
unzip shibboleth-identityprovider-${IDP_VERSION}
  • Invoke installer
sh ./
  • When prompted, give the following non-default answers:
    • FQDN is the hostname assigned to your IdP, typically
    • Keystore password would be used to create the java keystore containing the back-channel certificates. As the private key will be also stored on disk in an unencrypted X509 key file, there is no need to choose a secure keystore password... (Note: you will need the Keystore password later in this guide).
Keystore: changeit


When reruning the installer in the future (you'll be asked to do so further on in this guide), you'll be asked whether to overwrite the configuration files. 
It is important you answer NO to that question - otherwise, all modifications made to the configuration files will be lost.
  • This installs the Shibboleth IdP web application into /opt/shibboleth-idp/war/idp.war

Configure Tomcat and deploy the IdP WAR

Context Deployment Fragment

  • Create /etc/$TOMCAT_NAME/Catalina/localhost/idp.xml with the following content:


      <Context docBase="/opt/shibboleth-idp/war/idp.war"
               swallowOutput="true" />

Endorsed libraries

  • Endorse XML libraries used by the IdP installed into Tomcat6.
    • Create /var/lib/tomcat6/common/endorsed:
mkdir -p /var/lib/tomcat6/common/endorsed

    • Add the following to /etc/tomcat6/tomcat6.conf to make endorsed directories really work:

    • and copy all jars from $SHIB_INST_HOME/endorsed/ into this endorsed directory:
cp $SHIB_INST_HOME/endorsed/* /var/lib/tomcat6/common/endorsed


  • Connectors in /etc/$TOMCAT_NAME/server.xml, if not already defined, define a n AJP connector at port 8009
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

  • And comment out the existing http connector defined for port 8080:
    <Connector port="8080" protocol="HTTP/1.1"
               redirectPort="8443" />

SOAP Endpoints

  • Shibboleth IdPs and SP may communicate directly, as opposed to sending messages via the user's browser, during certain operations (Attribute Query, Artifact Resolution, and Logout).

    • Download tomcat6-dta-ssl-1.0.0.jar (asc) in to /usr/share/tomcat6/lib
    • Add the following connector definition to Tomcat's TOMCAT_HOME/conf/server.xml file:
<Connector port="8443" 
           keystorePass="PASSWORD" />

    • Replace IDP_HOME with the IdP home directory entered during installation.
    • Replace PASSWORD with the password for the IdP key entered during installation.

Memory settings

  • Tweak Tomcat memory settings: increase the default Java minimal and maximal heap size settings to at least 512MB (or more, depending the total RAM in your VM)
    • Edit /etc/$TOMCAT_NAME/$TOMCAT_NAME.conf and add:
JAVA_OPTS="-Xms256m -Xmx768m"

File and Directory permissions

  • Make all files under /opt/shibboleth-idp owned by Tomcat
chown -R tomcat:tomcat $IDP_HOME

Tomcat start-up test

  • At this point Tomcat6 should start without error and the un-configured IdP should also start but will not be able to process logins at this point. To verify there are no errors you should check the following log files and confirm there are no errors.
  • You should correct all errors before moving on.
Tomcat6 logs
    • /var/log/tomcat6/catalina.out 
IdP log
    • $IDP_HOME/logs/idp-process.log
The final line of this log after a successful startup should similar to the following,
INFO [edu.internet2.middleware.shibboleth.common.config.BaseService:180] - shibboleth.HandlerManager service loaded new configuration

Configure Apache


Apache needs to be configured to:
  • Listen on ports 443 - this is done via a separate configuration file idp.conf  (bypassing parts of the default configuration in ssl.conf)
  • Configured to disable SSL session cache to work around a bug
  • To configure the virtual host for ports 443, download the files attached to this page idp.conf into the Apache configuration directory /etc/httpd/conf.d
  • In the files, replace all occurrences of with the hostname of your IdP
  • In idp.conf, configure the SSL VirtualHost to use the commercial certificate issued for your IdP
  • Make a backup of your ssl.conf
cd /etc/httpd/conf.d/
cp ssl.conf ssl.conf.dist

  • Edit your ssl.conf and:
    • Disable SSL session cache by commenting out the default SSLSessionCache directive and instead setting the cache to none:
#SSLSessionCache         shmcb:/var/cache/mod_ssl/scache(512000)
SSLSessionCache         none

  • Delete the whole default <VirtualHost> section from ssl.conf (the definitions in idp.conf will be used instead).
  • Delete the entry for Listen 443 (because we now have the directive in idp.conf).

Testing Apache

  • When Apache configuration is complete you should be able to start it and navigate to the IdP login page This should result in a page similar to the following.

Basic Shibboleth Configuration

Load the Federation Metadata

  • Configure the IdP to load the Federation Metadata in /opt/shibboleth-idp/conf/relying-party.xml by adding the following snippets into the Chaining MetadataProvider.
Note: There are three versions of the AAF Metadata, this installation uses the Complete Metadata. This version of the Metadata will continue to expand and grow as new features become available. For more information on the other version of Metadata see the knowledge base article "Three version of the AAF Metadata available".

<!-- AAF Federation metadata -->
<metadata:MetadataProvider id="AAF" xsi:type="metadata:FileBackedHTTPMetadataProvider"
            <metadata:MetadataFilter xsi:type="metadata:ChainingFilter">
                <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil"
                                maxValidityInterval="864000" />
                <metadata:MetadataFilter xsi:type="metadata:SignatureValidation"
                                requireSignedMetadata="true" />
                <metadata:MetadataFilter xsi:type="metadata:EntityRoleWhiteList">
                <metadata:MetadataFilter xsi:type="metadata:SchemaValidation"/>

Important: AAF Test environment metadata is being loaded. Remove '.test' from the Metadata URL to use the AAF Production version.

  • The AAF metadata should have their signature verified: add the trust engine definition as well (or uncomment and configure it further down in the file):
    <!-- Trust engine used to evaluate the signature on loaded AAF metadata. -->

    <security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticPKIXSignature">
        <security:ValidationInfo id="AAFCredentials" xsi:type="security:PKIXFilesystem">

  • This definition is referring to a certificate used to verify the signature - store the certificate in /opt/shibboleth-idp/credentials
cd /opt/shibboleth-idp/credentials

# For the AAF Test Environment
wget -O aaf-metadata-cert.pem

# For the AAF Production Environment
wget -O aaf-metadata-cert.pem

  • Note that the relying-party.xml file also refers to:
    • Our own metadata generated for the IdP in /opt/shibboleth-idp/metadata/idp-metadata.xml
    • Our own credentials stored in /opt/shibboleth-idp/credentials/idp.crt and /opt/shibboleth-idp/credentials/idp.key
    • Our own entityId (also stored in the self-metadata in /opt/shibboleth-idp/metadata/idp-metadata.xml

Test Metadata Loading

  • Restarting Tomcat should force the IdP to download and consume the AAF Metadata. Evidence of this occurring will be found by
    • The creation of updating of the AAF Metadata file /opt/shibboleth-idp/metadata/aaf-metadata.xml
    • Logs in the log file /opt/shibboleth-idp/logs/idp-process.log

Configure IdP with a login screen

It is desirable to have a site-branded login screen - which makes it easier for users to recognize the proper login screen - and may be necessary for deploying site-wide login and password-handling policies. The credentials are then cached only for a given period of time - instead of the whole browser session.

For deploying a login screen for a Shibboleth 2.x IdP:
  • Edit $IDP_HOME/conf/handler.xml and
    • Uncomment Username/Password Login Handler
Note: The AAF core attribute AuthenticationMethod is populated from the value provided in the ph:AuthenticationMethod below.
<!--  Username/password login handler -->

<ph:LoginHandler xsi:type="ph:UsernamePassword"

    • Comment out RemoteUser LoginHandler
<!-- Login Handlers -->
    <ph:LoginHandler xsi:type="ph:RemoteUser">

  • Optionally, customize session duration (default 30 minutes): add the following attribute (with the duration either in minutes or using the PT notation) to the UsernamePassword login handler: (Example extends session inactivity duration to 1 hour).

  • Edit $IDP_HOME/conf/login.config and provide details for the LDAP server (uncomment and configure LdapLoginModule section). You may have to provide more attributes than what's in the default commented-out section: namely subtreeSearch="true" and serviceUser and serviceCredential with login details for a privileged account (to look up users). 
   edu.vt.middleware.ldap.jaas.LdapLoginModule required
      serviceUser="<ldap user DN here>"
      serviceCredential="<ldap password here>"

Apply Institutional Branding

  • Customize login screen with site branding: edit src/main/webapp/login.jsp in your Shibboleth IdP source distribution
You should discuss the branding of your IdP with your institutions corporate branding team to ensure your users will be comfortable using the login page with their institute provided credentials.
  • Customize other IdP screens that your users may experience. Consistent institutional branding should be applied to the following files
    • error-404.jsp
    • error.jsp
    • login-error.jsp
Links to your institutional support site should be provided on these error pages.
  • Further details on applying institutional branding is provided later in this guide.
  • Ensure form-based auth managed by the container is enabled. Edit $SHIB_INST_HOME/src/main/webapp/WEB-INF/web.xml and uncomment the Form based login-config.
    <!-- Uncomment if you want form-based auth managed by the container -->
    <login-config> <auth-method>FORM</auth-method> <realm-name>IdP Password Authentication</realm-name> <form-login-config>
        <form-login-page>/login.jsp</form-login-page> <form-error-page>/login-error.jsp</form-error-page> </form-login-config> </login-config>

  • Rebuild and redeploy the WAR file afterwards by re-running the installer:
sh ./

LDAP connections with TLS/SSL with an untrusted certificate

The connection to the LDAP server can be established either over plain LDAP (no cryptographic protection), or over LDAP with either TLS/SSL. Some LDAP servers may be configured to only accept a bind operation over an cryptographically protected channel (TLS or SSL). Some LDAP servers might however be using a self-signed certificate - or a certificate issued by a CA not trusted by the default Java trust store. In that case, it is necessary to add the CA certificate issuing the LDAP server certificate (or alternatively the LDAP server cerificate itself) to the Java keystore.

  • Get the CA certificate and save it into /opt/shibboleth-idp/credentials/local-ca.crt (picking an appropriate file name)
  • Make a copy of the default Java key store:
cp $JAVA_HOME/jre/lib/security/cacerts $JAVA_HOME/jre/lib/security/cacerts.orig

  • Import the CA certificate into the Java keystore:
keytool -import -trustcacerts -alias "Local-CA" -file /opt/shibboleth-idp/credentials/_local-ca_.crt -keystore $JAVA_HOME/jre/lib/security/cacerts

  • Change the alias to something descriptive for the local CA
  • You will get prompted for the passphrase protecting the Java keystore. The default password is "changeit" (literally).
    1. only works for TLS and not SSL
    2. only works for the LDAP resolver itself, but not for the login screen connector in login.conf

Verify Branding and LDAP connection

To verify that the branding has been successfully applied and connectivity to your LDAP server works you can again navigate to the IdP login page This time you should see your institutional branding rather than the default example login page. You can repeat the Apply Institutional Branding until you are happy with the look and feel of your login page.

To test the LDAP connection attempt to login with a known username / password. If you enter a correct username and password the IdP should respond with an error, "An error occurred while processing your request". This indicates that the authentication to the LDAP server has been successful.


Rule 8.4 from the AAF Federation Rules states that "Identity Providers may only release Attributes to a Service Provider, or another Identity Provider, with the permission of the End User." The AAF recommends IdP install uApprove to provide a mechanism for used to consent to the release of attributes.

The uApprove application will step in the first time the user is logging in to a service. It will asks the user for permission to release the required (and desired) attributes to the service. The user will be asked again if the set of attributes released to the service changes. The user also has the option of giving a Global consent - permission to release any attributes to any service the user accesses in the future. The Global consent can be later revoked (via the Reset-approvals feature) and can also be completely disabled in the system-wide configuration (if the institution decided their users shouldn't be allowed to give global consent).

More information about uApprove, as well as download links, can be found at

As uApprove plugs into the IdP, the version of uApprove must be matched to be compatible with the version of IdP. The most recent version of uApprove 2.3.1 is compatible with IdP 2.3.4 (the most recent stable version of shibboleth).

The following instructions are closely based on the uApprove 2.3.1 installation manual,

Please check at the uApprove website that 2.3.1 is still the most recent version - and otherwise refer to the new version's installation manual for updated instructions.

uApprove can store the approval information in either a SQL database, or in a flat file. Storing the information in a SQL database is more scalable, and it also allows to revoke consent already given. This guide documents installing uApprove configured to use a local MySQL database. Please refer to the uApprove installation manual for other alternatives (such as connecting to an external database).

Install uApprove

  • Download the uApprove binary distribution, unpack it into $UAPPROVE_INSTALL.
unzip uApprove-${UAPPROVE_VERSION}.zip -d /tmp

Library Installation

Copy the libraries to the IdPs library directory:


cp $UAPPROVE_INSTALL/lib/jdbc/*.jar $IDP_INSTALL/lib

Provide the JDBC connector for your database to the classpath of the IdP. You might use one of the provided MySQL or HSQL JDBC connector:

cp $UAPPROVE_INSTALL/lib/jdbc/optional/#jdbc-connector#.jar $IDP_INSTALL/lib

Ensure that only one version of each library is present in $IDP_INSTALL/lib.

  • Create subdirectories under /opt/shib-src/uApprove, unzip the two ZIP files (idp-plugin and viewer), copy the configuration files from both into the config directory, and copy the IdP plugin libraries into the lib directory in the IdP installation directory.

Configuration Template

Copy the configuration template to the IdPs configuration directory:

cp $UAPPROVE_INSTALL/manual/configuration/ $IDP_HOME/conf

cp $UAPPROVE_INSTALL/manual/configuration/uApprove.xml $IDP_HOME/conf

Webapp files

Copy of the web application files like the JSPs, CSS files and images to the IdPs webapp directory:

mkdir $IDP_INSTALL/src/main/webapp/uApprove

cp $UAPPROVE_INSTALL/webapp/* $IDP_INSTALL/src/main/webapp/uApprove

Database Preparation

Configure MySQL for a very long connection timeout. By default, MySQL closes connections after 8 hours of inactivity. This breaks connections overnight - and the database clients running on the IdP (uApprove and also SharedToken) report errors when reconnecting to the database (even when using autoReconnect=true). Edit /etc/my.cnf and add the following into the [mysqld] section:

wait_timeout=31536000 # 3600*24*365 - one year

Setup the database, the following database parameters are as a guide only.
  • Create a MySQL database (uApprove), a user (also uApprove), and grant the user full access over the database (replace DB-PASSWORD with a suitable password):
mysql -u root
GRANT INSERT, SELECT, UPDATE, DELETE ON uApprove.* TO 'uApprove'@'localhost';

Create the initial table structures using the schema creation files
mysql -u root -p -D uApprove < $UAPPROVE_INSTALL/manual/storage/terms-of-use-schema.sql

mysql -u root -p -D uApprove < $UAPPROVE_INSTALL/manual/storage/attribute-release-schema.sql

Web Application Deployment Descriptor

Extend the IdP web application deployment descriptor ( $IDP_INSTALL/src/main/webapp/WEB-INF/web.xml):

Add $IDP_HOME$/conf/uApprove.xml to the <context-param...> area in the web.xml file.


Add the uApprove Filter and Servlets ( $IDP_INSTALL/src/main/webapp/WEB-INF/web.xml):

Add the following at the end of the web.xml file just prior the the closing </web-app>.

<!-- uApprove Filter and Servlets -->
<servlet-name>uApprove - Terms Of Use</servlet-name>
<servlet-name>uApprove - Terms Of Use</servlet-name>
<servlet-name>uApprove - Attribute Release</servlet-name>
<servlet-name>uApprove - Attribute Release</servlet-name>

Custom Configuration

In $IDP_HOME/conf/uApprove.xml change:
<context:property-placeholder location="classpath:/configuration/" />
<context:property-placeholder location="file:$IDP_HOME$/conf/" />
Note: You must expand $IDP_HOME$ to it's actual values, e.g. /opt/shibboleth-idp
Customize $IDP_HOME$/conf/ according your database environment and required features. See inline documentation for configuration options.


To activate uApprove the IdP must be re-deployed.


Start Tomcat

  • Start MySQL, Tomcat and Apache and make them auto start:
service mysqld start
service tomcat6 start
service httpd start
chkconfig mysqld on
chkconfig tomcat6 on
chkconfig httpd on

Testing uApprove

  • uApprove now be integrated into your IdP. This can be verified by,
    • Navigate to the uApprove TermsOfUse page, which should result in a page similar to the following.

This is the default Terms of Use page provided with uApprove.

Advanced uApprove Deployment

This sections contains advanced configuration topics.

Reset Attribute Release Consent

To provide an option that allows users to clear their attribute release consent during the login flow, add a check box to $IDP_INSTALL/src/main/webapp/login.jsp. You must re-deployed the IdP for this change to take effect.

<form action="<%=request.getAttribute("actionUrl")%>" method="post">   ...   <input id="uApprove.consent-revocation" type="checkbox" name="uApprove.consent-revocation" value="true"/>   <label for="uApprove.consent-revocation">Clear my attribute release consent</label>   ... </form>

JDBC Connection Pool Tuning

Cf. BoneCP config API for a list of all the available configuration settings.

The settings are defined in $IDP_HOME$/conf/uApprove.xml:

    <bean id="uApprove.dataSource" class="com.jolbox.bonecp.BoneCPDataSource" ...         p:minConnectionsPerPartition="1" p:maxConnectionsPerPartition="20" ... />

Apply Institutional Branding to uApprove

Institutional branding should be applied to the uApprove JSP and CSS files located in $IDP_INSTALL/src/main/webapp/uApprove. uApprove use the JavaServer Pages Standard Tag Library (JSTL). A reference guide is available at

When you have completed branding uApprove you must re-deploy the IdP to make the changes effective.

Changing the Terms of Use

A Terms of Use module is provided that asks your users to accept the terms before they can proceed. This version allows you to provide HTML formatted Terms. Configuration for the Terms of Use is in the $IDP_HOME/conf/ file. The following options are provided.

 Option     Values 
 tou.enabled true  - enables the Terms of Use Module
 false - disables
 tou.version A Number representing the version of Terms of Use. When the version changes users may be required to re-accept the Terms of Use.
 tou.resource Location of the HTML file to include within the Terms of Use page.
 For example: file:/opt/shibboleth-idp/conf/terms-of-use.html

Additional Information on uApprove

Additional configuration is possible with uApprove for more details refer to the uApprove manual provided on the SWITCHaai web site.

Configure Attribute Resolver

All attribute configuration is done in /opt/shibboleth-idp/conf/attribute-resolver.xml.

Edit the file and implement the following changes:

Link your Attribute Resolver to your LDAP server

In /opt/shibboleth-idp/conf/attribute-resolver.xml, uncomment the LDAP DataConnector element and configure it with local LDAP connection parameters to connect to your LDAP server (ldapURL, baseDN, principal, principalCredential) and also set the property java.naming.referral to "follow":

<resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory" 
    ldapURL="ldap://" baseDN="dc=institution,dc=domain,dc=com,dc=au" principal="LDAP-BIND-DN-HERE"
    <dc:LDAPProperty name="java.naming.referral" value="follow"/>

Link existing attributes

  • Define attributes available directly in LDAP: mail, sn, and givenName: just uncomment the relevant AttributeDefinition element for each of these attributes.
  • Define attributes available as an attribute in the LDAP with a slightly different name - typically, in ActiveDirectory, cn would be the user's login name, while displayName would be the users actual preferred (common) name. In that case, uncomment the relevant AttributeDefinition element and change the sourceAttributeID XML attribute to the name of the original attribute. If connecting to ActiveDirectory,
    • Define cn based on displayName (sourceAttributeID="displayName")
    • Define uid based on cn
  • Define eduPersonPrincipalName define based on cn with your institution's scope (in the form set the scope attribute like:
scope="" sourceAttributeID="cn"

  • If either eduPersonAssurance or eduPersonEntitlement are available in your IdMS, expose them via the IdP by uncommenting their respective definition in attribute-resolver.xml

Define static attributes

We need to define several attributes that would have a static value for each user. We do so by first defining a StaticDataConnector (close to where the commented-out example is):

  • Provide actual meaningful values for your institution: full organization name, home organization name (same as scope), and home Organization Type.
<!-- Static Connector -->
<resolver:DataConnector id="staticAttributes" xsi:type="dc:Static">
    <dc:Attribute id="o">
        <dc:Value>The Institution</dc:Value>
    <dc:Attribute id="homeOrganization">
    <dc:Attribute id="homeOrganizationType">

Now define the attributes:

  • Define organizationName by uncommenting the definition and changing the connector dependency from "myLDAP" to "staticAttributes"
  • Pasting in the definitions for homeOrganization and homeOrganizationType, not provided in the default configuration:
<resolver:AttributeDefinition id="homeOrganization" xsi:type="ad:Simple" sourceAttributeID="homeOrganization">
    <resolver:Dependency ref="staticAttributes" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:oid:" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:" friendlyName="homeOrganization" />

<resolver:AttributeDefinition id="homeOrganizationType" xsi:type="ad:Simple" sourceAttributeID="homeOrganizationType">
    <resolver:Dependency ref="staticAttributes" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:oid:" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:" friendlyName="homeOrganizationType" />

Define scripted attributes

The eduPersonAffiliation and eduPersonPrimaryAffiliation describe the affiliation type of the user authenticating. The typical question is: "Is this person staff or student?" The full set of values (with definitions available in the AAF Attribute Recommendation) is: faculty / student / staff / employee / member / affiliate / alum / library-walk-in. The eduPersonAffiliation attribute is multi-valued and should include all values that apply to the user.

Typically, the LDAP server will not be directly providing values for these attributes, but it would have some attributes that allow to determine at least some of the affiliation type values applying to the user - e.g. to tell whether the user is a staff member or a student.

In this case, we recommend defining the attributes using a scriptlet, synthesizing the value from the LDAP attributes available.

This would be very specific for each institution. We illustrate this in an example (based on an actual setup), where we assume the LDAP server has attributes:

  • isUnderGrad (boolean)
  • isPostGrad (boolean)
  • isStaff (boolean)
We decide to give anyone with isStaff=TRUE the "staff" affiliation, and to anyone with isUnderGrad=TRUE OR isPostGrad=TRUE the "student" affiliation. Also, anyone who is staff or student also gets the "member" affiliation.

  • We first define these attributes at the Shibboleth level, importing them from LDAP, using the following definitions. Note that as these attributes are not expected to be passed in Shibboleth assertions, the definitions don't have any AttributeEncoder elements. Otherwise, we would have to decide on attribute names / OIDs to use in the encoder definitions.
<!-- prerequisite to scripted eduPersonAffiliation -->
<resolver:AttributeDefinition id="isUnderGrad" xsi:type="ad:Simple" sourceAttributeID="isUnderGrad">
    <resolver:Dependency ref="myLDAP" />
    <!-- no encoder needed -->
<resolver:AttributeDefinition id="isPostGrad" xsi:type="ad:Simple" sourceAttributeID="isPostGrad">
    <resolver:Dependency ref="myLDAP" />
    <!-- no encoder needed -->
<resolver:AttributeDefinition id="isStaff" xsi:type="ad:Simple" sourceAttributeID="isStaff">
    <resolver:Dependency ref="myLDAP" />
    <!-- no encoder needed -->

  • We follow by defining eduPersonAffiliation using an AttributeDefinition of type Script:
<resolver:AttributeDefinition id="eduPersonAffiliation" xsi:type="ad:Script">
    <resolver:Dependency ref="isUnderGrad" />
    <resolver:Dependency ref="isPostGrad" />
    <resolver:Dependency ref="isStaff" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:eduPersonAffiliation" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:" friendlyName="eduPersonAffiliation" />
            if (eduPersonAffiliation == null) {
                    eduPersonAffiliation = new BasicAttribute("eduPersonAffiliation");
            is_UnderGrad = isUnderGrad != null && isUnderGrad.getValues().size()>0 && isUnderGrad.getValues().get(0).equals("TRUE");
            is_PostGrad = isPostGrad != null && isPostGrad.getValues().size()>0 && isPostGrad.getValues().get(0).equals("TRUE");
            is_Staff = isStaff != null && isStaff.getValues().size()>0 && isStaff.getValues().get(0).equals("TRUE");
            if (is_Staff) { eduPersonAffiliation.getValues().add("staff"); };
            if (is_UnderGrad || is_PostGrad ) { eduPersonAffiliation.getValues().add("student"); };
            if (is_UnderGrad || is_PostGrad || is_Staff ) { eduPersonAffiliation.getValues().add("member"); };

  • Finally, we define the eduPersonScopedAffiliation attribute by uncommenting the definition and:
    • setting your institution's scope, in the format scope=""
    • changing the dependency from LDAP to the previously defined attribute eduPersonAffiliation:
<resolver:Dependency ref="eduPersonAffiliation" />

Define sharedToken

  1. Following the fill sharedToken install guide, we will choose to store the SharedToken value in a MySQL database - to keep track of values issued and have a means of inserting a different value if someone asks for portability.

  • Download binary from AAF Files download site

The shared token value MUST be stored in either the LDAP server itself (preferred, keeps the values alongside primary identity information), or alternatively in a MySQL database (easier to get going by running a MySQL server directly on the IdP).

In this section, some instructions are specific to storing the shared token values in an LDAP server, some are specific to storing the values in a local MySQL server - please choose accordingly.

  • If storing the sharedToken value in your LDAP server, edit the conf/ inside the jar and change the following settings - the search filter should be the same as in your LDAP connector - configuring which LDAP attribute is the principal name:

  • Copy the JAR into $SHIB_INST_HOME/lib and (later) rerun the Shibboleth IdP installer to rebuild the webapp WAR archive. (When rerunning the installer, accept the default install location (or specify your install location, stored also in $IDP_HOME) and answer no to the question on overwriting configuration.)
cp arcs-shibext-*.jar $SHIB_INST_HOME/lib
sh ./

Configuring a MySQL database for storing sharedToken values

    • Install the driver (mysql-connector-java-5.x.y-bin.jar) into $SHIB_INST_HOME/lib and also into /opt/shibboleth-idp/lib (and rerun the Shibboleth IdP installer - now)
  • Create a MySQL user: run "mysql" as root and enter the following commands:
create user 'idp_admin'@'localhost' identified by 'IDP_ADMIN_PASSWORD';
 grant all privileges on idp_db.* to 'idp_admin'@'localhost';
  • Create a MySQL user: run "mysql" as idp_admin and enter the following commands:
 mysql -u idp_admin -p

 use idp_db;

 sharedToken VARCHAR(50),

Defining sharedToken attribute (both LDAP and MySQL)

  • Add schema definition to attribute-resolver.xml: add classpath:/schema/arcs-shibext-dc.xsd to the list of schema locations at the top of the file.
  • Add connector definition to attribute-resolver.xml (sharedToken) with the following customizations:
    • idPIdentifier - your IdP entityId, sourceAttributeID: combination of attributes that is unique, non-reassignable and if possible persistent - if usernames are not reused at your institution, username is perfectly fine - so the "cn" or "uid" attribute would do
    • If using a MySQL server, enter the database connection details, with the IDP_ADMIN_PASSWORD as defined just above
    • If storing sharedToken in an LDAP server:
      • Omit the DatabaseConnection element from the below snippet
      • Change the values to storeLdap="true" and storeDatabase="false"
<!-- ==================== auEduPersonSharedToken data connector ================== -->
<resolver:DataConnector xsi:type="SharedToken" xmlns=""
    <resolver:Dependency ref="myLDAP" />
    <DatabaseConnection jdbcDriver="com.mysql.jdbc.Driver"

  • Note: on the first install, generate a suitable salt value with:
openssl rand -base64 36
    • On subsequent installs, reuse the same value (stored somewhere carefully)
  • Note also that the SharedToken value depends on the IdP entityID - which could be picked up from the environment, but is better set in the configuration.
  • Note that the JdbcURL uses "?autoReconnect=true" - which is an extension from the original shared-token installation instructions.

  • IMPORTANT: If storing the values in an LDAP server, modify the LDAP DataConnector so that the FilterTemplate element is defined without any namespace qualifier, just with a default namespace, as in the following snippet. Make the same change for any LDAPPropertyElements. This is needed due to a known problem in the shared-token implementation.
        <FilterTemplate xmlns="urn:mace:shibboleth:2.0:resolver:dc">
        <LDAPProperty name="java.naming.referral" value="follow" xmlns="urn:mace:shibboleth:2.0:resolver:dc" />

  • Add attribute definition to attribute-resolver.xml (auEduPersonSharedToken)
<!-- ==================== auEduPersonSharedToken attribute definition ================== -->
<resolver:AttributeDefinition id="auEduPersonSharedToken" xsi:type="ad:Simple" sourceAttributeID="auEduPersonSharedToken">
    <resolver:Dependency ref="sharedToken" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:" friendlyName="auEduPersonSharedToken" />

eduPersonTargetedID (Needs updating [ComputedID -> StoredID])

Based on, define old and new definition of eduPersonTargetedID by:

The AAF Recommends using the StoreIDDataConnector over the computedID. See for configuration details.
  1. Uncommenting AttributeDefinition id="eduPersonTargetedID"
  2. Uncommenting DataConnector where id="computedID and changing it in the following ways:
    • Using just the username attribute (cn or uid) as the source attribute.
    • Using a value of salt generated (only at the first install, to be reused later) with
openssl rand -base64 36

This is the final configuration of the ComputeID DataConnector (without the proper salt)

    <!-- Computed targeted ID connector -->
    <resolver:DataConnector xsi:type="dc:ComputedId"
                            salt="your random string here">
        <resolver:Dependency ref="myLDAP" />

Verify changes to attribute-resolver.xml

A number of changes have been made to the attribute-resolver.xml file. Before continuing you should verify the changes you have made by restarting the Tomcat server and checking the idp-process.log file for errors.

Configuring Attribute Release

  • Attribute release is configured in /opt/shibboleth-idp/conf/attribute-filter.xml
  • The file can contain multiple policies.
  • Each policy can apply to a number of hosts or hostgroups (federations) - linked with the basic:OR policy.
  • Attributes are referred to by the "friendly" ID they get assigned in attribute-resolver.xml.
  • The following policy releases all the required attributes to the AAF Federation Registry - necessary for logging in there.

<afp:AttributeFilterPolicy id="federationManagerPolicy" >
    <afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="" />
    <afp:AttributeRule attributeID="displayName">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="commonName">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="surname">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="givenName">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="email">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="eduPersonPrincipalName">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="eduPersonScopedAffiliation">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="eduPersonAffiliation">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="eduPersonPrimaryAffiliation">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="homeOrganization">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="homeOrganizationType">
        <afp:PermitValueRule xsi:type="basic:ANY" />
    <afp:AttributeRule attributeID="eduPersonTargetedID">
        <afp:PermitValueRule xsi:type="basic:ANY" />

  • As needed, add more refined policies for hosts that need additional attributes. Instead of manually defining policies for all hosts, configure the automatic download of the AAF attribute release policy synthesized for your IdP. See the Knowledge base article: Automating Attribute Release for detailed instructions.
Note: You must have your IdP registered in the AAF Federation Registry before you can automate attribute release.

Verify changes to attribute-filter.xml

A number of changes have been made to the attribute-filter.xml file. Before continuing you should verify the changes you have made by restarting the Tomcat server and checking the idp-process.log file for errors.

Joining the federation

To join your IdP to the AAF you must registry it in the AAF Federation Registry. An overview of this process is provided in the Knowledge base article: How to technically join the Australian Access Federation

Register you Organisation

First you must register you organisation in the federation registry. You can do this without needing to login.

  • Go to the federation registry in the environment you which to join

  • Select the "Register new Organization" tab and follow the instructions.
Notes on using the FR.
  • All questions have a "more info" pop-up dialogue, just place your mouse over the  icon for more information.
  • If error is detected while entering data, e.g. invalid URL a warning message will be displayed which you must correct before move on.
  • Check you email, and spam box as the FR will send email to the email address you used when registering.
  • Read the messages on the screen and sent to you via email carefully 
  • You will receive an an email stating the following:
Your Organization has been registered with the federation and is now undergoing an approval process. This workflow may take upto 48 hours to complete. For progress updates please contact AAF support.
  • When approved you will receive a followup email. 
  • READ this email carefully. There is an action you must perform after your IdP is registered.
  • Keep this email until you have become the administrator of the Organisation. 

Your Organization has been activated within the Australian Access Federation and is now able to be used by other federtation members. A summary of your Organization details are provided below:

Internal ID:
Display Name:Organisation Name

You MUST undertake the following steps:

  1. If you need to register an Identity Provider you should undertake this process now, once your Identity Provider is active continue below. If you use an account with the AAF virtual home you can continue now.
  2. BECOME THE ADMINISTRATOR of this Organization by clicking here. This will also make you an executive workflow approvals member for this Organization.
  3. Ensure all components of your organization are valid and supply any missing information.
  4. Assign other users to your organizations executive approvals group (other users will need to login first for you to assign them admin rights).
    1. The Australian Access Federation provides a technical support service for all participants. All queries should be directed to the AAF online support helpdesk or via email to

Registry your IdP

After your organisation has been approved you can register your IdP at part of your organisation.

  • Go to the federation registry in the environment you which to add the IdP
  • Select the "Register new Identity Provider" tab and follow the instructions. You need to provide various pieces of information about your identity providers including
    • The Organisation to which the IdP belongs
    • The host your IdP is running on
    • The scope for which the IdP can assert attributes
    • The public key (/opt/shibboleth-idp/credentials/idp.crt)
    • The attributes supported by the IdP
  • You will receive an an email stating the following:

Your Identity Provider has been registered with the federation and is now undergoing an approval process. This workflow may take upto 48 hours to complete. For progress updates please contact AAF support.

Organization:Org Name
Internal ID:1,234
Display Name:IdP Name
Description:A test IdP
Entity Descriptor:

The Australian Access Federation provides a technical support service for all participants. All queries should be directed to the AAF online support helpdesk or via email to

  • When your IdP has been approved you will receive a followup email. 
  • READ this email carefully. There is an action you must perform after your IdP is registered.

Your Identity Provider has been activated within the Australian Access Federation and is now able to be used to login. A summary of your Identity Provider details are provided below:

Internal ID:1,234
Display Name:IdP Name
Description:A test IdP
Organization:Org Name

You MUST undertake the following steps:

  1. BECOME THE ADMINISTRATOR of this Identity Provider by clicking here.
  2. If you have recently registered an Organization you should follow the link provided to in the activation email for the Organization now.
  3. Ensure all components of your identity provider are valid and supply any missing information.
  4. If necessary provide administrative access to others (other users will need to login first for you to assign them admin rights).
    1. The Australian Access Federation provides a technical support service for all participants. All queries should be directed to the AAF online support helpdesk or via email to

Logging into the Federation Registry

After you receive the email confirming the successfully registration of your IdP several changes to the federation will occur within about 30 minutes.
  • Your IdP will be listed on in the Where are You From (WAYF) 
  • Your IdP's metadata will be included in the federation metadata
You must wait until both of these events have completed before attempting to login to the AAF Federation Registry for the first time.
Note: You may have to restart Tomcat to get your IdP to load the latest Metadata with your IdP included as your IdP may take up to 2 hours to do so automatically.

You are now ready to login to the Federation Registry for the first time. Navigate to the Federation Registry and select Login. This will take you to the WAYF, select you IdP and login. If all went well you should be logged into the Federation Registry.

The most common issue that occurs when logging in for the first time is missing required attributes. The Federation Registry will tell you which attributes where missing.

Becoming an Organisation Administrator

When your Organisation was approved you will have received an email "Your Organization has been activated within the...". In this email is a one shot link. 
  • Click on this link and login to the Federation Registry with the account you wish to use as Administrator.
As organisational administrator you will be able to perform the following functions on your Organisation. 
  • Add and modify the lists of contacts. The following contact types are available, you should assign someone to each role.
 Contact Type    Description
 Technical     Technical operation of the IdP and Services within the Organisation
 Marketing     Publicizing the federation within your organisation
 Billing Subscription payments 
 Support     Support desk
 Administrative     Federation membership documentation, compliance
 Business Owner      

  • Add and modify organizational administrator
Note: Being an organizational administrator does NOT automatically make you an Identity Provider administrator or a Service Providers administrator. 
  • Approval of Services that have been requested to be added under your organisation.
  • Modifying organisation details

Becoming an Identity Provider Administrator 

When your Identity Provider was approved you will have received an email "Your Identity Provider has been activated within the...". In this email is a one shot link
  • Click on this link and login to the Federation Registry with the account you wish to use as Administrator.
As Identity Provider administrator you will be able to perform the following functions on your Identity Provider.
  • Add and modify the lists of contacts. See the list above for available contact roles.
  • Add and modify Identity provider administrators
  • Modify Identity Provider details.
Warning: Changing details of your Identity Provider can result in changes to the federation metadata which may impact on the operation of your IdP.

Registering SAML1.x Endpoints

Some Identity provides will need to work with older SAML1 (Shibboleth 1.3.x) service providers. By default the Federation Registry does not create the SAML1.x endpoints. Log a job with to request the addition of SAML 1.x endpoint. For more details set the Knowledge base article: SAML 1.x endpoints and Federation Registry

Advanced IdP Configuration

Enabling automatic reload

To automatically reload a service configuration (such as the attribute-filter.xml file), one has to add two attributes to the service definition: configurationResourcePollingFrequency (in milliseconds) and configurationResourcePollingRetryAttempts.

  • The change done to /opt/shibboleth-idp/conf/service.xml is thus:
     <srv:Service id="shibboleth.AttributeResolver"
         <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/attribute-resolver.xml" xsi:type="resource:FilesystemResource" />

     <srv:Service id="shibboleth.AttributeFilterEngine"
         <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/attribute-filter.xml" xsi:type="resource:FilesystemResource" />


     <srv:Service id="shibboleth.RelyingPartyConfigurationManager"
          depends-on="shibboleth.SAML1AttributeAuthority shibboleth.SAML2AttributeAuthority">
        <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/relying-party.xml" xsi:type="resource:FilesystemResource" />

     <srv:Service id="shibboleth.HandlerManager"
        <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/handler.xml" xsi:type="resource:FilesystemResource" />

Load Atribute Filter

This step should be done only after fully registering your IdP into the federation.

To automatically release attributes to new services registered in the federation, we will define inside the AttributeFilterEngine a second ConfigurationResource, loading the data from a remote HTTP URL (backed by a local file) (as documented in Shibboleth documentation on multiple policy group files

In services.xml, modify the AttributeFilterEngine in the following way:

  • increase the configurationResourcePollingFrequency to 2 hours
  • define a second ConfigurationResource, backed by a local file and pulling in the URL specific to your institution (the URL is available in the AAF Federation Registry in the IdP registration entry)
    <srv:Service id="shibboleth.AttributeFilterEngine"
        <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/attribute-filter.xml" xsi:type="resource:FilesystemResource" />
             <srv:ConfigurationResource xsi:type="resource:FileBackedHttpResource"
                   file="/opt/shibboleth-idp/conf/aaf-attribute-filter.xml" />

  • Increase polling frequency (2 hours recommended), in order to not put too much stress on the federation manager.
  • The attribute names used in the download policy file must match the local attribute names. Check that the attribute names in the downloaded attribute filter against their names in existing configuration files:
    • attribute-resolver.xml (attribute definitions, match against the ID in the AttributeDefinition element)
    • attribute-filter.xml (local attribute filter)
    • /opt/uApprove/conf/attribute-list (uApprove attribute list)

Customization and Branding

Customizing and branding IdP login screen

In a default install, the IdP login screen is displaying the Shibboleth project logo, a default prompt for username and password, and text saying that this screen should be customized. To establish trust with users, this page should at the very least have the proper institution logo and name and the instructions to customize the page should be removed. Each institution may also wish to customize the graphics to match the style of their login pages. The instructions below show how to change the style of the login screen to match the style of the uApprove screen.

The instructions add a bit of functional logic into the login page - instead of displaying just the entityId of the login page, displaying the full name of the service as configured in the metadata (if available), followed by the hostname of the service.

All of the customization has to be done in the Shibboleth installation directory ($SHIB_INST_HOME, in particular to src/main/webapp/login.jsp) - and after any changes, it is necessary to re-deploy the IdP web application (re-run ./ and restart Tomcat).

For reference, see the Shibboleth Login Page customization instructions at

To customize the login screen with your institutional branding:
  • Copy your institution's logo into $SHIB_INST_HOME/src/main/webapp/images/inst_logo.gif (change the filename here and later on as suitable)
  • Edit $SHIB_INST_HOME/src/main/webapp/login.jsp and:
  • Set head->title to "Institution-name Login" (with your institution name)
  • Do the same for the <h1> element (and for formatting purposes, demote this to an <h2> element)
  • Delete the paragraph saying this is a sample login page
  • Change link to the logo image from /images/logo.jpg (Shibboleth logo) to /images/inst_logo.gif (your institution's logo)
  • Nice framing: wrap the whole HTML body in the following DIV element - applying the same style as what the uApprove screen is using:
<div style="width: 650px; margin-left:auto; margin-right:auto; border-style: solid; border-color: #00247D; border-width: 1px; padding: 10px; text-align: left; ">

  • If suitable, change the phrasing on the login prompt and change the formatting from "<h2>" to just plain paragraphs ("<p>"):
<p>You are accessing <strong><%= loginContext.getRelyingPartyId() %></strong></p>
<p>Please login with your AUT username and password.</p>

As of Shibboleth IdP 2.3.0, the default login page now displays not just the service entityID but also the service DisplayName and Description if available in the metadata. This is facilitated through tags from the idpui tag library, documented at the IdPAuthUserPassLoginPage. However, some of the features used by the default login page (like the service logo) are not currently  available in the metadata produced by the Federation Registry, so we still recommend to customize this page heavily: remove the left/right frame arrangement, and also display the service hostname (extracted from the entityID).

  • Add the following code snippet into login.jsp to construct the hostname:
<!-- Local extension: display the name of the service -->
String GetHostnameByURI(String uri)
  /* reusing uApprove's Controller.getResourceHost code */
    int i1 = uri.indexOf("//");
    int i2 = uri.indexOf("/", i1+2);
    // LOG.debug("uri received = \"" + uri + "\"");

    // return just the component out of
    if ( i2 >= 0 )
       uri = uri.substring(i1 + 2, i2);
    else if ( i1 >= 0 )
       uri = uri.substring(i1 + 2);

    // return just the component out of
    if (uri.indexOf(':')>=0) {
        uri = uri.substring(uri.lastIndexOf(':')+1);
    //LOG.debug("hostname extracted = \"" + uri + "\"");

  return uri;

<!-- getting relying party full name -->
<%@ page import="edu.internet2.middleware.shibboleth.common.relyingparty.RelyingPartyConfigurationManager" %>
<%@ page import="edu.internet2.middleware.shibboleth.idp.util.HttpServletHelper" %>
<%@ page import="" %>
<%@ page import="edu.internet2.middleware.shibboleth.idp.authn.LoginContext" %>
<%@ page import="org.opensaml.saml2.metadata.EntityDescriptor" %>
   StorageService storageService = HttpServletHelper.getStorageService(application);
   LoginContext loginContext = HttpServletHelper.getLoginContext(storageService,application, request);
   String hostname = loginContext.getRelyingPartyId();
   try {
       hostname = GetHostnameByURI(loginContext.getRelyingPartyId());
   } catch (Exception e) {
       /* Intentionally ignored:
        * Could not get detailed service name, will display basic name only */

Note: this snippet uses code from as well as code developed for the AAF.
  • Further edits to login.jsp:
    • Comment out the <div class="rightpane"> section with the right panel.
    • Comment out the opening and closing div tags for loginbox, leftpane and content
    • Replace the prompt "The web site described to the right has asked you to log in..." with:
<p>You are accessing service <strong><idpui:serviceName/> at <%= hostname %></strong><br>
           <p>This site has asked you to log in and you have chosen <strong>YOUR-INSTITUTION</strong> as your home institution.<br>
           Please login with your YOUR-INSTITUTION username and password.</p></p>
  • Finally, re-deploy the IdP with:
service $TOMCAT_NAME restart

Customizing and branding uApprove

The uApprove web application by default displays the SWITCH AAI branding. To customize this for the local institution (display the institution logo), one has to edit the header.jsp template in the uApprove web application installation tree and rebuild the web application. Note also that the explanation message given to the user (for why the user is visiting this application) can be customized in /opt/uApprove/viewer-$UAPPROVE_VERSION/webapp/WEB-INF/classes/

  • Backup the original header.jsp file:
cp /opt/shib-src/uApprove/viewer-$UAPPROVE_VERSION/webapp/header.jsp /opt/uApprove/viewer-$UAPPROVE_VERSION/webapp/header.jsp.orig

  • Copy your institiution logo into /opt/shib-src/uApprove/viewer-$UAPPROVE_VERSION/webapp/images/inst_logo.gif (adjust filename as suitable)
  • Edit /opt/uApprove/viewer-$UAPPROVE_VERSION/webapp/header.jsp
    • Replace link to SWITCH AAI logo (images/switch-aai.gif) with images/inst_logo.gif
    • Delete the AAI specific links just below that
  • Rebuild the uApprove web application:
cd /opt/shib-src/uApprove/viewer-$UAPPROVE_VERSION/
ant deploy -Duapprove.deployment=/opt/uApprove/war

  • Restart tomcat:
service $TOMCAT_NAME restart

Friendly attribute names

By default, uApprove would be representing attributes by their local alias - which may not provide the best possible user experience. Names like "eduPersonPrincipalName" look quite cryptic to an ordinary user. The metadata syntax allows to provide friendly names (even locale-specific multiple names) in the attribute-resolver.xml file, and uApprove will pick the attribute names from there.

The syntax for specifying the attribute names is:

<resolver:AttributeDefinition xsi:type="ad:Simple" id="email" sourceAttributeID="mail">
    <resolver:Dependency ref="myLDAP" />
    <resolver:DisplayName xml:lang="en">Email address</resolver:DisplayName>
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:mail" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" />

Add the following attribute descriptions for the respective attributes into attribute-resolver.xml, right between the Dependency and AttributeEncoder elements:

uid:                           <resolver:DisplayName xml:lang="en">Local user ID</resolver:DisplayName>
email:                         <resolver:DisplayName xml:lang="en">Email address</resolver:DisplayName>
commonName:                    <resolver:DisplayName xml:lang="en">Common name</resolver:DisplayName>
surname:                       <resolver:DisplayName xml:lang="en">Surname</resolver:DisplayName>
givenName:                <resolver:DisplayName xml:lang="en">Given name</resolver:DisplayName>
eduPersonPrincipalName:        <resolver:DisplayName xml:lang="en">Global username (EPPN)</resolver:DisplayName>
displayName:                <resolver:DisplayName xml:lang="en">Display name</resolver:DisplayName>
organizationName:              <resolver:DisplayName xml:lang="en">Institution name</resolver:DisplayName>
homeOrganization:              <resolver:DisplayName xml:lang="en">Institution domain</resolver:DisplayName>
homeOrganizationType:          <resolver:DisplayName xml:lang="en">Institution type</resolver:DisplayName>
eduPersonAffiliation:          <resolver:DisplayName xml:lang="en">Affiliation type</resolver:DisplayName>
eduPersonScopedAffiliation:    <resolver:DisplayName xml:lang="en">Affiliation type (with institution)</resolver:DisplayName>
eduPersonEntitlement:          <resolver:DisplayName xml:lang="en">Entitlements</resolver:DisplayName>
eduPersonAssurance:            <resolver:DisplayName xml:lang="en">Identity assurance level</resolver:DisplayName>
auEduPersonSharedToken:        <resolver:DisplayName xml:lang="en">Shared token</resolver:DisplayName>
auEduPersonAffiliation         <resolver:DisplayName xml:lang="en">Affiliation type (Australian extensions)</resolver:DisplayName>


The best way to test an IdP is to try to log into a Service Provider in the federation - and the most convenient way for that is to access an attribute reflector - a page that displays all of the attributes received in the Shibboleth session. The AAF is running an attribute reflector in both AAF and AAF-TEST. Both reflectors are running on the VHO (Virtual Home Organization) server and are requesting all attributes available in the federation - hence, they work very well for testing all the attributes released by your IdP.

The attribute reflector URLs are:
An alternative tool for testing IdP is the Attribute Authority Command Line Interface client - For a given user TEST_USERNAME, invoke the tool with:

$SHIB_HOME/bin/ --principal $TEST_USERNAME --requester

  • The tool output is the whole set of attributes that would be released for this user to the given application (the AAF VHO in this case). If testing for another service, pass the entityId of the service in the --requester option.
Note that the tool may fail with: ClassNotFoundException: javax.servlet.ServletRequest. To remedy this, link the Tomcat servlet.jar library into $SHIB_HOME/lib (needs to be re-done after each rebuild of the Shibboleth IdP):
ln -s /usr/share/java/servlet.jar $SHIB_HOME/lib/


The installation of an Identity Provider into the Australian Access Federation is not be a difficult task but given the large number of steps currently involved there is a lot of scope for error. Debugging some of these errors can be very time consuming. We recommend that you follow this guide from start to finish and ensure all test points through out are successfully completed before move on.

The AAF strongly recommends that you deploy an Identity provider into the AAF Test Federation first to become familiar with the software and its configuration. Further we recommend that you maintain your Test IdP using it for upgrade testing and making it available as a test platform for service providers deploying services on behalf of your Organisation.

Finally, the AAF team is here to help, if you have any issues with regards to your IdP deployment please contact us at or search for solutions at the AAF Knowledge base.