SSO with Microsoft Entra ID

This guide covers the configuration of Single Sign-On (SSO) authentication for rConfig V8 using Microsoft Entra ID (formerly Azure AD). You create an application registration in Microsoft, copy three values into the rConfig .env file, and approve the first user who signs in. For what SSO gives you and which Microsoft clouds are supported, start with the Microsoft SSO overview.

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

• Administrator access to the Microsoft portal for your cloud: portal.azure.com for commercial tenants, portal.azure.us for GCC High and DoD tenants
• Administrator access to rConfig V8, and shell access to edit .env on the rConfig server
• rConfig server accessible via HTTPS with valid domain name
• rConfig V8.3.3 or later if your tenant is in GCC High, DoD or China. Earlier releases can only sign in commercial tenants

Configure Microsoft Azure

Step 1: Create App Registration

Navigate to Azure Portal > App registrations and click New registration.

GCC High and DoD tenants do this in the Azure Government portal at portal.azure.us, not portal.azure.com. The screens are the same, the tenant is not.

Configure the application registration:

• Name: Choose a descriptive name (e.g., “rConfig V8”)
• Supported account types: Select the appropriate option for your organization
• Redirect URI: Select Web and enter:

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

Click Register to create the application.

Step 2: Note Application Details

After registration, copy the following values from the Overview page:

• Application (client) ID
• Directory (tenant) ID

Step 3: Create Client Secret

1. Navigate to Certificates & secrets
2. Click New client secret
3. Add a description (e.g., “rConfig V8 Secret”)
4. Select an expiration period
5. Click Add
6. Copy the Value immediately (you won’t be able to view it again)

Configure rConfig V8

Step 1: Edit Environment Configuration

Open the rConfig .env file:

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

Step 2: Add Microsoft SSO Configuration

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

MICROSOFT_CLIENT_ID=your_application_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret_value
MICROSOFT_REDIRECT_URI=https://your-rconfig-domain.com/auth/callback/microsoft
MICROSOFT_TENANT_ID=your_tenant_id

# New in V8.3.3. Microsoft cloud the tenant lives in: commercial (default), gcc-high, dod or china
MICROSOFT_CLOUD=commercial

Configuration Parameters:

• MICROSOFT_CLIENT_ID: Application (client) ID from Azure
• MICROSOFT_CLIENT_SECRET: Secret Value created in Step 3
• MICROSOFT_REDIRECT_URI: Must match the redirect URI configured in Azure
• MICROSOFT_TENANT_ID: Directory (tenant) ID from Azure (required for single-tenant configurations)
• MICROSOFT_CLOUD: New in V8.3.3. The Microsoft cloud your tenant is in. Leave it as commercial unless you are in GCC High, DoD or China. On V8.3.2 and earlier this key does nothing

Step 3: Choose your Microsoft cloud

MICROSOFT_CLOUD decides which Microsoft hosts rConfig talks to. Get it wrong and the sign-in redirect goes to an authority that does not know your tenant, so the login never comes back.

New in V8.3.3

MICROSOFT_CLOUD, MICROSOFT_LOGIN_ENDPOINT and MICROSOFT_GRAPH_ENDPOINT were all added in V8.3.3. Every release before it sent logins to login.microsoftonline.com and read profiles from graph.microsoft.com, with no setting to change either, so GCC High, DoD and China tenants could not complete a sign-in at all.

Upgrading from an earlier release? Nothing to do if your tenant is commercial. commercial is the default and your existing logins keep working whether or not the key is present in .env. Add it only when you move to a sovereign cloud.

MICROSOFT_CLOUD	Sign-in host	Microsoft Graph host
commercial (default)	login.microsoftonline.com	graph.microsoft.com
gcc-high	login.microsoftonline.us	graph.microsoft.us
dod	login.microsoftonline.us	dod-graph.microsoft.us
china	login.chinacloudapi.cn	microsoftgraph.chinacloudapi.cn

Both hosts have to be reachable outbound from the rConfig server, so use this table when you open firewall or proxy allowlists.

Caution

GCC Moderate tenants are hosted in the commercial cloud and keep commercial. Only GCC High and DoD tenants use the .us endpoints. If your users sign in at login.microsoftonline.com today, leave this setting alone.

Note

For a Microsoft cloud not listed above, or a deployment that reaches Microsoft through your own hostnames, set MICROSOFT_LOGIN_ENDPOINT and MICROSOFT_GRAPH_ENDPOINT instead. Both take a full host such as https://login.internal.example.mil and override the MICROSOFT_CLOUD preset.

Step 4: 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 Microsoft button.

User Approval Process

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

1. User authenticates successfully with Microsoft
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 Apache error logs for configuration issues

Login redirects to the wrong Microsoft domain

If you are on GCC High or DoD and the browser lands on login.microsoftonline.com instead of login.microsoftonline.us, the cloud setting has not taken effect:

• Confirm you are running V8.3.3 or later. Earlier releases always used the commercial endpoints
• Check MICROSOFT_CLOUD=gcc-high (or dod) is set in .env with no typo. An unrecognised value falls back to commercial rather than failing outright
• Re-run php artisan rconfig:clear-all. The cached config and event map are both rebuilt by it, and a stale cache keeps the old behaviour

The user account will not appear in Users while this is happening. The sign-in never returns to rConfig, so there is nothing yet to approve.

Authentication fails

• Verify redirect URI matches exactly between Azure and rConfig
• Confirm client secret has not expired in Azure
• Check that tenant ID is correct for single-tenant applications
• For GCC High and DoD, confirm the app registration was created in the Azure Government portal (portal.azure.us) and not the commercial one

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

• Microsoft SSO Overview - Supported Microsoft clouds and what SSO gives you
• SSO Overview - Understanding SSO in rConfig V8
• User Management - Managing user accounts and approvals
• Role-Based Access Control - Configuring user roles and permissions