Using the Shibboleth Windows Installer

Introduction

This is an abbreviated step-by-step of guide of the Shibboleth Windows installation guidance. Using the Shibboleth Windows installer will help your Identity Provider (IdP) server come online faster and for some, remain more sustainable. The Shibboleth Windows installer installs both a Jetty webserver and the Shibboleth IdP software with an empty base configuration to ensure proper operations. Once base install is completed, Canadian Access Federation (CAF)-specific settings can be added to the IdP.

 After performing these steps, you will have:

  • A minimally operating Identity Provider which you can then tailor to your environment
  • The ability to verify a sign-on using the admin/Hello built-in service with LDAP connectivity to your on-premises Active Directory

Prerequisite Steps

Note: JDK versions higher than 11.X do not include a Java script engine and therefore will not work.

  • Install an XML editor with syntax highlighting to reduce errors in XML editing. Free versions of Visual Studio Community edition are helpful or Notepad++.

Steps to Install Shibboleth IdP

  1. Follow steps for Shibboleth installer at: https://wiki.shibboleth.net/confluence/display/IDP4/WindowsInstallation
    Select the “Install Jetty and the “Configure for Active Directory” check boxes and complete the AD dialogue.
  2. In ldap.properties doublecheck the idp.authn.LDAP.XXX settings. These are site specific. Please see https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631612/LDAPAuthnConfiguration for details.
  3. Enable access to the IdP status page for http://<idp_name>/idp/status
    • Edit admin.properties and uncomment status block.
    • Edit access-control.xml and add IP range(s) to AccessByIPAddress entry for any IP range(s) you want to allow to access the status pages. By default access is only permitted by the local machine via the loopback address.
    • Restart the IdP
  4. Enable the HelloWorld configuration app

Note: To allow access to the app, you need to add your SubjectName that you sign in as into $idphome/conf/access-control.xml in the ‘AccessByAdminUser’ block.

  • Restart the IdP for it to take effect and visit the admin/hello site on your IdP.
  1. Prepare the IdP for large metadata aggregates by increasing the JVM maximum memory pool.
    • Increase the JVM maximum memory pool using this command:

C:\Program Files (x86)\Shibboleth\Procrun\shibd_idpw.exe

  • Click on the Java tab and set the “maximum memory pool” to 4096MB and click OK.

CAF Configuration

Configure CAF Metadata Feeds

To connect to the CAF metadata feeds:

  • Configure retrieval of the metadata aggregates on an hourly basis.
  • Verify the aggregates using the CAF signing key (caf_metadata_verify.crt).
  • Request CAF to trust your new instance of the IdP by emailing tickets@canarie.ca with your metadata.

To validate the aggregates, you need to have the CAF signing key on disk for the IdP to use. To do this, fetch the key from the CAF Operational url: https://caf-shib2ops.ca/CoreServices/caf_metadata_verify.crt and place it in the $idp_home/credentials/caf_metadata_verify.crt file for use in the metadata verification process.

Next, to establish trust between your IdP and CAF, edit metadata-providers.xml to add these references to the file:

<MetadataProvider id="URLMDCAFTestbed"        
        xsi:type="FileBackedHTTPMetadataProvider"
        xmlns="urn:mace:shibboleth:2.0:metadata"
        metadataURL="https://caf-shib2ops.ca/CoreServices/testbed/caf_test_fed_unsigned.xml"
        backingFile="%{idp.home}/metadata/caf_test_fed_unsigned.xml"
        maxRefreshDelay="PT1H">
</MetadataProvider>

<MetadataProvider id="URLMDCAF_Prod"
xsi:type="FileBackedHTTPMetadataProvider"
backingFile="%{idp.home}/metadata/caf_metadata_signed_sha256.xml"
metadataURL="https://caf-shib2ops.ca/CoreServices/caf_metadata_signed_sha256.xml"
failFastInitialization="false"
maxRefreshDelay="PT4H">
        <MetadataFilter xsi:type="SignatureValidation" certificateFile="%
{idp.home}/credentials/caf_metadata_verify.crt" />
        <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P30D"/>
        <MetadataFilter xsi:type="EntityRole" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
                  <RetainedRole>md:SPSSODescriptor</RetainedRole>
        </MetadataFilter>
</MetadataProvider>

<MetadataProvider id="URLMDCAF_eduGAIN_SP"
xsi:type="FileBackedHTTPMetadataProvider"backingFile="%
{idp.home}/metadata/caf_interfed_sp.xml"
metadataURL="https://caf-shib2ops.ca/CoreServices/caf_interfed_sp.xml"
failFastInitialization="false"
maxRefreshDelay="PT4H">
        <MetadataFilter xsi:type="SignatureValidation" certificateFile="%{idp.home}/credentials/caf_metadata_verify.crt" />
        <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P30D"/>
        <MetadataFilter xsi:type="EntityRole" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
                  <RetainedRole>md:SPSSODescriptor</RetainedRole>
        </MetadataFilter>
</MetadataProvider>


Hint: You can force a reload of the CAF test federation metadata by running this command:
C:\Program Files (x86)”\Shibboleth\IdP\bin\reload-metadata -id URLMDCAFTestbed
from a CMD window or from a browser location of:
https://127.0.0.1/idp/profile/admin/reload-metadata?id=URLMDCAFTestbed

Next, email tickets@canarie.ca with your new entityID and/or your metadata from $idp_home/metadata/idp-metadata.xml so that CANARIE can add it to the test federation. Once added, you can exercise another sign-on test with https://validator.caftest.canarie.ca which will allow you to verify your IdP with a federated service from end-to-end without needing to create your own federated service to test against.

Working with Attribute Release

The act of signing in and the function of adding (or ‘resolving’) attributes to an identity are considered two different operations. In other words, just because you’re able to sign in does not mean you have attributes.

Attributes in the latest version of the Shibboleth IdP are driven by the attribute registry engine. The home for this is in %{idp.home}/conf/attributes and uses default-rules.xml to signal which sets of files are used for directory attributes. If it’s missing, copy it from %{idp.home}/dist/conf/attributes directory.

A small default set of dynamic and static attributes are delivered with the base installation of the IdP and require customization to properly resolve from the appropriate source attribute(s) from your directory (AD/LDAP) to the attribute values for a person.

Technical details about attribute resolution can be found here: https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631517/AttributeFilterConfiguration

Progressing to More Advanced Configurations

Some sites may want to use Azure for their single sign-on (SSO) and multifactor authentication (MFA) provider. We recommend reviewing the Shibboleth Knowledge Base article for this more advanced configuration: https://shibboleth.atlassian.net/wiki/spaces/KB/pages/1467056889/Using+SAML+Proxying+in+the+Shibboleth+IdP+to+connect+with+Azure+AD