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.

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 file contains the configuration details rConfig needs to authenticate users.

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/saml

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

Step 2: Create Symlink to Public Directory

Create a symbolic link to make the metadata accessible:

ln -s /var/www/html/rconfig8/current/storage/saml/metadata.xml \
      /var/www/html/rconfig8/current/public/metadata.xml

Note

This symlink will need to be recreated after each rConfig update. Document this step in your internal procedures or consider hosting the metadata file on a separate web server.

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_URL='https://your-rconfig-domain.com/metadata.xml'
SAML2_SP_CERTIFICATE='/var/www/html/rconfig8/current/storage/saml2/sp-cert.pem'
SAML2_SP_PRIVATE_KEY='/var/www/html/rconfig8/current/storage/saml2/sp-key.pem'

Configuration Parameters:

• SAML2_METADATA_URL: URL to your metadata.xml file (can be local or remote)
• SAML2_SP_CERTIFICATE: Path to Service Provider certificate
• SAML2_SP_PRIVATE_KEY: Path to Service Provider private key

Tip

You can host the metadata.xml file on a separate server if preferred. Update the SAML2_METADATA_URL to point to the external URL.

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 Sign in 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 metadata.xml file exists and is accessible
• Verify symlink is correctly created

Metadata file not accessible

• Check file permissions on metadata.xml (should be readable by web server)
• Verify symlink exists: ls -la /var/www/html/rconfig8/current/public/metadata.xml
• Test metadata URL in browser: https://your-rconfig-domain.com/metadata.xml

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

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

Symlink broken after update

• Recreate the symlink after each rConfig update:

  ln -s /var/www/html/rconfig8/current/storage/saml/metadata.xml \
        /var/www/html/rconfig8/current/public/metadata.xml

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

Maintenance Notes

After rConfig Updates:

The symbolic link to metadata.xml will need to be recreated after each rConfig update. Add this step to your update procedures:

ln -s /var/www/html/rconfig8/current/storage/saml/metadata.xml \
      /var/www/html/rconfig8/current/public/metadata.xml

Alternative: External Metadata Hosting

To avoid recreating the symlink after updates, host the metadata.xml file on a separate web server and update SAML2_METADATA_URL to point to the external URL.

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