SSO with Shibboleth

SSO with Shibboleth

This guide covers the configuration of Single Sign-On (SSO) authentication for rConfig V8 using Shibboleth, a SAML 2.0 based identity provider commonly used in educational institutions. The process involves configuring your Shibboleth IdP and uploading SAML metadata to rConfig.

Shibboleth is not a separate protocol. It is a SAML 2.0 Identity Provider. In rConfig, Shibboleth uses the same underlying SAML2 implementation. The distinction is UI-level only (separate login button).

Caution

As of V8.2.0, metadata must be provided as a local XML file in SAML2_METADATA_FILE. URL-based metadata and raw XML environment values are not supported.

Caution

Shibboleth is a complex Identity Provider system primarily used in educational institutions. Its setup and configuration is outside the scope of this document. Consult your Shibboleth documentation and IT department for IdP configuration assistance.

Caution

Users are not automatically granted access to rConfig after SSO authentication. An administrator must approve each user before they can access the application. See the User Management section for more information.

Prerequisites

• Shibboleth Identity Provider already configured and operational
• Administrator access to Shibboleth IdP
• Administrator access to rConfig V8
• rConfig server accessible via HTTPS with valid domain name
• SAML metadata XML file from your Shibboleth IdP

Configure Shibboleth Identity Provider

Step 1: Create Application Integration

Configure Shibboleth to recognize rConfig as a Service Provider (SP). This process varies by institution but generally involves:

1. Registering rConfig as a new Service Provider
2. Configuring attribute release policies
3. Generating SAML metadata for rConfig

Helpful Resource:

Harvard University provides an excellent guide for SAML/Shibboleth integration: Harvard IAM - SAML Shibboleth Integration

Step 2: Download Metadata

Download the metadata.xml file from your Shibboleth Identity Provider. This is IdP metadata, which rConfig consumes to authenticate users. The Service Provider (SP) metadata is generated separately by rConfig (see the next section).

Configure rConfig V8

Step 1: Upload Metadata File

Upload your metadata.xml file to the rConfig SAML directory:

# Create SAML directory if it doesn't exist
mkdir -p /var/www/html/rconfig8/current/storage/saml2

# Upload your metadata.xml to this location
/var/www/html/rconfig8/current/storage/saml2/idp-metadata.xml

Note

rConfig reads IdP metadata directly from the filesystem using SAML2_METADATA_FILE. Do not expose this file publicly.

Provide SP Metadata to Your IdP

rConfig exposes its Service Provider (SP) metadata at:

https://your-rconfig-domain.com/auth/saml2/metadata

Provide this URL to your Identity Provider administrator. This is the metadata your IdP needs to trust rConfig as a Service Provider.

Note: The metadata file referenced by SAML2_METADATA_FILE is IdP metadata consumed by rConfig. The /auth/saml2/metadata endpoint is SP metadata generated by rConfig.

Step 3: Edit Environment Configuration

Open the rConfig .env file:

vim /var/www/html/rconfig8/current/.env

Step 4: Add Shibboleth SAML Configuration

Add or update the following lines:

SAML2_METADATA_FILE='/var/www/html/rconfig8/current/storage/saml2/idp-metadata.xml'
SAML2_ENABLED=false
SHIBBOLETH_ENABLED=true
SAML2_SP_CERTIFICATE='/var/www/html/rconfig8/current/storage/saml2/sp-cert.pem'
SAML2_SP_KEY='/var/www/html/rconfig8/current/storage/saml2/sp-key.pem'

Configuration Parameters:

• SAML2_METADATA_FILE: Local file path to IdP metadata XML. This is required in V8.2.0+.
• SAML2_ENABLED: Toggle the generic SAML2 login button independently.
• SHIBBOLETH_ENABLED: Toggle the Shibboleth login button independently.
• SAML2_SP_CERTIFICATE: Path to Service Provider certificate
• SAML2_SP_KEY: Path to Service Provider private key

Note

Shibboleth in rConfig uses the same underlying saml2 Socialite provider as generic SAML2. The separate SHIBBOLETH_ENABLED toggle only controls login button visibility and provider path selection in the UI.

Breaking Change in V8.2.0

• Old:

SAML2_METADATA_URL=https://idp.example.com/metadata

• New:

SAML2_METADATA_FILE=/path/to/idp-metadata.xml

Migration command:

curl https://idp.example.com/metadata > /path/to/idp-metadata.xml

After migration, verify the web server user can read the file.

ACS URL (Exact Match Required)

The ACS URL MUST match exactly between rConfig and your IdP:

https://your-rconfig-domain.com/auth/callback/saml2

This includes:

• HTTPS vs HTTP
• no trailing slashes
• exact path

Mismatches will cause authentication failures.

SAML Binding Behavior

Most Identity Providers use HTTP-POST binding for SAML responses.

rConfig supports both GET and POST callbacks, but POST is the most common.

Ensure your IdP is configured to POST assertions to the ACS URL.

Single Logout (SLS)

Single Logout (SLS) support depends on your Identity Provider. If logout issues occur, it is safe to leave SLS unconfigured.

Step 5: Clear Application Cache

Save the file and clear the rConfig cache:

php /var/www/html/rconfig8/current/artisan rconfig:clear-all

Verify Configuration

After configuration, the rConfig login page will display a Login with Shibboleth button.

User Approval Process

When users attempt to sign in via SSO for the first time:

1. User authenticates successfully with Shibboleth
2. User account is created in rConfig with SSO access disabled
3. User sees an error message indicating approval is required

Administrator must:

1. Log in to rConfig as an administrator
2. Navigate to Users section
3. Locate the new SSO user
4. Enable SSO access for the user
5. Assign appropriate role and permissions

After approval, the user can successfully authenticate and access rConfig.

Troubleshooting

SSO button not appearing

• Verify all environment variables are correctly set
• Ensure cache has been cleared: php artisan rconfig:clear-all
• Check that the metadata file exists at SAML2_METADATA_FILE

Metadata file not accessible

• Check file permissions on metadata.xml (should be readable by web server)
• Verify SAML2_METADATA_FILE points to the file path you uploaded
• Metadata file must contain raw XML
• Metadata must NOT be: - HTML login page - redirected content - copied URL text
• Validate XML content and ensure the first non-whitespace character is <
• Example:

head /var/www/html/rconfig8/current/storage/saml2/idp-metadata.xml

  Expected output starts with:
     <EntityDescriptor

Authentication fails

• Verify metadata.xml contains correct Shibboleth IdP configuration
• Check that Service Provider certificate and private key exist
• Confirm Shibboleth IdP has rConfig registered as a valid Service Provider
• Review Apache error logs for SAML-related errors

ACS URL mismatch

• Confirm the IdP ACS URL is exactly https://your-rconfig-domain.com/auth/callback/saml2
• Check scheme (https), path, and trailing slash behavior
• Any mismatch can break SAML assertion delivery or validation

Reverse proxy or load balancer issues

If rConfig is behind a load balancer or reverse proxy:

• Ensure APP_URL is set correctly (https)
• Ensure trusted proxies are configured

Incorrect scheme detection can break SAML validation.

Certificate or key file errors

• Verify certificate and private key paths are correct in .env
• Check file permissions (readable by web server user)
• Ensure certificate and key files are valid and not expired

Attribute release issues

• Verify Shibboleth IdP is configured to release required attributes (email, name)
• Check attribute mapping configuration in Shibboleth
• Review Shibboleth IdP logs for attribute release errors

Users cannot access after SSO login

• Verify administrator has enabled SSO access in Users section
• Confirm user has been assigned an appropriate role
• Check user account status is active

Time synchronization issues

SAML assertions are time-sensitive.

Ensure your rConfig server and Identity Provider are time-synchronised (NTP).

Clock drift can cause valid logins to fail with authentication or validation errors.

Maintenance Notes

Always keep IdP metadata local and referenced through SAML2_METADATA_FILE. Do not expose metadata files in a public web directory.

Related Documentation

• SSO Overview - Understanding SSO in rConfig V8
• Generic SAML Setup - Alternative SAML configuration
• User Management - Managing user accounts and approvals
• Role-Based Access Control - Configuring user roles and permissions