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/saml2/metadata

Assertion Consumer Service (ACS) URL:

https://your-rconfig-domain.com/saml2/acs

Single Logout Service (SLS) URL:

https://your-rconfig-domain.com/saml2/sls

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_IDP_METADATA_FILE='/var/www/html/rconfig8/current/storage/saml2/idp-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'
SAML2_SP_ENTITY_ID='https://your-rconfig-domain.com/saml2/metadata'
SAML2_SP_ACS_URL='https://your-rconfig-domain.com/saml2/acs'
SAML2_SP_SLS_URL='https://your-rconfig-domain.com/saml2/sls'

Configuration Parameters:

SAML2_IDP_METADATA_FILE: Path to IdP metadata XML file
SAML2_SP_CERTIFICATE: Path to Service Provider certificate
SAML2_SP_PRIVATE_KEY: Path to Service Provider private key
SAML2_SP_ENTITY_ID: rConfig’s SAML Entity ID (must match IdP configuration)
SAML2_SP_ACS_URL: Assertion Consumer Service URL (must match IdP configuration)
SAML2_SP_SLS_URL: Single Logout Service 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. Generate and provide this to your IdP administrator:

Option 1: Access Metadata URL

Navigate to the following URL in your browser:

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

Save the XML content or provide this URL to your IdP administrator.

Option 2: Generate Metadata File

php /var/www/html/rconfig8/current/artisan saml2:generate-metadata > sp-metadata.xml

Provide this sp-metadata.xml file to your IdP administrator.

Verify Configuration

After configuration, the rConfig login page will display a Sign in with SAML 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_IDP_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

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 Entity ID, ACS URL, and SLS URL in .env match IdP configuration
Check for case sensitivity in URLs

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

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