Installation and configuration of Shibboleth IdP v3 on Windows

Last Update: 16th April 2018

This guide is aimed at those using the Shibboleth IdP v3 Windows MSI Installer. If you are setting up Shibboleth IdP manually on Windows or on another platform e.g. Linux, then we are currently updating the relevant guide Installation and configuration of Shibboleth IdP v3 software

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.

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.


  1. Download a copy of Oracle Java 8 (1.8) SE JDK for Windows from the Oracle website
    • Choose JDK Download, and download the relevant version for your OS.
      • Windows 64-bit - jdk-nnnnn-windows-x64.exe (where nnnn reflects the version number).
      • Windows 32-bit - jdk-nnnnn-windows-i586.exe (where nnnn reflects the version number).
    • You should inspect and verify the relevant checksum for the file you have downloaded. Oracle provide a link on the download page for the 'JDK nnnnn checksum'.
      • You can use certutil -hashfile jdk-nnnnn-windows-x64.exe sha256 to reveal the SHA256 checksum.
    • Whilst JRE may work, only JDK is supported according the the IdP3 System Requirements.
  2. For Java versions earlier than 1.8u161, then download a copy of Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for JDK/JRE 8 from the Oracle website
    • This will be a single download named
    • JCE is required for some Service Providers (SPs) that may need to use AES with 256-bit keys, and is suggested in IdP3 Installation
    • We cannot find a checksum on the Oracle website for the above, so please complete your own checks.
  3. Download a copy of Shibboleth IdP for Windows from the Shibboleth Project
    • Choose the relevant version for your OS.
      • Windows 64-bit - shibboleth-identity-provider-nnnnn-x64.msi
      • Windows 32-bit - shibboleth-identity-provider-nnnnn-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-nnnnn-x64.msi.sha256
      • You can use certutil -hashfile shibboleth-identity-provider-nnnnn-x64.msi sha256 to reveal the SHA256 checksum.
  4. 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
  5. 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 rather than the software deployed such as
    • 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.
    • 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.
  6. 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)


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 JRE using 'File Explorer', for example C:\Program Files\Java\jdknnnn_nnn\jre. The path you are looking for will have a bin folder within it.
  4. For Java versions earlier than 1.8u161, take the and extract the individual local_policy.jar and US_export_policy.jar files to the C:\Program Files\Java\jdknnnn_nnn\jre\lib\security folder, this will overwrite two existing files of the same names.
  5. 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\Java\jdknnnn_nnn\jre
  • 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
    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., 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 again each of the following files in the %{idp-home}/credentials/ folder idp-backchannel.crt, idp-signing.crt, idp-encryption.crt

See the UK federation v3 IdP registration pages.


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/logback.xml to DEBUG:

    <!-- Logging level shortcuts. -->
    <variable name="idp.loglevel.idp" value="DEBUG" /> <!-- Default INFO -->
    <variable name="idp.loglevel.ldap" value="WARN" />
    <variable name="idp.loglevel.messages" value="DEBUG" /> <!-- Default INFO -->
    <variable name="idp.loglevel.encryption" value="DEBUG" /> <!-- Default INFO -->
    <variable name="idp.loglevel.opensaml" value="INFO" />
    <variable name="idp.loglevel.props" value="INFO" />

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 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/, views/login-error.vm, messages/ Refer to Login page Customisation
  • perform any tasks required for going into production

LDAP configuration

You will need to further refine the LDAP configuration within in 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

 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

By configuring the above with both idp.authn.LDAP.useStartTLS and idp.authn.LDAP.useSSL set to false and no idp.authn.LDAP.trustCertificates or idp.authn.LDAP.trustStore, then your Shibboleth IdP is using an unencrypted protocol between the IdP and the LDAP Server (Active Directory Domain Controllers).

It is strongly recommended that you configure your LDAP Server to support either StartTLS or SSL/TLS LDAP over SSL/TLS with a Certificate, and re-configure your Shibboleth IdP accordingly.

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;

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.

You might like to test that you can authenticate at your IdP and communicate with our test SP, before moving onto Attribute Release and Filter. Please restart the Shibboleth IdP service, refer to the Troubleshooting section below. Then conduct a test and then return to the Attribute Release section.

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.

  <AttributeFilterPolicy id="releaseToAnyone">
     <PolicyRequirementRule xsi:type="ANY" />
     <AttributeRule attributeID="eduPersonScopedAffiliation">
         <PermitValueRule xsi:type="ANY" />
     <AttributeRule attributeID="eduPersonTargetedID">
         <PermitValueRule xsi:type="ANY" />
     <AttributeRule attributeID="eduPersonTargetedID.old">
         <PermitValueRule xsi:type="ANY" />

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.

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".


It is strongly recommended that you configure your LDAP Server to support either StartTLS or SSL/TLS LDAP over SSL/TLS with a Certificate, and re-configure your Shibboleth IdP accordingly.


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}" sourceAttributeID="eduPersonAffiliation">
        <Dependency ref="myLDAP" />
        <AttributeEncoder xsi:type="SAML1ScopedString"
                         encodeType="false" />
        <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oid:"
                         friendlyName="eduPersonScopedAffiliation" encodeType="false" />

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 script an attribute definition for eduPersonAffiliation, based on other attributes or groups in the LDAP. An example of this can be found on our Scripted Affiliation page


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 are still emerging. 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. Essentially the UK federation's attribute recommendations have not changed.

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

  <DataConnector xsi:type="ComputedId"
        <Dependency ref="myLDAP" />

In this example, we've used the source attribute uid which is often used in linux systems to record the users' login names. Whichever source attribute is chosen, it should not change over time.

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. Here is an example ComputedId resolver:DataConnector that uses the objectGUID:

  <DataConnector xsi:type="ComputedId"
        <Dependency ref="myLDAP" />

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.computed.salt can be set in 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.


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, 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.

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"
        <Dependency ref="computedID" />
        <AttributeEncoder xsi:type="SAML1XMLObject"
                          name="urn:oid:" />
        <AttributeEncoder xsi:type="SAML2XMLObject"
                          friendlyName="eduPersonTargetedID" />

   <AttributeDefinition xsi:type="Scoped" id="eduPersonTargetedID.old"
        <Dependency ref="computedID" />
        <AttributeEncoder xsi:type="SAML1ScopedString"
                          name="urn:mace:dir:attribute-def:eduPersonTargetedID" />

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.

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;

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/
 idp.title = Example College Login
 idp.url.helpdesk =
 idp.url.password.reset =
 idp.logo = ../../logo.jpg
 idp.logo.alt-text = Example College Logo =
 idp.footer = &copy; Example College

If further customisation of the login page is required refer to PasswordAuthnConfiguration. You will need to alter files such as messages/, 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'.