The following commands MUST be executed as the root user. Start the process from /root.

1. Run the command:

   curl https://raw.githubusercontent.com/spgreen/shibboleth-idp-installer/\
   SGAF-Implementation/bootstrap.sh > bootstrap.sh && chmod u+x bootstrap.sh
   

2. Edit the bootstrap file:

   vim bootstrap.sh
   

• You MUST review, configure and uncomment each field listed in the “MANDATORY SECTION”
• If you have LDAP details you SHOULD also configure the “OPTIONAL SECTION”.

You MAY further configure LDAP connection details, including TLS if required, after bootstrap has completed.

3. Run the command:

   ./bootstrap.sh
   

The bootstrap process will now 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.sh if the installation process completed but you made a simple mistake. e.g.

• Mistyped config in the MANDATORY SECTION
• Mistyped config in the OPTIONAL SECTION

If you force bootstrap.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

You MUST NOT re-run bootstrap.sh, unless:

• The script indicates you did not provide all required configuration options before your initial execution
• The underpinning Ansible based installation process fails during installation

If the latter scenario occurs you MUST correct the root cause of the error before attempting to continue.

Allowing the installer to run again

If you’ve met all conditions, run the installer again:

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

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

Once completed the bootstrap process will output information specific to your installation which you will use to register your Shibboleth IdP with the federation. Please follow the onscreen information in order to complete the registration process.

Important: At section 3 of the registration process, SAML Configuration, you will need to manually enter the Artifact Resolution Endpoint + Index and the Attribute Resolution Endpoint if you use the Easy registration using defaults. Please Note: The ECP Endpoint is not required.
In the following examples, please replace idp.example.edu.sg with the IdP's Fully Qualified Domain Name (FQDN) during the registration process.

Artifact Resolution Endpoint: https://idp.example.edu.sg:8443/idp/profile/SAML2/SOAP/ArtifactResolution
Artifact Resolution Endpoint Index: 2
Attribute Resolution Endpoint: https://idp.example.edu.sg:8443/idp/profile/SAML2/SOAP/AttributeQuery

After completing the registration process, you will receive an email from the federation indicating your Shibboleth IdP is pending approval by the SGAF. The approval process can take up to 24 hours.

For further assistance please contact technical-support@singaren.net.sg

1. Configure LDAP connectivity

If you provided basic LDAP details to the bootstrap process you MAY skip this section.
If you:

• Wish to use TLS connections; or

• Have an advanced deployment scenario for your directory infrastructure:

  1. Locate local configuration files
     You MUST make any changes you require below within:

     /opt/shibboleth-idp-installer/repository/assets/<HOST_NAME>/idp/conf
     

     and NOT

     /opt/shibboleth-idp/conf
     

  which is the default path documented in external resources. All specific config file names, e.g. ldap.properties, remain the same.

  2. Configure LDAP options

     Please see the Shibboleth IdP LDAP documentation for a description of all available LDAP options. Undertake configuration changes or certificate additions to the server as necessary.

  3. Apply Changes

     After changing LDAP configuration you MUST run the command:

     /opt/shibboleth-idp-installer/repository/update_idp.sh
     

  This will merge the changes as required and reload the Shibboleth IdP to apply them.

2. Receive Shibboleth IdP Approval
   You will receive a second email following approval by the SGAF.

   Please wait for at least 4 hours after receiving this email, so backend processes and data sync is completed before undertaking the instructions it contains to gain administrative rights over your Shibboleth IdP within SGAF management tools.

3. Add Backchannel certificates

The final installation step involves providing your backchannel certificates to the SGAF management tool, Federation Registry.

Access your Shibboleth IdP record within Federation Registry and navigate to SAML -> Certificates

1. Add the contents of /opt/shibboleth/shibboleth-idp/current/credentials/idp-backchannel.crt as a certificate for signing.
2. Add the contents of /opt/shibboleth/shibboleth-idp/current/credentials/idp-encryption.crt as an encryption certificate.

From the configuration directory you can make changes to customise the following areas as appropriate for your environment:

• Apache certificates and configuration
• IdP configuration (xml/properties)
• IdP branding (velocity templates, css and images).

Customisations recommended by SingAREN for operating a production Shibboleth IdP

Here are some of the areas you should customise when preparing a Shibboleth IdP for a production environment:

• The Shibboleth IdP MUST use valid certificates, verified by a widely trusted CA, for your Apache webserver
• The use of EV certificates is RECOMMENDED
• Ensure all attributes on the SGAF Attribute Validator are shown with green ticks to indicate successful release
• Branding should be consistent with your organisations corporate branding, images, logos, colour schems, etc
• Corporate links, eg Accessibility, Copyright, Disclaimers, Privacy, etc should be consistent with the corporate site
• The name known by your users for their username / password should be consistently used on the IdP login page
• Links to a corporate terms of use or similar page
• Link provided to recover lost password, manage passwords or other credentials, etc
• Display of the SingAREN logo and links to the SGAF information such as the service catalogue
• Guidance for users about effectively logging out, particularly when using publicly accessible computers
• Minimise and preferably eliminate the use of technical jargon
• Showing the name of the service the user is logging into, possibly the logo as well if it is available

Actions undertaken during an update
The update process will perform the following:

1. Update underlying operating system packages to ensure any security issues are addressed
2. Apply any configuration changes made within the assets directory for: * Shibboleth IdP * Jetty * Apache HTTPD
3. RESTART all dependent processes.

You MUST have a tested rollback plan in place before running an update to ensure any unanticipated changes can be reversed.

You MUST have a tested rollback plan in place before running an update to ensure any unanticipated changes can be reversed.
Executing the update

To update your Shibboleth IdP run the command:

/opt/shibboleth-idp-installer/repository/update_idp.sh

In order to upgrade your versions to the latest vetted releases you need to add the -u switch to the update_idp.sh command:

/opt/shibboleth-idp-installer/repository/update_idp.sh -u

By supplying the -u switch the following occurs in addition to the normal update process:

1. Upgrade to the most recent version of the installer:
   • The update will be retrieved from: https://github.com/spgreen/shibboleth-idp-installer.git
   • It will be based on the most recent production release
2. Upgrade, if necessary, to the most recently vetted versions of:
   • Shibboleth IdP
   • Jetty

• Apply configuration changes to the IdP

  # /opt/shibboleth-idp-installer/repository/update_idp
  

• Restart the IdP (Jetty)

  # systemctl restart idp
  

• Restart apache

  # systemctl restart httpd
  

• Restart ntpd

  # systemctl restart ntpd
  

• Restart firewall

  # systemctl restart firewalld
  

The structure of the filesystem after a successful install is as follows:

    /opt
    ├── jetty
    │   └── jetty-distribution-9.2.10.v20150310   # Jetty installation
    ├── keypairs                                  # TLS assets for Apache
    │   ├── intermediate.crt
    │   ├── server.crt
    │   └── server.key
    ├── shibboleth
    │   ├── jetty                                 # Jetty base for Shib IdP
    │   ├── shibboleth-idp
    │   │   └── shibboleth-idp-3.1.1              # Shibboleth instance
    │   └── shibboleth-src                        # Shib Installation files
    │       ├── install-3.1.1.exp
    │       ├── install-3.1.1.sh
    │       └── shibboleth-identity-provider-3.1.1
    └── shibboleth-idp-installer	
        ├── repository                            #Holds conf and source code
        └── build                                 #Installer work directory 
    /var
    └── log
        ├── shibboleth                            #Shibb specific logs
        ├── httpd                                 #Apache logs
        └── jetty                                 #Jetty base logs

The IdP installer provides no backup or monitoring of the platform.
Deployers SHOULD:

Undertake regular backups of:

• The entire VM
• The local mariadb instance
• Key directories, including, but not limited to:
  1. /opt/shibboleth-idp-installer
  2. /opt/keypairs
  3. /opt/shibboleth
  4. /etc/httpd
• Monitor service availability
• Monitor platform concerns, such as disk space and load averages

Future Customisations

You can return to the customisation stage in the future to make further changes.

The installer uses software called Ansible a goal-oriented configuration management tool that is secure and agentless. An AAF GitHub repository holds the configuration information. This is used by Ansible to reliably and repeatably configure the IdP avoiding the potential failures from scripting, script-based systems or manually management. All that is needed is your local information. The installer passes this to Ansible which then installs or upgrades your IdP. SingAREN has modified the necessary files within the AAF GitHub repository to allow Shibboleth IdP v3 installation specifically for the SGAF environment.

As new versions of the Shibboleth IdP or any of the underpinning software become available the AAF creates a new branch in the GitHub repository and apply changes. All changes go through a though testing and review process before being committed to the repository. On completion of testing a new version of the installer is released.
When a new installer is released notifications will be announced via various channels. SingAREN will modify the updates accordingly for the SGAF environment.
On receipt of such a notification it’s time to plan for your local IdP upgrades. First in your test environment to be sure there are no issues and local configuration options continue to work. Next, with approval of your change board upgrade your production IdP.

The IdP Installer is a tool to assist you maintain your IdP. If the tool is not meeting your requirements or you would like to see some improvements we welcome your feedback.

If there are any issues experienced when running the tool the SGAF technical support will be happy to assist.