SSO with Google Workspace

This guide covers the configuration of Single Sign-On (SSO) authentication for rConfig V8 using Google Workspace. The process involves creating an OAuth application in Google Cloud Console and configuring rConfig with the necessary credentials.

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.

When to Use This Page

Follow this guide when your organization uses Google Workspace for identity management and you want rConfig users to log in with their existing Google credentials instead of a local rConfig password.

Prerequisites

• Administrator access to Google Cloud Console or Google Workspace Admin Console
• Administrator access to rConfig V8
• rConfig server accessible via HTTPS with valid domain name

Configure Google Workspace

Step 1: Create OAuth Application

Follow Google’s official documentation to set up your custom Identity Provider in the Google Admin Console:

Google Admin Console - Set up SSO for your organization

Step 2: Configure OAuth Consent Screen

In the Google Cloud Console:

1. Navigate to APIs & Services > OAuth consent screen
2. Select Internal or External based on your organization’s requirements
3. Fill in the required application information
4. Add authorized domains if needed
5. Save the configuration

Step 3: Create OAuth 2.0 Credentials

1. Navigate to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. Select Web application as the application type
4. Add a name for your OAuth client (e.g., “rConfig V8”)
5. Under Authorized redirect URIs, add:

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

6. Click Create
7. Copy the Client ID and Client Secret (you’ll need these for rConfig configuration)

Configure rConfig V8

Step 1: Edit Environment Configuration

Open the rConfig .env file:

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

Step 2: Add Google SSO Configuration

Add or update the following lines with your Google OAuth application values:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=https://your-rconfig-domain.com/auth/callback/google

Configuration Parameters:

• GOOGLE_CLIENT_ID: OAuth 2.0 Client ID from Google Cloud Console
• GOOGLE_CLIENT_SECRET: OAuth 2.0 Client Secret from Google Cloud Console
• GOOGLE_REDIRECT_URI: Must match the authorized redirect URI configured in Google

Step 3: 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 Google button.

User Approval Process

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

1. User authenticates successfully with Google
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.

Common Gotchas

Caution

• New SSO users aren’t active by default. The first successful Google login only creates the account, an administrator must still enable SSO access and assign a role before the user can sign in again.
• The redirect URI must match exactly. Any difference between the URI registered in Google Cloud Console and GOOGLE_REDIRECT_URI in .env (including trailing slashes or http vs https) causes authentication to fail.
• An unpublished OAuth consent screen blocks everyone except test users. If the consent screen is still in testing mode, only explicitly added test users can sign in, everyone else sees “Access blocked”.
• The cache must be cleared after every .env change. Run php artisan rconfig:clear-all after adding or updating the Google SSO variables, or the old (or missing) values keep being used.

Troubleshooting

SSO button not appearing

• Verify all environment variables are correctly set
• Ensure cache has been cleared: php artisan rconfig:clear-all
• Check Apache error logs for configuration issues

Authentication fails

• Verify redirect URI matches exactly between Google and rConfig
• Confirm OAuth consent screen is properly configured
• Check that the OAuth client is not restricted or disabled
• Ensure authorized domains include your rConfig domain

“Access blocked” error from Google

• Verify OAuth consent screen is published (not in testing mode) or user is added as a test user
• Check that user’s email domain is authorized in the OAuth configuration
• Confirm application is approved for the requested scopes

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

Related Documentation

• SSO Overview - Understanding SSO in rConfig V8
• User Management - Managing user accounts and approvals
• Roles and Permissions - Configuring user roles and permissions