Shibboleth Server
Overview
This document provides technical reference information about our Shibboleth Service Provider infrastructure. For information about Shibboleth as an authentication method, see Shibboleth. For conceptual understanding, see Shibboleth Overview.
In the legacy AWS account, we have two EC2 instances running our Shibboleth setup: ec2-euc-shib-01 and ec2-euc-shib-02. These servers run the Shibboleth Service Provider software that interacts with Identity Providers. This software handles SAML requests and responses.
These servers are accessible via the shibboleth.statista.com domain.
Configuration Repository
ℹ️ Configuration Management: All Shibboleth configuration files, certificates, and deployment scripts are version-controlled in the shibboleth-server-configuration repository.
The repository contains:
- Shibboleth configuration files (
shibboleth2.xml,attribute-map.xml, etc.) - SSL/TLS certificates for
shibboleth.statista.com - Metadata signing certificates for federation trust
- Apache configuration
- Landing page (
index.php) - Automated deployment script for pushing configuration to both servers
Key Benefits:
- Version control for all configuration changes
- Documented deployment process
- Easy rollback to previous configurations
- Consistent configuration across both instances
Usage: See the repository README for detailed instructions on pulling latest configurations, making changes, and deploying to servers.
EC2 Instances
- Instance Names:
- ec2-euc-shib-01
- ec2-euc-shib-02
- Region: Frankfurt (eu-central-1)
- Purpose: Run the Shibboleth Service Provider, ensuring high availability and redundancy
Shibboleth Service
shibd.service
The Shibboleth daemon (shibd) is the core service responsible for handling authentication and attribute resolution in a Shibboleth Service Provider (SP) environment.
- Service Name:
shibd.service - Description: Manages authentication requests, sessions, and interactions with Identity Providers (IdPs)
Key Commands:
sudo systemctl start shibd.service
sudo systemctl stop shibd.service
sudo systemctl restart shibd.service
sudo systemctl status shibd.service
⚠️ Important: shibd takes approximately 90 minutes to start due to parsing and validating ~270MB of federation metadata. This is normal behavior. See the certificate renewal guide for details.
Configuration Files
Shibboleth SP uses several configuration files located in /etc/shibboleth/ to define its behavior and establish trust relationships with different federations.
ℹ️ Note: These configuration files are managed through the shibboleth-server-configuration repository. Do not edit files directly on the servers unless absolutely necessary for emergency troubleshooting.
/etc/shibboleth/shibboleth2.xml
- Purpose: Primary configuration file for the Shibboleth Service Provider
- Location:
/etc/shibboleth/shibboleth2.xml - Content:
- SP Setup: Defines the SP's entity ID, local endpoints, and attributes it handles
- Metadata Provider: Specifies metadata sources, potentially referencing multiple federation files
- Session Management: Configures user sessions and Single Sign-On (SSO)
- Access Control: Manages access to protected resources
- Security Settings: Handles certificates, encryption, and signing processes
/etc/shibboleth/dfn-aai-basic-metadata.xml
- Purpose: Contains core metadata for entities within the DFN-AAI federation
- Location:
/etc/shibboleth/dfn-aai-basic-metadata.xml - Scope: Includes basic information necessary for interaction within the DFN-AAI federation
/etc/shibboleth/DFN-AAI-metadata.xml
- Purpose: Comprehensive metadata file for the DFN-AAI federation
- Location:
/etc/shibboleth/DFN-AAI-metadata.xml - Scope: May include extended entities, providing broader federation coverage than the basic metadata file
/etc/shibboleth/dfn-aai-edugain+idp-metadata.xml
- Purpose: Extends the DFN-AAI metadata to include entities from the eduGAIN federation
- Location:
/etc/shibboleth/dfn-aai-edugain+idp-metadata.xml - Scope: Facilitates global federated access by incorporating eduGAIN entities alongside DFN-AAI
/etc/shibboleth/ukfederation-metadata.xml
- Purpose: Contains metadata for entities within the UK Access Management Federation (UK Federation)
- Location:
/etc/shibboleth/ukfederation-metadata.xml - Scope: Enables interaction with UK-based institutions and services within the UK Federation
/etc/shibboleth/carsi-metadata.xml
- Purpose: Contains metadata for entities within CARSI, the Chinese academic federation (operated by Peking University)
- Location:
/etc/shibboleth/carsi-metadata.xml - Scope: Enables interaction with Chinese academic institutions within the CARSI federation
- Added: February 2026. See Add a New Metadata Provider to Shibboleth for the how-to guide.
Summary of Configuration Files
- shibboleth2.xml: Main configuration file for the SP, managing its behavior, session management, and security settings. It references the other metadata files to establish trust relationships.
- dfn-aai-basic-metadata.xml: Basic metadata for entities within the DFN-AAI federation, focusing on core entities necessary for interaction.
- DFN-AAI-metadata.xml: More comprehensive metadata file for the DFN-AAI federation, potentially including extended entities and broader federation coverage.
- dfn-aai-edugain+idp-metadata.xml: Combines DFN-AAI and eduGAIN federation metadata, enabling the SP to interact with a global network of federated entities.
- ukfederation-metadata.xml: Metadata specific to the UK Federation, facilitating interaction with UK-based academic and research institutions.
Log Files
Logs are essential for monitoring the Shibboleth Service Provider's activity and troubleshooting issues.
- Log File Location:
/var/log/shibboleth/shibd.log - Log Content:
- Authentication Requests: Details about incoming authentication requests
- Error Reporting: Captures errors and warnings for troubleshooting
- Session Details: Information related to user sessions and attribute processing
SSH Access
In rare cases, SSH access might be needed to troubleshoot Shibboleth-related issues. This access requires a VPN connection and is typically not handled by our team.
- SSH Access Key:
euc-shib.pem - VPN Requirement: SSH access is only available through a secure VPN connection
- Purpose: Provides secure access to the server for advanced troubleshooting
Connecting via SSH:
ssh -i /path/to/euc-shib.pem user@hostname
Note: Major issues should be escalated to the responsible team.
Related Documentation: Statista Atlassian - Shibboleth Troubleshooting