SSO with Okta

This guide covers the configuration of Single Sign-On (SSO) authentication for rConfig V8 using Okta. The process involves creating an OpenID Connect (OIDC) application in Okta 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 Okta for identity management and you want rConfig users to log in with their existing Okta credentials instead of a local rConfig password.

Prerequisites

• Administrator access to Okta Admin Console
• Administrator access to rConfig V8
• rConfig server accessible via HTTPS with valid domain name

Configure Okta

Step 1: Create App Integration

In the Okta Admin Console, navigate to Applications > Create App Integration.

Step 2: Select Integration Type

When the wizard launches:

1. Select OIDC - OpenID Connect as the sign-in method
2. Select Web Application as the application type
3. Click Next

Step 3: Configure Application Settings

Fill out the application configuration form:

General Settings:

• App integration name: Choose a descriptive name (e.g., “rConfig V8”)

Grant type:

• Check Authorization Code
• Check Refresh Token

Sign-in redirect URIs:

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

Sign-out redirect URIs:

https://your-rconfig-domain.com

Assignments:

• Choose Controlled access based on your organization’s requirements
• Select the appropriate user or group assignments

Click Save to create the application.

Step 4: Assign Users or Groups

After the application is created:

1. Navigate to the Assignments tab
2. Click Assign and select Assign to People or Assign to Groups
3. Assign the users or groups that should have access to rConfig via SSO
4. Click Done

Step 5: Retrieve Configuration Details

From the application General tab, copy the following values:

• Client ID
• Client secret (click Show to reveal)

Step 6: Get Okta Base URL

1. Navigate to Security > API > Authorization Servers
2. Locate the Issuer URI for the default authorization server
3. Copy only the hostname portion (e.g., https://your-domain.okta.com)
4. Do not include /oauth2/default in the base URL

Configure rConfig V8

Step 1: Edit Environment Configuration

Open the rConfig .env file:

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

Step 2: Add Okta SSO Configuration

Add or update the following lines with your Okta application values:

OKTA_BASE_URL=https://your-domain.okta.com
OKTA_CLIENT_ID=your_client_id
OKTA_CLIENT_SECRET=your_client_secret
OKTA_REDIRECT_URI=https://your-rconfig-domain.com/auth/callback/okta

Configuration Parameters:

• OKTA_BASE_URL: Your Okta domain (hostname only, without /oauth2/default)
• OKTA_CLIENT_ID: Client ID from Okta application settings
• OKTA_CLIENT_SECRET: Client secret from Okta application settings
• OKTA_REDIRECT_URI: Must match the sign-in redirect URI configured in Okta

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 Okta button.

User Approval Process

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

1. User authenticates successfully with Okta
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 Okta 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 sign-in redirect URI registered in Okta and OKTA_REDIRECT_URI in .env (including trailing slashes or http vs https) causes authentication to fail.
• OKTA_BASE_URL must not include /oauth2/default. Use the hostname only (e.g. https://your-domain.okta.com); appending the authorization server path breaks the connection.
• A user must be assigned to the application in Okta, not just have an account. Being a valid Okta user isn’t enough, the application needs an explicit user or group assignment or login fails with “Access denied”.
• The cache must be cleared after every .env change. Run php artisan rconfig:clear-all after adding or updating the Okta 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 Okta and rConfig
• Confirm Okta base URL does not include /oauth2/default
• Check that the application is assigned to the user in Okta
• Ensure client secret has not been regenerated in Okta

“Access denied” error from Okta

• Verify user or group is assigned to the application in Okta
• Check that the application is active (not disabled)
• Confirm authorization server is active

Invalid redirect URI error

• Verify sign-in redirect URI in Okta matches exactly with OKTA_REDIRECT_URI in rConfig
• Ensure there are no trailing slashes or typos
• Check that HTTPS is used (not HTTP)

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