You MUST have completed the requirements checklist before continuing installation. Environmental preparation is critical to a successful outcome. 


TABLE OF CONTENTS


Actions undertaken during installation

The installation process will:

  • Optionally perform a yum -y update (system wide package upgrade). Please note that the installer uses yum or apt-get for the installation of all system components (except Jetty and Shibboleth IdP).

  • Install all required dependencies (git, ansible, mariadb etc). With the previous step in mind, bootstrap will always use the latest versions of these packages.

  • Create self signed keys for Jetty. These are for initial testing of the IdP and are replaced when further customising the Shibboleth IdP

  • Install Jetty with Shibboleth IdP. Jetty runs on port 443 and optionally ports 80 and 8443 and creates the Shibboleth IdP web app context /idp.

  • Install a MariaDB instance. A database is created (name: idp_db, user: idp_admin) with these schemas populated.

  • Installs chrony for time synchronisation.

  • Opens local firewall ports 443 and optionally ports 80 and 8443

  • Optionally configures the IdP for integration with eduGAIN

  • Optionally configures the IdP to enable various REFEDS specifications.


Event logging

The installer provides a detailed set of information indicating the steps it has undertaken on your server. You MAY disregard this output if the process completes successfully.


For future review all installer output is logged to


/opt/shibboleth-idp5-installer/activity.log

Preparing the bootstrap-v5.ini file

For new installations download the bootstrap-v5.ini file as follows;


curl https://raw.githubusercontent.com/ausaccessfed/shibboleth-idp5-installer/main/bootstrap-v5.ini> bootstrap-v5.ini


Edit the bootstrap-v5.ini file; 


A description of each field is provided here and in the downloaded version of bootstrap-v5.ini


vi bootstrap-v5.ini


  • You MUST review, configure and uncomment each field listed in the [main] section


  • If you have LDAP details you SHOULD also configure the [ldap] section 

You MAY further configure LDAP connection details, including TLS if required, after bootstrap has completed.      
  • Review the [logging, policy and advanced] section. Please ensure that you understand the implications of making any changes to fields in these sections.  


Running the installer

Download and prepare the bootstrap-v4.sh for execution using the following command;


curl https://raw.githubusercontent.com/ausaccessfed/shibboleth-idp5-installer/main/bootstrap-v5.sh > bootstrap-v5.sh && chmod u+x bootstrap-v5.sh


Ensure that bootstrap-v5.ini is in the same directory used to download the bootstrap-v5.sh script.


Run the following command as root;


./bootstrap-v5.sh

 

The bootstrap-v5 process will now install and configure your server to operate as a Shibboleth IdP. 


Errors during installation

If an error occurs, the logs prior to installer termination MUST be reviewed to understand the underpinning cause.


Generally the installer SHOULD be executed once.


After the initial execution you’ll receive an error if you try to run bootstrap.sh again.


You MUST NOT re-run bootstrap-v5.sh if the installation process completed but you made a simple mistake. e.g.

  • Mistyped config in the [main], [ldap], [logging], [policy] or [advanced] sections


If you force bootstrap-v5.sh to run again once initial installation has completed the action MAY be destructive.

In this scenario you should continue with federation registration as documented below and then make any configuration changes necessary as documented within the customisation stage following completion of the installation stage as documented below.


Reasons to re-run the installer

Common Errors

OSErrorResolutionHow to continue
All

The script indicates you did not provide all required configuration options before your initial execution

Complete all required settings in the bootstrap-v5.ini file.Re-run the bootstrap-v5.sh script. At this point the installer has not created its lock file.
AllAnsible version < 2.14Upgrade to the latest version of Ansible.Re-run the bootstrap-v5.sh script. At this point the installer has not created its lock file.


Allowing the installer to run again

In general you will never need to re-run the bootstrap-v5.sh script after it has completed creating the /opt/shibboleth-v5-installer directory. You should use the deploy or upgrade scripts instead.


If you must re-run bootstrap-v5.sh then you remove the lock file first. Note this will overwrite any previous installations.


rm /root/.lock-idp-bootstrap-v5 && ./bootstrap-v5.sh

The bootstrap-v5 process will now start over and attempt to install and configure your server to operate as a Shibboleth IdP.


When Bootstrap-v5.sh completes

When the scripts completes the mariadb, jetty and the IdP should be running. The IdP probably will not be able to authenticate and there may be some errors in the Shibboleth log file /var/log/shibboleth-idp/idp-warn.log. This is a good start but indicates that additional configuration is required.


Initial testing

On completion of the initial installation there are a number of tests that can be performed to verify the IdP is working in it's off-the-self state.


TestProcedure / CommandRecovery
The IdP is runningCheck that two java process related to the IdP are running.

$ ps ax | grep jetty

Two java process should be listed. The first will begin with
   /usr/bin/java -server -Djetty.home=...,
 the second will be much longer and include
 -Didp.home=/opt/shibboleth/shibboleth-idp/shibboleth-idp-5.

If these processes are not present on your system the IdP has not successfully started.		Check the jetty logs for errors, these can be found in /var/log/jetty.

These logs may provide an indicator as to why the IdP has not started.
LDAP Connection
The IdP will start even if the connection to your LDAP or Active directory service failed. If you are using an LDAPS or Start TLS connection to your directory, the IdP will start but will not function at this point. 


Some test below will fail if there is no connection to your directory server.

You need to add your LDAP certificate to the configuration. For migrations this occurs in when Completing IdP V4 migration to V5. For new installations in the Completing IdP V5 Installation guide.
Check the IdP logsThe IdP writes its four log files into the directory /var/log/shibboleth-idp. It may take a few minutes for the log files to appear the first time the IdP starts.

Check idp-warn.log for any errors. This should only contain two Deprecation warnings that can be ignored.

Check idp-process.log from any ERRORS and and verify the Servlet has started. You should find the following content near the end of the file.

... No upgrade available from 5.1.2
... Version 5.1.2 is current		Review each ERROR to determine its cause. The configuration file and approximate line number of a configuration problem will generally be shown.

In some cases you will need to check the Jetty logs to find additional information about the error.


Ports are openYou may need to install net-tools to use the netstat commad.

Use following command to verify the following are open and are owned be the IdPs java process;

    netstat -anp | grep java

Port 443 listening and accepting connections from everywhere
Port 80 listening and only accepting connections from localhost

Only if you have enabled the back channel, verify the following as well;
Port 8443 listening and accepting connections from everywhere 		If any of these ports are not it may be another process has claimed the ports. Use netstat to verify. Also check the Jetty logs for clues.
Check Shibboleth modules are enabledUse the following command to verify the modules listed below are enabled;

/opt/shibboleth/shibboleth-idp/current/bin/module.sh

Enabled modules;
    idp.Core
idp.CommandLine
idp.EditWebApp
idp.authn.Password
idp.admin.Hello
    idp.intercept.Consent		Contact AAF Support.
Accessing the IdPThe IdP server should be responding the incoming requests. A web browser is simplest way to perform these tests but curl or wget will work.

The name of you IdP server should be the same as the value you supplied in the HOST_NAME value in bootstrap-v4.ini.

The IdP should NOT be listening on port 80.
http://[HOST_NAME]

The IdP should be listening on port 443. Attempting to access the root level of the IdP will redirect you to https://example.edu/ [Note: You will change this address later in the configuration].
https://[HOST_NAME]

Using the new Hello World feature introduced at version 4.1. It should show the default login page. You can try entering your credentials and one of two outcomes will occur;
1. Successful login and you receive an Access Denied message.
You need to configure the AccessByAdminUser adding your username to use. You will receive a list of your attributes as an Admin User.
2. Successful login and you receive an Uncaught Exception error message. 
This is caused be a requirement of the auEduPersonSharedToken generator. It requires the entityID of the IdP to be passed to it when generated a shared token for a user. Hello world does not provide this value. If the user already has a shared token it will be returned.
https://[HOST_NAME]/idp/profile/admin/hello
Verify the IdP is accessible to the system you are testing from.

If you are upgrading you may need to all an entry to your local hosts file so your browser goes to the new IdP.
Retrieving Attributes
Use the aacli tool to verify initial attribute retrieval is working correctly. As root execute the following commands

cd /opt/shibboleth/shibboleth-idp/current/bin
./aacli -n [username] -r https://validator.[test.]aaf.edu.au/shibboleth

The output should be some JSON with an attributes section shows all of the attributes that have been retrieved for the specified user.
Ensure the connection to your directory is working. This test will not produce any attributes if the LDAP connection is not available.



Completing the installation

New installations

For new installations you need to complete to following steps which are detailed in the Completing IdP V5 Installation guide.

  • Registration with the federation
  • Configure LDAP connectivity
  • Customisation of your IdP
  • Testing your new IdP


Upgrading from IdP V4

For migrations from IdP v4 you need to complete the following steps that are detailed in Completing IdP V4 migration to V5 guide.

  • Resolving Attributes
  • Back channel certificates
  • Bi-Lateral Services
  • Customisation of your IdP
  • Testing your migrated IdP