Description This article describes additional configurations to be added to a Shibboleth Service Provider. Contents Attributes Shibboleth Attribute Map Shibboleth Sessions Handler Further Reading Attributes The attribute map and attribute extractor function in the Shibboleth Service Provider enables you to read attributes from an authenticated users' session and use those for the purpose of access restriction, profile population, and general user experience. Shibboleth Attribute Map By default, all members of the CSU Federation receive a large list of attributes from authenticated users. The shipped attribute-map file that comes with the Shibboleth installation does not automatically capture all of these attributes. To learn more about the attributes provided to CSU Federation members, review the file attached to this article (attribute-map.xml), and follow these instructions to update your configuration. In your Shibboleth Service Provider configuration, navigate to the location of your attribute-map.xml file Windows/IIS: C:\opt\shibboleth-sp\etc\shibboleth\attribute-map.xml Linux: /etc/shibboleth/attribute-map.xml Back up the current file Replace the attribute-map.xml file with the one attached to this article. Restart shibboleth to enable the updated file. Windows/IIS: Services > Shibboleth Daemon > Right-click > Restart Linux: systemctl restart shibd Review the Shibboleth XMLAttributeExtractor Guide on how to extract users' attributes from their assertion Shibboleth Sessions Handler The Shibboleth Sessions Handler element displays data about the authenticated user's session, including passed attributes, to a web-page used for debugging. By default, the configuration masks these values (indicated with showAttributeValues="false") in this web page: Configuration in shibboleth2.xml (All handler elements contained in Sessions element): Windows/IIS: C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml Linux: /etc/shibboleth/shibboleth2.xml Published location: (Valid authentication required first): /Shibboleth.sso/Session Example page display with values masked: With a completed attribute map and the Sessions Attribute values displayed, the attribute-values will also populate in the Sessions page: Attribute Values enabled Example page display with values displayed Further reading Shibboleth Service Provider - Shibboleth Resources

Description This article describes additional features that can be added to enhance your Shibboleth Service Provider. Contents Discovery Feed IdP Metadata DiscoFeed Handler discovery.html files SSO tag Duo MFA Further Reading Discovery Feed Service Providers (SPs) that connect to multiple Identity Providers (IdPs) for authentication can use a Discovery Feed to provide a simplified option for users to select their authentication endpoint. Many members of the InCommon Federation host a single website with a discovery service that allows users to select their institution, be redirected to their host institution's Identity Provider, and authenticate into the application. The scope of the CSU System only includes two Identity Providers: Production and Test; a discovery feed can be configured to authenticate through both instances for applications that need to be able to (such as systems that serve to test IdP functionality). EduCause website's Discovery Service IdP Metadata The Shibboleth SP needs to have a MetadataProvider element for each IdP that should appear in the Discovery Feed In the application server, open shibboleth2.xml in a text editor IIS: C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml Linux: /etc/shibboleth/shibboleth2.xml Include MetadataProvider elements for each required IdP https://shibidp.colostate.edu/idp/shibboleth Save Do not yet restart shibboleth service DiscoFeed Handler In shibboleth2.xml, locate the Handler elements (should be near bottom of file) Confirm the DiscoveryFeed Handler is listed (not commented-out) Save Do not yet restart shibboleth service discovery.html files Attached to this article is a zipped folder discovery.zip. Download this .zip and transfer it to your web server's web home (e.g. C:\web) Unzip the attachment discovery.zip in your web home. The following files/folders should be contained in your web home css/idpselect.css js/ idpselect.js idpselect_config.js discovery.html discovery.php These include basic templates - customize and rebrand to suit your application after functionality is tested Save Do not yet restart shibboleth service SSO tag In shibboleth2.xml, locate the Handler elements (should be near top of file) Update the SSO tag (which points to a specific IdP's entityID) with the SSO discoveryProtocol SAML2 If you decide to rename the discovery.html file in your web-home, you must also include that filename, here in the SSO tag Save Restart the Shibboleth Daemon IIS: Services > Shibboleth Daemon > Right-Click > Restart Linux: systemctl restart shibd Restart your web application IIS: Internet Information Services (IIS) Manager > > Restart Duo MFA Duo is the CSU System selected tool for multi-factor authentication (MFA or 2FA). Learn more about Duo Two-Factor Authentication. Single Sign-On (SSO) can be configured to work with Duo as a second authentication factor that follows username and password. DUO can be configured to operate with SSO from either the Service Provider (SP) or Identity Provider (IdP), but it is recommended that CSU Shibboleth SPs requiring DUO be configured in the SP (and not the IdP). NOTE: before adding Duo to your Shibboleth SP, it is advised you notify users and stakeholders. To start adding Duo to your application's Shibboleth SP, open shibboleth2.xml in a text editor Windows/IIS: C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml Linux: /etc/shibboleth/shibboleth2.xml Locate the SSO element in the Sessions tag Add authnContextClassRef="http://colostate.edu/mfa" anywhere in the SSO tag SAML2 Save Restart shibboleth to enable Duo MFA Windows/IIS: Services > Shibboleth Daemon > Right-click > Restart Linux: systemctl restart shibd Test in a browser (private/incognito window) Review your Shibboleth SP logs if Duo does not prompt Further Reading Shibboleth Service Provider - Shibboleth Resources

Shibboleth Service Provider - Update Signing Certificate Updating the Signing Certificate on a Shibboleth Service Provider involves generating a new signing certificate and key, configuring the new files in your service provider, uploading the updated certificate to the CSU Federation, and having the updates loaded into the CSU System Identity Providers. New signing certificates are automatically generated with new installations of the Shibboleth Service Provider Certificate + key pairs last 10 years CSU's Identity and Access Management team will send out reminder-emails of a certificate's impending expiration beginning 60 days before expiration date Expiration emails are sent to the contact information provided in the CSU Federation Use a group email address to ensure widespread communication This article describes how to perform a signing certificate update using rollover, theoretically resulting in no downtime. CSU's IAM recommends notifying users and scheduling a cautionary maintenance window. Applicable To CSU System, Fort Collins, Pueblo, Spur IT Staff, CSU Federation service provider administrators Prerequisites Access to update the server that manages the Shibboleth Service provider Access to the CSU Federation Management pages: CSU Federation - Manage Service Provider Certificates Access requests can be sent to iamhelp@colostate.edu Requires campus/VPN Connection (Global Protect) NOTE: Some steps may require involvement from CSU's IAM department. Please review full article before beginning process. Instructions: You'll receive a notification email titled: Your Shibboleth certificate will soon expire Schedule Maintenance/Downtime (if applicable) Performing the certificate update using a certificate rollover shouldn't result in any downtime; maintenance is still recommended as a precautionary measure Division of IT use https://coloradostateuniversity.statuspage.io/ Back up existing certificate & key Your Shibboleth Service Provider should use the same file/value for both the signing and encryption certificates. Find the files used by examining your shibboleth2.xml configuration file Copy/back upshibboleth.xml before editing IIS: \opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml Linux: /etc/shibboleth/shibboleth2.xml In shibboleth2.xml, locate the CredentialResolver element (should be a single cert+key pair, or two cert+key pairs that use the same values) Open the cert+key in a text editor to view and compare their contents Back up both the certificate and key in your system by making a copy Generate new Cert+Key Pair Location: IIS: \opt\shibboleth-sp\etc\shibboleth\keygen.bat Linux: /etc/shibboleth/keygen.sh The keygen utility file began shipping with the Shibboleth Service Provider with Versions 3.*. We recommend updating your Shibboleth Service Provider configuration if applicable Shibboleth Service Provider - Update Shibboleth Version (IIS) Until your Service Provider is updated, you can download the keygen utility from Shibboleth.net Go to https://shibboleth.net/downloads/service-provider/ Locate & Select the most current version of Shibboleth Download the *.zip file Unzip and Copy the keygen file to your running Shibboleth Service Provider server From unzipped folder: shibboleth-sp-\configs\keygen.[sh/bat] Two new files will generate: sp-cert.pem and sp-key.pem If the files fail to generate, it may be because the certificates already exist by the same name. For Windows, run the .bat command in CMD-prompt to see output if needed Rename the new Cert+Key Pair if needed and add them to your shibboleth2.xml file while keeping the current Cert+Key Pair intact NOTE: if you have two different files saved for "encryption" and "signing," both cert-values should be identical and you'll only need to run the keygen utility once to get a new value to replace both. Save Adding the second pair of cert+key enables your Service Provider to support both/either/or pairs for single sign-on authentications. Your Service Provider should continue to function as normal Restart Shibboleth Daemon IIS: Services > Shibboleth Daemon > Right Click > Restart Linux: systemctl restart shibd Test continued SSO functionality for your service in a private/incognito window At this point the CSU Federation will still use your old/soon-to-expire certificate for authentications Add Certificate to CSU Federation Manager Navigate + login to https://wsprod.colostate.edu/cwis24/acns/shibboleth/certificates Contact iamhelp@colostate.edu if no access permitted Click Add Certificate Populate Host Name, Department, Certificate (remove --BEGIN-- and --END-- comment lines) Click Insert After saving, click to open Certificate in Federation Manager to verify successful save (should see Serial Number, Dates, and Creator NetID populated) At this point the Certificate is saved in the CSU Federation repository but is not attached to any Service Providers Change Certificate for Service Provider in CSU Federation Manager NOTE: Please read through these steps before continuing Updates entered into the CSU Federation Manager are published to the CSU Federation metadata on a schedule: Daily at 11:00 am MT - all entries to the CSU Federation Manager are entered into the CSU Federation Metadata database Daily at 12:00 pm MT - the CSU Federation Metadata is published with all updates that were recorded in the database at 11:00 am MT If needed, coordinate with an IAM developer (in advance of your update work) at iamhelp@colostate.edu to plan a time to have the metadata updated outside of the normal schedule If your Service Provider configuration has multiple, configured SP entityIDs, you must complete the following steps for each in the CSU Federation Manager Additional SP entity IDs are configured in the ApplicationOverride elements in the ApplicationDefaults in your shibboleth2.xml file. Navigate + log in to the CSU Federation Manager: https://wsprod.colostate.edu/cwis24/acns/shibboleth/ServiceProviders Locate and open your Service Provider entry Click edit Scroll down to the contacts section Ensure the current contact is up-to-date. Add any contact emails necessary and make sure all contact emails are group emails. In the Certificate row, from the drop-down menu, find and select your newly added Certificate Click Save Your Service Provider entry should now show your updated Certificate with updated dates Updated Certificate and Service Provider is populated in CSU Federation Metadata https://csufederation.acns.colostate.edu/csufederation-metadata.xml and https://csufederation.acns.colostate.edu/csufederationtest-metadata.xml The CSU Federation Metadata database is updated daily at 11:00 am Mountain Time, then published to the Metadata [website] at 12:00 pm Mountain Time. If an update needs to happen outside of its normally scheduled time, contact iamhelp@colostate.edu to schedule in advance CSU System Identity Providers retrieve+cache the current CSU Federation Metadata every 2-3 hours. Within 2-3 hours of the automated CSU Federation metadata update, the Identity Providers will start using your updated Service Provider's certificate IAM will also manually refresh the IdPs' cached CSU Federation Metadata if you've requested a CSU Federation Metadata update Test continued SSO functionality for your service in a private/incognito window The CSU Federation will now use your new certificate for authentications Remove the old Cert+Key from your Service Provider In shibboleth2.xml, find + remove the references to your old Cert+Key pair, leaving the new Cert+Key pair intact Save Restart Shibboleth Daemon Test continued SSO functionality for your service in a private/incognito window Outcome: The signing Certificate on your Shibboleth Service Provider will serve for 10 more years. Additional Resources Shibboleth Service Provider - Shibboleth Resources

Recommendations for server upgrade/replacement with CSU System Shibboleth Service Provider This article outlines the steps and recommendations for performing a server replacement while maintaining CSU Shibboleth Service Provider integration. It ensures continuity of service during the migration by following specific guidelines for setup, installation, and configuration. Applicable to: CSU System, Fort Collins, Pueblo, Spur Affiliation: IT Prerequisites Administrative access to both the server being replaced and the new server. Shibboleth Service Provider installation files. Access to the CSU Federation certificate manager. See CSU Federation for access requirements Recommended Steps Set up new server/site Install the new service or website using the same website and domain name as the one being replaced. The new server can be accessed by specifying the IP address in the hostsfile of the testing user’s machine. During setup and configuration, the replacement service will not be accessible via current DNS specifications or the load balancer. Install Shibboleth Service Provider Perform a fresh installationof the current release of Shibboleth Service Provider on the new server. See Single Sign-On & Shibboleth Service Providers for resources Configure Service Provider Configure the Service Provider (SP) to match the previous SP settings, ensuring you use the same entityID. The same signing certificate & keymust be used. Both the signing certificate & key can be retrieved from the server being replaced. Do not create a new entry in the CSU Federation for the SP. The existing entry will be used for testing and production. Test authentication Perform authentication testsbefore rolling over the server. Testing can be performed on new server by isolating IP address on testing machine's hosts file Any issues encountered can be resolved within the Service Provider itself and do not require changes in the CSU Service Provider Federation entry. Perform server rollover Complete the server rollover once testing is successful. No additional troubleshooting from the CSU Shibboleth Service Provider should be required during this step. Outcome Following these steps ensures the successful replacement of a server while maintaining integration with CSU's Shibboleth Service Provider, preventing disruption of service.

This resource is used to track issues that you may encounter as an administrator to a Shibboleth service provider in the CSU Federation. Please use this to help in troubleshooting. Applicable To Admins of CSU System Service Providers in the CSU Federation Prerequisites CSU System IT manage Shibboleth Service Providers for CSU System sites Contents: Address Checking Error Looping Address Checking Error Problem: Users generate a browser error when trying to use single sign-on to authenticate into your application: 2024-02-29 09:31:57 WARN Shibboleth.SSO.SAML2 [59] [default]: detected a problem with assertion: Your client's current address (129.82.XX.XX) differs from the one used when you authenticated to your identity provider. To correct this problem, you may need to bypass a proxy server. Please contact your local support staff or help desk for assistance. This mismatch typically happens when a user's client is behind a proxy, VPN, or similar network device. These devices route traffic in a way that the web servers see different addresses. It's often referred to as "split tunneling" and occurs when only certain traffic is routed through the device. Solution: Change the checkAddress setting in your Shibboleth Service Provider to disable this check. (NOTE: Shibboleth restart required to apply change) Find + open your shibboleth2.xml configuration file IIS: \opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml Linux: /etc/shibboleth/shibboleth2.xml Modify the sessions element to add/change the checkAddress property, disabling it by setting it to false NOTE: If your service provider manages multiple websites, this modification must be completed in each Sessions element for the affected site(s). Save Restart the Shibboleth service IIS: Services > Shibboleth Daemon > Right Click > Restart Linux: systemctl restart shibd Test by authenticating through a private/incognito window Looping Problem: A user reaches the SSO login page, correctly enters credentials, and then quickly begins ‘looping’ through attempts to create new authentication sessions. Both the service provider (SP) and identity provider (IdP) show a rapid succession of new sessions being created indefinitely until the user ends their browser session. Service Provider Logs: 2023-03-08 12:32:50 INFO Shibboleth.SessionCache [1] [arieswebnew.colostate.edu]: new session created: ID (_736433175ee0876317fe536c67b34af7) IdP (https://shibidp.colostate.edu/idp/shibboleth) Protocol(urn:oasis:names:tc:SAML:2.0:protocol) Address (129.82.103.25) 2023-03-08 12:32:50 INFO Shibboleth.SessionCache [1] [arieswebnew.colostate.edu]: new session created: ID (_c28810aba3e445b5a0af55285703267f) IdP (https://shibidp.colostate.edu/idp/shibboleth) Protocol(urn:oasis:names:tc:SAML:2.0:protocol) Address (129.82.103.25) 2023-03-08 12:32:50 INFO Shibboleth.SessionCache [1] [arieswebnew.colostate.edu]: new session created: ID (_83e52f6202d4874d511d3284affebf8f) IdP (https://shibidp.colostate.edu/idp/shibboleth) Protocol(urn:oasis:names:tc:SAML:2.0:protocol) Address (129.82.103.25) 2023-03-08 12:32:50 INFO Shibboleth.SessionCache [1] [arieswebnew.colostate.edu]: new session created: ID (_964eb444af18c4e8c7fe3fe90d1a9f07) IdP (https://shibidp.colostate.edu/idp/shibboleth) Protocol(urn:oasis:names:tc:SAML:2.0:protocol) Address (129.82.103.25) 2023-03-08 12:32:50 INFO Shibboleth.SessionCache [1] [arieswebnew.colostate.edu]: new session created: ID (_2ef51666d533ad3ad98442771fdf1a75) IdP (https://shibidp.colostate.edu/idp/shibboleth) Protocol(urn:oasis:names:tc:SAML:2.0:protocol) Address (129.82.103.25) 2023-03-08 12:32:50 INFO Shibboleth.SessionCache [1] [arieswebnew.colostate.edu]: new session created: ID (_ccb4ce7655318fdb398b53f8e62dd4d1) IdP (https://shibidp.colostate.edu/idp/shibboleth) Protocol(urn:oasis:names:tc:SAML:2.0:protocol) Address (129.82.103.25) 2023-03-08 12:32:50 INFO Shibboleth.SessionCache [1] [arieswebnew.colostate.edu]: new session created: ID (_9f724ecb89468ba210e4a07fe9822b74) IdP (https://shibidp.colostate.edu/idp/shibboleth) Protocol(urn:oasis:names:tc:SAML:2.0:protocol) Address (129.82.103.25) Solution: There could be different components causing this, but a common cause can be an incorrect domain value in the Sessions tag of your service provider configuration. (NOTE: Shibboleth restart required to apply change) Find + open your shibboleth2.xml configuration file IIS: \opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml Linux: /etc/shibboleth/shibboleth2.xml Modify the sessions element to change the domain property to the highest common denominator for all endpoints/websites protected by your service provider. Example: if your service provider protects both dev.ariesweb.colostate.edu and dev.ramweb.colostate.edu, your domain element should be .colostate.edu. Restart the Shibboleth service IIS: Services > Shibboleth Daemon > Right Click > Restart Linux: systemctl restart shibd Test by authenticating through a private/incognito window Further Reading: Shibboleth Consortium - AddressChecking

Description Use this guide in addition to the official Release Notes, where Shibboleth announces updates, to perform Service Provider (SP) updates on a Windows server (IIS). Notifications of a new version is also emailed to announce@shibboleth.net. The OS used to develop this guide: Windows 2022 (IIS) Shibboleth Service Provider - About To update the Service Provider, you'll have a snapshot taken of your machine, back up your current configuration files, run the installer for the new version, restart and test your Service Provider. Instructions Before beginning the update, take a snapshot of your machine. (IAM specifically- one business day before your scheduled update, email vmhelp@colostate.edu to request the snapshot be taken before your update). Other departments, contact your server manager responsible for performing system snapshots. Include the machine name (e.g. shibspwintest.acns.colostate.edu)  Download the new version of the Shibboleth Service Provider from the Shibboleth Software Repository Open the Win64/Win32 folder that matches your system E.g. for shibspwintest.acns.colostate.edu, win64 > -win64.msi installer Download the shibboleth-sp-.msi file Copy/move the shibboleth-sp-.msi file onto your server In your server, double-click your shibboleth-sp-.msi file to run the installer Click Next at the Welcome to the Shibboleth... setup screen Click Next at the Update Shibboleth setup screen Click Install at the Ready to install Shibboleth Service Provider setup screen When prompted, close Shibboleth  After the installer is finished, test your Service Provider If your Service Provider isn't functional, use your snapshot to revert to your previous configuration. Additional Tips: To see your current version of the Shibboleth Service Provider: In file explorer, navigate to c:\opt\shibboleth-sp\sbin Type cmd in the filepath entry bar and press Enter to open the Command prompt in this location Enter the command shibd -version to see your current version of the Shibboleth Service Provider Further reading Shibboleth Service Provider - Shibboleth Resources