OIDC SSO Setup Guide for Microsoft Entra ID

This guide explains how to configure Microsoft Entra ID (OIDC) Single Sign-On (SSO) for AgileSec Platform, enabling users to authenticate using their Microsoft work accounts. It covers prerequisites, setup steps, testing, and troubleshooting for secure federated login.

1. Overview

This guide will help you configure Microsoft Entra Id OIDC ingle Sign-On (SSO) for your AgileSec Platform. With Microsoft SSO enabled, users in your organization can log in to AgileSec using their Microsoft work accounts.

Important Notes

• This configuration requires cloud-based Microsoft Entra ID. If your organization only uses on-premises Active Directory, you'll need Azure AD Connect to sync users to the cloud first.

• Users must already exist in AgileSec before they can log in with Microsoft SSO

• The email address in AgileSec must match the user's Microsoft email exactly

• Automatic user creation is not supported

2. Prerequisites

Before you begin, ensure you have:

• Administrator access to your Microsoft Azure Portal

• Administrator access to your AgileSec Platform

• Cloud-based Microsoft Entra ID (Azure AD) or a hybrid setup with Azure AD Connect

• Users already created in AgileSec with matching email addresses

3. Setup Entra ID

3.1 Create an App Registration

1. Sign in to the Microsoft Azure Portal

2. Go to Azure Active Directory (Microsoft Entra ID)

3. Select App registrations from the left menu

4. Click New registration

5. On Register an Application screen enter following:

   1. Name: Keyfactor AgileSec

   2. Supported Account Types: Select an option based on your preference.

   3. Redirect URI:

      1. Select platform: Web

      2. Enter: https://<analytics fqdn>/api/auth/callback/azure-ad

6. Click Register

3.2 Configure Authentication

1. In your app registration, click Authentication in the left menu

2. Under Implicit grant and hybrid flows, check:

   • ☑ ID tokens (used for implicit and hybrid flows)

3. Click Save

3.3 Create a Client Secret

1. Click Manage → Certificates & secrets in the left menu

2. Under Client secrets, click New client secret

3. Add a description: "Keyfactor AgileSec SSO"

4. Select expiration period: 12 months (recommended)

5. Click Add

6. Copy the Secret ID. ⚠️ Save this securely - you cannot retrieve it later. This will be your AZURE_AD_CLIENT_SECRET.

3.4 Configure API Permissions

1. Click Manage → API permissions in the left menu

2. Verify User.Read (Microsoft Graph) is listed

3. Click Add a permission if additional permissions are needed

4. If required by your organization:

   • Click Grant admin consent for [Your Organization]

   • Click Yes to confirm

3.5 Gather Configuration Values

From the Overview page, copy these values:

Note: If you selected "Multiple organizations" in Step 2, you can use common instead of your specific Tenant ID.

4. Setup AgileSec Platform

4.1 Update Web Configuration

• Configure the following environment variables for AgileSec Frontend Web in config_envs/webui

• Restart web service to apply the above settings change.

4.2 Test SSO Integration

Before testing, confirm:

• Users exist in AgileSec with email addresses matching their Microsoft accounts

• User accounts are active and properly configured

• Users have appropriate roles and permissions in AgileSec

Test SSO:

1. Log out of AgileSec if currently logged in

2. Go to your AgileSec login page

3. Click the button

4. You'll be redirected to Microsoft's login page

5. Sign in with your Microsoft account

6. Review and accept permissions if prompted

7. You should be redirected back to AgileSec and automatically logged in

5. Troubleshooting

5.1 Redirect URI mismatch Error

Symptoms: Error message about redirect URI not matching

Solutions:

• Verify the redirect URI in Azure matches exactly: https://<analytics fqdn>/api/auth/callback/azure-ad

• Check for http vs https

• Check for trailing slashes

• Ensure the domain name is spelled correctly

5.2 User not found Error

Symptoms: Login succeeds at Microsoft but fails in AgileSec

Solutions:

• Verify the user exists in AgileSec

• Confirm email addresses match exactly in both systems

• Check that the user account is active in AgileSec

• Have an administrator verify the user in AgileSec settings

5.3 Unauthorized or Permission denied Error

Symptoms: Cannot complete login process

Solutions:

• Verify User.Read permission is granted in Azure

• Check if admin consent is required and granted

• Review your organization's Azure AD policies

• Contact your IT department about tenant restrictions

5.4 Invalid client secret Error

Symptoms: Authentication fails with client secret error

Solutions:

• Verify you copied the secret Value, not the Secret ID

• Check if the secret has expired

• Create a new client secret in Azure

• Update the AgileSec configuration with the new secret

Users Cannot See the Microsoft Sign-In Button

Symptoms: Microsoft SSO button not visible on login page

Solutions:

• Verify SSO is enabled in AgileSec settings

• Check that the configuration was saved correctly

• Clear browser cache and try again

• Contact your AgileSec administrator

6. Maintenance

6.1 Client Secret Expiration

Client secrets expire based on the duration selected during creation. Set a reminder and renew before expiration:

1. Go to Azure Portal → Your app registration → Certificates & secrets

2. Create a new client secret

3. Copy the new secret value

4. Update the configuration in AgileSec

5. Test login with the new secret

6. Delete the old secret only after confirming the new one works

Recommendation: Set a calendar reminder 30 days before expiration.

6.2 Redirect URIs

If your AgileSec domain changes:

1. Update the Redirect URI in Azure app registration

2. Update the configuration in AgileSec

3. Test the login flow thoroughly

4. Notify users of any changes