SSO with SAML

SSO with SAML 2.0

This guide covers the configuration of Single Sign-On (SSO) authentication for rConfig V8 using any SAML 2.0 compliant Identity Provider. Use this guide when your IdP is not covered by the specific integration guides (Microsoft, Okta, Google, or Shibboleth).

Prerequisites

SAML 2.0 compliant Identity Provider configured and operational
Administrator access to your Identity Provider
Administrator access to rConfig V8
rConfig server accessible via HTTPS with valid domain name
Ability to configure SAML Service Provider settings in your IdP

SAML Configuration Requirements

Your Identity Provider must support SAML 2.0 and be configured to release the following attributes:

Required Attributes:

Email address: User’s email (typically email, mail, or emailAddress)
Name: User’s display name (typically displayName, name, or cn)

Optional Attributes:

Given name: First name
Surname: Last name
User ID: Unique identifier

Configure Your Identity Provider

Step 1: Create Service Provider Entry

In your Identity Provider, create a new SAML 2.0 Service Provider (SP) application with the following details:

Entity ID / Audience:

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

Assertion Consumer Service (ACS) URL:

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

Single Logout Service (SLS) URL:

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

Name ID Format:

Use urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress or
Use urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Step 2: Configure Attribute Mapping

Configure your IdP to release the following attributes to rConfig:

IdP Attribute	SAML Attribute Name	Description
Email Address	`email` or `mail`	User’s email address (required)
Display Name	`displayName` or `name`	User’s full name (required)
First Name	`givenName`	User’s first name (optional)
Last Name	`sn` or `surname`	User’s last name (optional)

Step 3: Download IdP Metadata

Download the SAML metadata XML file from your Identity Provider. This file typically contains:

IdP Entity ID
Single Sign-On Service URL
X.509 Certificate
Supported bindings and endpoints

Save this file as idp-metadata.xml.

Configure rConfig V8

Step 1: Upload IdP Metadata

Upload your IdP metadata 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 idp-metadata.xml to this location
/var/www/html/rconfig8/current/storage/saml2/idp-metadata.xml

Set appropriate permissions:

chown -R apache:apache /var/www/html/rconfig8/current/storage/saml2  # Rocky/RHEL
# or
chown -R www-data:www-data /var/www/html/rconfig8/current/storage/saml2  # Ubuntu
chmod 755 /var/www/html/rconfig8/current/storage/saml2
chmod 644 /var/www/html/rconfig8/current/storage/saml2/idp-metadata.xml

Step 2: Generate Service Provider Certificate

Generate a self-signed certificate for the SAML Service Provider:

# Generate private key
openssl genrsa -out /var/www/html/rconfig8/current/storage/saml2/sp-key.pem 2048

# Generate certificate (valid for 10 years)
openssl req -new -x509 -key /var/www/html/rconfig8/current/storage/saml2/sp-key.pem \
  -out /var/www/html/rconfig8/current/storage/saml2/sp-cert.pem -days 3650

You’ll be prompted for certificate information. Fill in appropriate values:

Country Name (2 letter code) [XX]: US
State or Province Name (full name) []: California
Locality Name (eg, city) []: San Francisco
Organization Name (eg, company) []: Your Organization
Organizational Unit Name (eg, section) []: IT
Common Name (eg, your server's hostname) []: your-rconfig-domain.com
Email Address []: [email protected]

Set appropriate permissions:

chmod 600 /var/www/html/rconfig8/current/storage/saml2/sp-key.pem
chmod 644 /var/www/html/rconfig8/current/storage/saml2/sp-cert.pem

Step 3: Edit Environment Configuration

Open the rConfig .env file:

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

Step 4: Add SAML Configuration

Add or update the following lines:

SAML2_METADATA_FILE='/var/www/html/rconfig8/current/storage/saml2/idp-metadata.xml'
SAML2_ENABLED=true
SHIBBOLETH_ENABLED=false
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 generic SAML2 login button visibility.
SHIBBOLETH_ENABLED: Toggle Shibboleth login button visibility independently.
SAML2_SP_CERTIFICATE: Path to Service Provider certificate
SAML2_SP_KEY: Path to Service Provider private key

Breaking Change in V8.2.0

Metadata loading is now strict and deterministic.

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

Then set file ownership/permissions so 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.

Step 5: Clear Application Cache

Save the file and clear the rConfig cache:

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

Provide SP Metadata to Your IdP

Some Identity Providers require Service Provider metadata. rConfig exposes its Service Provider (SP) metadata at:

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

Provide this URL to your Identity Provider administrator.

Verify Configuration

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

User Approval Process

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

User authenticates successfully with your Identity Provider
User account is created in rConfig with SSO access disabled
User sees an error message indicating approval is required

Administrator must:

Log in to rConfig as an administrator
Navigate to Users section
Locate the new SSO user
Enable SSO access for the user
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 in .env
Ensure cache has been cleared: php artisan rconfig:clear-all
Check that IdP metadata file exists and is readable
Review Apache error logs for configuration errors

IdP metadata file errors

Verify file path is correct in SAML2_METADATA_FILE
Check file permissions (readable by web server)
Ensure metadata XML is valid (no corruption or syntax errors)
Test file accessibility: cat /var/www/html/rconfig8/current/storage/saml2/idp-metadata.xml
Metadata file must contain raw XML
Metadata must NOT be:
- HTML login page
- redirected content
- copied URL text

Validate quickly:

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

Expected output starts with:

<EntityDescriptor

Certificate or key file errors

Verify certificate and private key paths are correct in .env
Check file permissions (private key should be 600, certificate 644)
Ensure certificate and key were generated successfully
Validate certificate: openssl x509 -in sp-cert.pem -text -noout

Authentication fails

Verify Entity ID matches exactly between rConfig and IdP configuration
Confirm ACS URL and SLS URL match IdP configuration
Check that required attributes (email, name) are being released by IdP
Review IdP logs for SAML assertion errors
Verify clock synchronization between rConfig server and IdP (time skew issues)

SAML response validation errors

Check X.509 certificate in IdP metadata is valid and not expired
Verify SAML response is signed by IdP
Ensure rConfig can validate IdP signature with certificate in metadata
Check for SAML protocol version mismatches

Attribute mapping issues

Verify IdP is releasing required attributes (email, displayName)
Check attribute names match expected values
Review SAML assertion in IdP logs to confirm attribute names
Test with different attribute name mappings if needed

URL mismatch errors

Ensure all URLs use HTTPS (not HTTP)
Verify domain name matches exactly (no trailing slashes)
Confirm your IdP ACS URL is https://your-rconfig-domain.com/auth/callback/saml2
Confirm your IdP SLS URL is https://your-rconfig-domain.com/auth/saml2/logout
Check for case sensitivity in URLs

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.

Verify administrator has enabled SSO access in Users section
Confirm user has been assigned an appropriate role
Check user account status is active
Review user email matches what’s sent in SAML assertion

Testing SAML Configuration

Test SAML Metadata

Access your SP metadata URL:

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

Verify the XML contains correct Entity ID, ACS URL, and certificate.

Test IdP Metadata

Verify IdP metadata is accessible:

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

Confirm it contains valid IdP Entity ID, SSO Service URL, and X.509 certificate.

Enable SAML Debug Mode

For detailed SAML debugging, temporarily enable debug mode:

# Add to .env
SAML2_DEBUG=true

Check logs after authentication attempt:

tail -f /var/www/html/rconfig8/current/storage/logs/laravel.log

Remember to disable debug mode after troubleshooting:

SAML2_DEBUG=false

Common IdP-Specific Notes

ADFS (Active Directory Federation Services)

Use http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress for email attribute
Use http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name for name attribute
Ensure claims are configured in Claim Rules

OneLogin

Entity ID must be registered exactly as configured
Verify SAML assertion is signed (not just response)
Check attribute mappings in OneLogin application configuration

Auth0

Use Universal Login for SAML
Configure SAML addon in Auth0 application settings
Map user attributes in SAML configuration tab

Keycloak

Create client with SAML protocol
Set Valid Redirect URIs to match ACS URL
Configure SAML attribute mappings in client mappers

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.

SSO Overview - Understanding SSO in rConfig V8
SSO with Shibboleth - Shibboleth-specific configuration
User Management - Managing user accounts and approvals
Role-Based Access Control - Configuring user roles and permissions