Installation and configuration of Shibboleth IdP v3 on Windows

Last Update: 26th September 2019

The UK federation support team has experience of installing and configuring the software, and we are continuing to develop documentation for our members. This page therefore contains some advice, pointers to the Shibboleth project documentation, and some UK federation-specific configuration information related to using the Shibboleth IdP v3 Windows MSI Installer. This guide assumes you are linking to a single Active Directory using LDAP for both authentication and as a source of attributes.

Please contact the UK federation helpdesk for further advice.

Note this page replaces the 'Shibboleth Installation and Configuration Guide' by Alan Coats of Burton and South Derbyshire College. We are grateful to Alan for his contribution to our documentation.

• IdP v3 Training
• Upgrading from v2
• New v3 deployments
• Preparation
• Installation
• Configuration
• Registering your Shibboleth v3 IdP
• Testing new IdP deployments
• Troubleshooting

Anyone interested in deploying the v3 IdP should start at the Shibboleth IdP v3 main page and read the system requirements and release notes.

IdP v3 Training

Jisc operate Shibboleth IdP v3 and Shibboleth SP v2 training courses. Please see the Jisc website for details:

Upgrading from v2

It's possible to upgrade a v2 deployment to v3. It is not recommended to upgrade a production v2 deployment in place, but you could clone a production v2 deployment and upgrade that. You should make sure that you follow all the post-upgrade tasks before moving to the configuration steps below.

The UK federation preferred method is to follow the FreshIdPv3 guide.

New v3 deployments

For a new deployment, you should first read the Installation page.

For a new Windows deployment most deployers should probably use the Windows installer, but please read the main Installation page before moving to the Windows installation page.

Preparation

1. Download a copy of Amazon Corretto
   • We recommend you download Corretto 11 which is only available for Windows 64-bit. If you are still running Windows 32-bit you will need Corretto 8, which is also available for Windows 64-bit. You may use the following direct links to the download page;
     • Recommended - Corretto 11 Download
       • Windows x64 - amazon-corretto-11.n.n.nn.n-windows-x64.msi
     • Alternative - Corretto 8 Download
       • Windows x64 - amazon-corretto-8.nnn.nn.n-windows-x64.msi
       • Windows x86 - amazon-corretto-8.nnn.nn.n-windows-x86.msi
   • You should inspect and verify the relevant checksum for the file you have downloaded. Amazon provide an MD5 checksum for this purpose.
     • You can use certutil -hashfile amazon-corretto-nn.n.n.nn.n-windows-x64.msi md5 to reveal the MD5 checksum (where nn.n.n.nn.n reflects the version number)
2. Download a copy of Shibboleth IdP for Windows from the Shibboleth Project IdP 3 Download page.
   • Choose the relevant version for your OS.
     • Recommended Windows 64-bit - shibboleth-identity-provider-3.n.n-x64.msi
     • Windows 32-bit - shibboleth-identity-provider-3.n.n-x86.msi
   • You should inspect and verify the relevant checksum for the file you have downloaded, Shibboleth provide corresponding checksum files e.g. shibboleth-identity-provider-3.n.n-x64.msi.sha256
     • You can use certutil -hashfile shibboleth-identity-provider-3.n.n-x64.msi sha256 to reveal the SHA256 checksum.
3. Create a user in 'Active Directory Users and Computers' for the Shibboleth IdP to search the your Active Directory with.
   • It should have the minimum level of privileges, so only a member of 'Domain Guests'
   • Under Properties, Account, it should have
     • 'User cannot change Password' ticked
     • 'Password never expires' ticked
     • 'User must change password at next logon' should be not be ticked
     • Account Expires: Never
   • Make a note of the username 'User login name' and password
4. Choose a DNS name and scope for your IdP
   • When picking a DNS name for your Shibboleth IdP, consider using a name that reflects the function such as idp.example.ac.uk rather than the software deployed such as shibboleth.example.ac.uk.
   • You will need to decide on a Scope for your IdP to use when using scoped attributes. In the majority of cases you will use your existing domain e.g. example.ac.uk.
   • Your entityID and Scope need to comply with our entityID policy and our Metadata Registration Practice Statement. In practice, this means ensuring that the DNS name used is for a domain registered to the relevant legal entity.
   • Ensure the appropriate DNS records are created in the external DNS and if required in any internal DNS for the DNS name of the IdP.
5. Firewall rules
   • Your IdP will require the following open from anywhere inbound to the IdP TCP port 443 (https) and TCP port 8443 (alt-https / IdP Backchannel) to the IdP.
   • The IdP will itself need access to TCP port 80 (http) for outbound for the UK federation metadata.
   • The IdP will need access to the appropriate ports for LDAP on the Active Directory Domain Controllers. It is likely to need one or more of the following (whilst configuring and testing you want to open all of these)
     • TCP port 389 for LDAP (plaintext and/or startTLS)
     • TCP port 636 for LDAPS (SSL/TLS)
     • TCP port 3268 for LDAP Domain Controller Global Catalogue (plaintext and/or startTLS)
     • TCP port 3269 for LDAPS Domain Controller Global Catalogue (SSL/TLS)

Installation

Install Java

1. If you downloaded the files above on another machine, then copy them to your Windows server.
2. Start by installing Java using the default settings.
3. Once Java is installed, then locate the install path for Java JDK using 'File Explorer', for example C:\Program Files\Amazon Corretto\jdknn.n.n_nn. The path you are looking for will have a bin folder within it.
4. Setup a JAVA_HOME environment variable to point to the Java installation
   • Within 'File Explorer', choose 'This PC' and right click 'Properties'
   • On the Left hand panel - Choose 'Advanced System Settings', at the bottom of the 'Advanced' Tab choose 'Environment *Variables'
   • Under 'System variables' choose 'New...'
     • Variable name: JAVA_HOME
     • Variable value: C:\Program Files\Amazon Corretto\jdknn.n.n_nn
   • Click OK

Run the Shibboleth IdP Windows installer

The Shibboleth IdP Windows installer, will install Shibboleth and the Jetty (web server/Java container)

1. Open the Shibboleth IdP installer file shibboleth-identity-provider-nnnnn-x64.msi
2. On the 'Welcome page', choose 'Next'
3. On the 'End-User License agreement', read and then choose 'I accept the terms in the License Agreement', choose 'Next'
4. On the 'Configure Shibboleth' screen
   1. Leave the install folder as-is.
   2. Make sure that 'Install Jetty' and 'Configure for Active Directory' are ticked.
   3. In 'Choose the DNS Name for this IdP' enter the Fully Qualified Domain Name (FQDN) of the IdP, this will be a registered DNS name, which you will need to ensure exists in DNS. An example would be idp.example.ac.uk
   4. In 'Scope' enter the Fully Qualified Domain Name of your organisation, this typically the same DNS name you use publicly for instance for email or web services.
5. Configure for Active Directory
   • In 'Specify the Active Directory Domain:' enter the FQDN of the Active Directory domain. Note: that whilst this can reflect a registered domain name e.g. example.ac.uk, it might be a non-registered domain like example.local
   • You may wish to tick 'Use Global Catalog'. The issues around using Standard LDAP vs Global Catalog are documented under LDAP Servers Issues
   • Enter the username and password, which have been generated under Preparation step 4.
6. You can now complete the installation under 'Ready to Install Shibboleth IdP v3', you may also be asked to complete 'User Account Control'
7. At this stage, the IdP is installed, but will require further configuration within the %{idp.home} folder, on Windows this is usually C:\Program Files(x86)\Shibboleth\IdP

Registering your Shibboleth v3 IdP

You will need to review and then submit the %{idp.home}/metadata/idp-metadata.xml along with the Information required for registration to the UK federation.

We will ask you to perform Certificate Verification, which you will need to do against each of the following files in the %{idp-home}/credentials/ folder idp-backchannel.crt, idp-signing.crt, idp-encryption.crt

See the UK federation Shibboleth IdP registration pages.

Configuration

General guidance

Typically the IdP installation directory is /opt/shibboleth-idp on Linux, or C:\Program Files\Shibboleth\IdP or C:\Program Files (x86)\Shibboleth\IdP on Windows. The installation directory is referred to in configuration files as %{idp.home}, and we refer to it as such here. Configuration files are located in the conf subdirectory of the IdP installation directory, that is to say %{idp.home}/conf.

Take configuration a step at a time; work on a particular configuration task, and test and modify your configuration until you have achieved the desired result. Check the idp-process.log and the container logs.

You can get more information by turning the logging level to DEBUG while you're configuring the IdP. To get details for many of the important processes in the IdP, set the following 3 parameters in %{idp.home}/conf/idp.properties to DEBUG:

    idp.loglevel.idp=DEBUG
    idp.loglevel.messages=DEBUG
    idp.loglevel.encryption=DEBUG

Reference documentation for logging configuration is available on the Shib wiki.

Generally we suggest the following order for configuring the IdP:

• user login, configuration usually in ldap.properties or jaas.config
• federation metadata
• register
• test
• attribute release in attribute-filter.xml and attribute-resolver.xml
• customise login page, configuration in views/login.vm, messages/messages.properties, views/login-error.vm, messages/error-messages.properties. Refer to Login page Customisation
• perform any tasks required for going into production

LDAP configuration

You will need to refine the LDAP configuration in ldap.properties to suit your Active Directory configuration. In the following we are assuming that sAMAccountName will be used as the username by users authenticating at the IdP. Please check the following are correct in relation to that:

 idp.authn.LDAP.userFilter= (sAMAccountName={user})
 idp.attribute.resolver.LDAP.searchFilter= (sAMAccountName=$resolutionContext.principal)

The following line idp.attribute.resolver.LDAP.returnAttributes will need to include cn and sAMAccountName, but it may include others, and will need to be updated when building your Attribute Resolver

 idp.attribute.resolver.LDAP.returnAttributes= cn,sAMAccountName

By default the Shibboleth IdP configuration assumes that you will be using a secure protocol either startTLS or SSL to connect to your Active Directory Domain Controller using LDAP. If you have this available then you should configure the public key certificate of the server(s) in %{idp.home}/credentials/ldap-server.crt, and configure idp.authn.LDAP.useStartTLS, idp.authn.LDAP.useStartTLS and idp.authn.LDAP.ldapURL accordingly.

Unfortunately, the default configuration of Active Directory does not have a certificate installed for startTLS or LDAP over SSL/TLS to be enabled, therefore many organisations maybe using unencrypted LDAP on port 389 so you may need to set the following lines in their ldap.properties

 idp.authn.LDAP.useStartTLS            = false
 idp.authn.LDAP.useSSL                 = false
 #idp.authn.LDAP.trustCertificates      = %{idp.home}/credentials/ldap-server.crt
 #idp.authn.LDAP.trustStore             = %{idp.home}/credentials/ldap-server.truststore

UK federation metadata configuration

Metadata services

The UK federation metadata is required for the IdP to validate UK federation service providers (SPs), and for the SPs to validate IdPs. It contains SAML metadata for all registered UK federation IdP and SP deployments. The UK federation provide two metadata services, which can be used interchangeably.

1. UK federation metadata query (MDQ)
2. UK federation metadata aggregate

Existing IdP and SP deployments will utilise the metadata aggregate, but we recommend that new IdP deployments utilise the metadata query (MDQ) service.

You should review the following sections of our MDQ documentation;

• What is MDQ?
• Benefits and risks

Metadata signing certificate

To secure against compromise, the UK federation metadata is signed using the UK federation's private key, and the corresponding public key must be used to verify the signature.

Note: that we use a different private key to sign the metadata aggregate and the metadata query service, therefore you will require the corresponding public key for the service that you choose to use, these are provided in the form of a self-signed X509 certificate.

The public key for the UK federation metadata query can be found at;

The public key for the UK federation metadata aggregate can be found at;

The certificate is required in the IdP configuration so that it can be used to verify the signature of the UK federation metadata. It needs to be downloaded and saved to the %{idp.home/credentials} directory.

However, as this certificate secures the entire UK Federation, you should not rely on it until you have checked its authenticity. To do this, you should verify the certificate's SHA-256 fingerprint, please refer to our page on Certificate Verification

To verify it you need to compare the resulting value with the correct fingerprint value, which can be obtained from the UK federation team. To guard against the possibility of this web site being compromised, you should contact them by telephone. Their phone number can be found on the UK federation helpdesk contact information page.

Configuration in metadata-providers.xml

After you have downloaded the UK federation signing certificate and verified its authenticity as described above, you configure the IdP to use the UK federation metadata by editing %{idp.home}/conf/metadata-providers.xml and adding a MetadataProvider element. The configuration example will depend on which Metadata service you plan to use

• Metadata Query service - Configuration example for Shibboleth IdP - Recommended and example provided here;

    <!-- UK federation MDQ service -->
    <MetadataProvider id="ukfMDQ" xsi:type="DynamicHTTPMetadataProvider">
        <!-- Verify the signature on the root element (i.e., the EntityDescriptor element) -->
        <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
                certificateFile="%{idp.home}/credentials/ukfederation-mdq.pem" />

        <!-- Require a validUntil XML attribute no more than 30 days into the future -->
        <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P30D" />

        <!-- The MetadataQueryProtocol element specifies the base URL for the query protocol -->
        <MetadataQueryProtocol>http://mdq.ukfederation.org.uk/</MetadataQueryProtocol>
    </MetadataProvider>

• Metadata aggregate service - Configuration example for Shibboleth IdP - Alternative

Attribute release

For the UK federation's attribute release recommendations generally, please see section 7 of the UK federation's Technical Recommendations for Participants. There are four attributes that the UK federation regards as "core" attributes: eduPersonScopedAffiliation, eduPersonTargetedID, eduPersonPrincipalName and eduPersonEntitlement. The most commonly used of these are eduPersonScopedAffiliation and eduPersonTargetedID, so we focus on those here.

Attribute filter

The attribute filter configuration determines which attributes are released to which service providers, and is configured in the conf/attribute-filter.xml file. Most service providers in the UK federation require the attribute eduPersonScopedAffiliation with an affiliation value equivalent to full membership, eg. member, staff or student. The affiliation values released for a given user must be determined on the basis of the user's genuine affiliation with your organisation from your organisation's point of view.

In general the UK federation considers there to be very little personally identifying information carried by either eduPersonScopedAffiliation or eduPersonTargetedID so considers it safe to release them to any SP; the following configuration snippet does just that. However, your organisation should do its own risk analysis in consultation with its data protection officer rather than taking our word for it.

Note that this snippet would release these two attributes to any SP with which the IdP successfully authenticated; this might be a UK federation SP, or an SP imported from another federation via eduGAIN interfederation, or another SP for which the IdP has the metadata configured one way or another. More sophisticated attribute filters are possible; please see the Shibboleth documentation.

  <!-- 
    The UK federation considers there to be very little personally identifying
    information carried by either eduPersonScopedAffiliation or eduPersonTargetedID
    so considers it safe to release them to any SP
  --> 
  <AttributeFilterPolicy id="releaseToAnyone">
     <PolicyRequirementRule xsi:type="ANY" />
     <AttributeRule permitAny="true" attributeID="eduPersonScopedAffiliation" />
     <AttributeRule permitAny="true" attributeID="eduPersonTargetedID" />
     <AttributeRule permitAny="true" attributeID="eduPersonTargetedID.old" />
  </AttributeFilterPolicy>

Also note If your previous attribute release policies had depended on your use of a metadata aggregate tagged with groupID="http://ukfederation.org.uk" or the equivalent for metadata aggregate files from other federations (see the Benefits and risks section of the MDQ page), you may find the method for tagging per-entity metadata as described in the Internet2 Metadata Distribution Service documentation useful.

Attribute resolver

The attribute resolver configuration specifies how attributes are retrieved or generated on behalf of your users. You will need to make sure that there is a DataConnector element set up in the file to connect to your LDAP, assuming the attributes for your users are stored in an LDAP, or attributes or groups from the LDAP can be used to generate attributes. A database might also be used to store attributes.

There is an example attribute-resolver.xml file in the conf directory containing an example LDAP DataConnector configuration, called attribute-resolver-ldap.xml. The DataConnector configuration will need to be modified for your local set-up.

Note the IdP only reads attribute-resolver.xml and not the attribute-resolver-ldap.xml file.

As discussed previously in LDAP Configuration the default configuration of Active Directory often only has unencrypted LDAP (TCP port 389 or 3268) enabled. If using the attribute-resolver-ldap.xml as a base, then you may need to remove or comment out the following within the DataConnector id="myLDAP".

 useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
 trustFile="%{idp.attribute.resolver.LDAP.trustCertificates}"

eduPersonScopedAffiliation

Assuming you have a DataConnector configuration with id="myLDAP", and the LDAP has been populated with the eduPersonAffiliation attribute for all your users, then you can use the eduPersonAffiliation attribute as the basis to generate eduPersonScopedAffiliation by means of the following snippet in attribute-resolver.xml:

  <AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="Scoped"
                        scope="%{idp.scope}">
        <InputDataConnector ref="myLDAP" attributeNames="eduPersonAffiliation"/>
        <AttributeEncoder xsi:type="SAML1ScopedString"
                         name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"
                         encodeType="false" />
        <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9"
                         friendlyName="eduPersonScopedAffiliation" encodeType="false" />
    </AttributeDefinition>

If the LDAP has not been populated with eduPersonAffiliation and it is not possible to arrange for it to be populated then you may need to use either a script or mapped attribute definition for eduPersonAffiliation, based on other attributes or groups in the LDAP. An example of this can be found on our Mapped Affiliation page.

Note: previously versions of this documentation may have link to a scripted example, we advise avoiding the user of Scripted Attributes within the IdP if possible.

eduPersonTargetedID

This attribute again depends on having a DataConnector configuration to connect to your LDAP. It also requires a ComputedId DataConnector.

Please note: the ComputedId was previously deprecated and the Shibboleth team recommended that it and the eduPersonTargetedID attribute are no longer used, and that a persistent ID should be released as a subject name identifier instead. However, there has since been a reversal of this and the connector is no longer deprecated and remains in place whilst new profiles for SAML subject identification (pairwise-id). Please see the ComputedId documentation and the subject name identifier documentation.

However, there are legacy SPs and non-Shibboleth SPs that may not be able to accept subject name identifiers in place of eduPersonTargetedID, so the UK federation recommends that UK federation IdP operators continue to release eduPersonTargetedID.

The UK federation advise is now to streamline your configuration with that for the pairwise-id, by setting many of the details (source attribute, salt) in saml-nameid.properties, and refering to these values in the DataConnector

Assuming your DataConnector configuration has id="myLDAP" then the ComputedId DataConnector might look like this:

  <DataConnector id="computed" xsi:type="ComputedId"
                            generatedAttributeID="computedId"
                            salt="%{idp.persistentId.salt}"
                	    algorithm="%{idp.persistentId.algorithm:SHA}"
                            encoding="%{idp.persistentId.encoding:BASE32}">
       <InputDataConnector ref="myLDAP" attributeNames="%{idp.persistentId.sourceAttribute}" />
   </DataConnector>

Within saml-nameid.properties, you then set the #idp.persistentId.sourceAttribute be that uid often used in OpenLDAP based directories. Whichever source attribute is chosen, it should not change over time.

    idp.persistentId.sourceAttribute=uid

In Active Directory, the users login name is often called sAMAccountName, although this has been known to change during the lifetime of a user's account. Depending on your system, either objectGUID or objectSid could be used.

The objectGUID is binary, so if it is to be used as the source attribute it should be declared as binary by adding this line to the LDAP DataConnector with id="myLDAP":

 <LDAPProperty name="java.naming.ldap.attributes.binary" value="objectGUID"/>

If you use objectSid, you'll need to add a similar element to the LDAP DataConnector.

Note that the order of the elements within the DataConnector matters. Please consult the LDAP Connector documentation on the Shibboleth wiki for the appropriate placing of the LDAPProperty.

The property idp.persistentId.salt can be set in saml-nameid.properties or possibly another properties file used for storing passwords, or the value can be included directly in the DataConnector. It is a random string of at least 16 bytes which you choose. It should be kept secret.

   idp.persistentId.salt=0123456789abcdef

If you are migrating from an earlier version of the software you should use the same source attribute and salt value as you used previously, and set idp.persistentId.encoding = BASE64 setting in saml-nameid.properties, which will ensure that the same values are generated for each of your users. This is necessary to retain access to personalisations saved on SPs that are keyed to eduPersonTargetedID values.

   idp.persistentId.encoding = BASE64

There are two forms of eduPersonTargetedID, a scoped form which we refer to here eduPersonTargetedID.old and the unscoped form which we refer to as eduPersonTargetedID. We suggest you release both forms, to allow for older SPs that do not recognise the unscoped form. Here are the attribute definitions for these two forms:

   <AttributeDefinition xsi:type="SAML2NameID" id="eduPersonTargetedID"
                        nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
        <InputDataConnector ref="computed" attributeNames="computedId"/>
        <AttributeEncoder xsi:type="SAML1XMLObject"
                          name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
        <AttributeEncoder xsi:type="SAML2XMLObject"
                          name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10"
                          friendlyName="eduPersonTargetedID" />
  </AttributeDefinition>

   <AttributeDefinition xsi:type="Scoped" id="eduPersonTargetedID.old"
                        scope="%{idp.scope}">
        <InputDataConnector ref="computed" attributeNames="computedId"/>
        <AttributeEncoder xsi:type="SAML1ScopedString"
                          name="urn:mace:dir:attribute-def:eduPersonTargetedID" />
  </AttributeDefinition>

Attribute Release Consent

The v3 IdP includes a flexible mechanism to allow people using your IdP to consent to the release of attributes about them. This is enabled by default for new installations and is a significant change to user interaction from the v2 IdP. See our documentation on Attribute Release Consent for details.

Consent example configuration

The following example configuration could be used, this ensures users only see the consent notification where personal information is being released, but for identifiers and affiliations they do see the notification.

Within in %{idp.home}/config/intercept/consent-intercept-config.xml, add <value> statements for eduPersonTargetedID.old eduPersonScopedAffiliation eduPersonAffiliation and eduPersonEntitlement, within the shibboleth.consent.attribute-release.BlacklistedAttributeID list. The section of configuration should now look like this;

    <util:list id="shibboleth.consent.attribute-release.BlacklistedAttributeIDs">
        <value>transientId</value>
        <value>persistentId</value>
        <value>eduPersonTargetedID</value>
        <value>eduPersonTargetedID.old</value>
        <value>eduPersonScopedAffiliation</value>
        <value>eduPersonAffiliation</value>
        <value>eduPersonEntitlement</value>
    </util:list>

Obtaining and installing the browser facing SSL certificate.

By default the Windows IdP generates a PKCS12 file for the browser facing SSL certificate called C:\Program Files(x86)\Shibboleth\IdP\credentials\idp-userfacing.p12. It is configured into Jetty in %{idp-home}/jetty-base/start.d/idp.ini, using the options jetty.browser.keystore.path=, jetty.browser.keystore.password=, and jetty.browser.keystore.type=. Whilst the default is a PKCS12 type, it can also use a JKS (Java Keystore) type.

Important notes for Jetty as part of the Windows installer

• Do not accidentally adjust the similarly named 'jetty.backchannel.keystore' options, this should not need to be changed for a new deployment.
• You should only need to modify %{idp-home}/jetty-base/start.d/idp.ini, it should not be required to modify other aspects of the Jetty installation, or configure certificate information elsewhere.

You will need to install an SSL certificate from a relevant certificate authority for your IdPs browser facing interface, if you have one already then you can configure it as described above. If you don't have one, or it is not in the either a PKCS12 or JKS format, then you will need to complete that.

We have also provided guides on creating the browser facing certificate you only need to follow one of these;

• Browser facing certificate using the Certificate snap-in in Windows - Recommended for Windows deployers
• Browser facing certificate using Java keytool which will be suitable for the IdP on all platforms (Windows and Linux)
• Getting the Browser-Facing Certificate will be suitable for IdP and SP on Linux, but also worth reviewing if you would like some more detail on the process.

Login page customisation

The login page can be customised in a number of ways, this section of our guide focuses on completing the minor changes which should be suitable for most institutions.

• Place an appropriate logo for your organisation in the %{idp-home}/static folder, this will be added to below idp.logo replacing 'logo.jpg'
• Add appropriate values %{idp-home}/messages/messages.properties

 idp.title = Example College Login
 idp.url.helpdesk = https://www.example.ac.uk/it/helpdesk
 idp.url.password.reset = https://www.example.ac.uk/it/password
 idp.logo = ../../logo.jpg
 idp.logo.alt-text = Example College Logo
 idp.logo.target.url = https://www.example.ac.uk
 idp.footer = © Example College

If further customisation of the login page is required refer to PasswordAuthnConfiguration. You will need to alter files such as messages/error-messages.properties, views/login.vm, and views/login-error.vm.

Testing new IdP deployments

Once you have registered your IdP, you can test your IdP configuration using this UK federation test service provider:

The index page contains a number of links, which invoke different versions of the Discovery Service. The links marked as "full" have a list of all federation IdPs, including those that have been registered as hidden or invisible. If you click one of these links and select your IdP from the WAYF or DS page and successfully authenticate, you should see a list of environment variables, some of which contain the values of attributes released by the IdP; this allows you to test attribute generation and release as well as simple authentication.

WAYF links use the federation WAYF and will invoke a SAML1 session, which produces two displayed assertions – one for the authentication, one for the attributes. DS links use the federation Discovery Service and may invoke a SAML2 session, which produces a single displayed assertion.

If you are testing a Shibboleth IdP, and you have trouble authenticating or releasing attributes, then ensure your log levels are turned up to DEBUG before re-testing, and check the logs; the idp-process.log is generally the most informative. If nothing is being written to the Shibboleth logs then check the Tomcat or Jetty logs; it is advisable to keep checking the Tomcat or Jetty logs anyway during the earlier stages of the installation.

You should not attempt to gain access to any live service until you have verified, by the use of the test page noted above, that your IdP is properly configured and releasing attributes correctly.

Troubleshooting the Windows IdP

1. Check that service is running

• The Shibboleth IdP on Windows is controlled using the shibd_idpw.exe which can be found in C:\Program Files (x86)\Shibboleth\ProcRun, this is registered in Windows as a service, so also available via 'Services' where it is listed as 'Shibboleth 3 IdP daemon'
• If you have made changed to your IdP configuration you should Restart the IdP using this
• Check that the 'Status' of the service is 'Running' and has a start type of 'Automatic'

2. From a command prompt you can use the 'status.bat' script to check that your IdP is running.

 "C:\Program Files (x86)\shibboleth\idp\bin\status.bat"

Assuming the script runs successfully, then you should see some 'Operating Environment Information' and some 'Identity Provider Information'.