Single Sign-On with Azure AD (OIDC) — Setup Guide

This is the recommended way to set up Single Sign-On in Activate LMS. It uses OpenID Connect (OIDC) against Microsoft Azure AD / Microsoft Entra ID, with MSAL.js handling the browser flow. On-premise ADFS is still supported through the existing bridge-site solution, but new setups should always use Azure AD OIDC.

How it works

1. A user opens the Activate LMS login page.
2. They click Log in with SSO (or are redirected automatically if SSO-only is enabled).
3. The browser is sent to Microsoft sign-in.
4. The user signs in with their Azure AD account.
5. Microsoft returns an ID token to Activate LMS.
6. The Activate LMS Frontend API validates the token against Azure AD metadata (signature, issuer, audience, lifetime) and extracts the username from a configured claim.
7. If the user exists in the LMS, they are logged in. If they don't and auto-provisioning is enabled, the user is created automatically from the token data.
8. The user receives a JWT session token (7-day lifetime) and is logged in.

What IT needs to provide to the LMS administrator

Before SSO can be configured in Activate LMS, your IT department must register an application in Azure AD and provide the following:

Field	Description
Tenant ID	Your Azure AD tenant GUID. Found in Azure Portal under Entra ID → Overview.
Client ID (Application ID)	The Application (client) ID for the App Registration you create for Activate LMS.
Authority URL	Typically https://login.microsoftonline.com/{tenant-id}. Activate LMS appends /v2.0 automatically if it is missing.
Username claim	The claim used to identify the user — usually preferred_username (UPN) or email. See Choosing the username claim below.

Setting up the App Registration in Azure AD

These steps are performed by an Azure AD administrator in the Azure Portal.

Step 1: Create the App Registration

1. Sign in to https://portal.azure.com.
2. Go to Microsoft Entra ID → App registrations → New registration.
3. Give the app a descriptive name, e.g. "Activate LMS".
4. For Supported account types, choose "Accounts in this organizational directory only" (single tenant) unless you have a specific reason to do otherwise.
5. Under Redirect URI, choose platform Single-page application (SPA) — this is critical; do not choose "Web". Then enter the URL of your Activate LMS frontend with /authentication/login appended, following this pattern:

   https://<your-LMS-domain>/authentication/login

   For example: https://customer.activatelms.com/authentication/login or https://learning.yourcompany.com/authentication/login. Your LMS administrator can confirm the correct domain.
6. Click Register.

Multiple frontends: If you have additional Activate LMS frontends — for example a test/staging domain or a local development host — each one needs its own SPA Redirect URI added in the same place, following the same /authentication/login pattern. You can add multiple Redirect URIs under the same App Registration; do it now (or later under Authentication → Single-page application → Add URI).

Common mistakes that cause sign-in to fail:

• Choosing the "Web" platform instead of "Single-page application".
• Omitting the /authentication/login path from the Redirect URI.
• Forgetting to add a Redirect URI for an additional frontend domain (staging/dev).

See the Common errors table below if you see AADSTS900971 or AADSTS50011 after Microsoft sign-in.

Step 2: Configure authentication

1. Inside the new App Registration, go to Authentication.
2. Under Implicit grant and hybrid flows, enable ID tokens. Do not enable Access tokens.
3. Confirm the Supported account types setting from Step 1.
4. Save.

Step 3: Configure token claims (recommended)

By default, Azure AD ID tokens include preferred_username and email. If you want Activate LMS to auto-create users with the correct first and last names, add the following optional claims:

1. Go to Token configuration → Add optional claim.
2. Select ID as the token type.
3. Add: given_name, family_name, email.
4. To map job titles to learning profiles automatically, also add: jobTitle.
5. Save.

If given_name and family_name are not added, Activate LMS falls back to splitting the full name claim at the first space — which works for most people but may produce wrong results for users with several middle names.

Step 4: API permissions

The default User.Read permission is sufficient — it lets the app read the signed-in user's own profile. Admin consent is not required; it is granted automatically when the user first signs in.

Step 5: Hand over to the LMS administrator

Once the App Registration is in place, provide your LMS administrator with:

• The Tenant ID (Overview tab)
• The Client ID / Application ID (Overview tab)
• The Authority URL: https://login.microsoftonline.com/{tenant-id}
• The chosen username claim (usually preferred_username)
• Confirmation that ID tokens are enabled under Authentication

Configuring SSO in Activate LMS

This part is performed by the LMS administrator, not by IT. It is described here so IT understands what their information is used for.

The LMS administrator goes to Settings → Single Sign-On and creates a new SSO configuration with these fields:

Field	Value
Name	A descriptive name, e.g. "Azure AD / OIDC".
Organisation	Optional — if set, SSO applies only to users in the selected organisation. If blank, SSO is active for all users in the domain.
Tenant ID	Provided by IT.
Client ID	Provided by IT.
Authority	Provided by IT.
Username claim	The claim that uniquely identifies the user (normally preferred_username).
Create users automatically	If enabled, unknown users who sign in via SSO are created automatically in the LMS.
Organisation code for auto-creation	Only relevant if auto-creation is enabled. Specifies which organisation new users are placed in.
SSO only	If enabled, password login is disabled for this organisation. Users can only sign in via SSO.
Automatic SSO	If enabled, the user is redirected to SSO automatically without having to click the button.
Active	Must be enabled for the configuration to take effect.

Choosing the username claim

Activate LMS uses one claim from the Azure AD token to match the user in the LMS. The right choice depends on how usernames are structured in your LMS:

Claim	Contains	When to use
preferred_username	The user's UPN, e.g. anne@company.com	Recommended default. Works when LMS usernames are email-formatted.
email	The user's primary email address	When UPN and email differ, and the LMS uses email as the username.
upn	Same as preferred_username but under the older claim name	Only needed in specific compatibility scenarios.

Activate LMS matches the claim value against the user's UserName in the LMS database. If your Azure AD UPNs do not match LMS usernames exactly, either rename the LMS users or enable auto-creation so new users are created with the correct identifier.

Auto-provisioning

If Create users automatically is enabled, users who sign in for the first time are created in the LMS. Activate LMS attempts to populate the following fields from token claims:

LMS field	Token claim	Fallback if missing
Username	The configured claim (typically preferred_username)	Error — user cannot be created.
First name	given_name	Split of name at the first space.
Last name	family_name	Everything after the first space in name.
Email	email	Use preferred_username if it looks like an email.
Learning profile	jobTitle	Falls back to "Default".
Organisation	(set in SSO configuration)	Required — must be set by the LMS administrator.

If auto-provisioning is enabled, the claims given_name, family_name, email and optionally jobTitle should be added as optional claims in Azure AD (see Step 3 above). Otherwise users may be created with incomplete data.

Testing and troubleshooting

First test

After setup, both IT and the LMS administrator should verify that SSO works. Ask a test user to:

1. Open the LMS login page in a new incognito browser (to avoid cached sessions).
2. Click Log in with SSO.
3. Confirm they are sent to Microsoft sign-in.
4. Sign in with their Azure AD account.
5. Confirm they land on the LMS home page and see their own name in the top-right corner.

Common errors

Error or symptom	Cause	Fix
"Invalid SSO token"	The token could not be validated against Azure AD metadata — usually because Authority or Client ID don't match.	Verify that Tenant ID and Client ID in the LMS configuration match the App Registration exactly.
"Could not extract username from SSO token"	The configured username claim is missing from the token.	Change the claim choice in the LMS configuration, or add the missing claim as an optional claim in Azure AD.
"SSO is not configured for this tenant"	There is no active SSO configuration for the LMS domain the user is signing in to.	The LMS administrator must enable the configuration under Settings → Single Sign-On.
User gets "Not found" after signing in to Microsoft	The user does not exist in the LMS and auto-provisioning is not enabled.	Either create the user manually in the LMS, or enable auto-provisioning.
User signs in but ends up at the login page again	Third-party cookies are blocked, or the JWT was not stored correctly.	Check the browser console for errors. Try a fresh incognito session.
AADSTS900971: No reply address provided (after Microsoft sign-in)	The App Registration has no Redirect URI configured for the LMS frontend, or the platform type is "Web" instead of "Single-page application".	In Azure Portal → App Registration → Authentication, click Add a platform, choose Single-page application, and add the URI https://<your-LMS-domain>/authentication/login. Each frontend domain needs its own entry.
AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application	A Redirect URI exists, but it doesn't match the URL the user is signing in from — usually because the path or domain is wrong, or it's registered under the "Web" platform instead of SPA.	Verify the Redirect URI matches the LMS frontend URL exactly, including the /authentication/login path, and that it lives under the Single-page application platform. Add an additional entry if you have multiple frontends (e.g. staging).

Logs and diagnostics

If deeper troubleshooting is needed, request logs from the Activate LMS Frontend API. For SSO errors the following is logged:

• The DomainID the token was validated against
• The claim value that was extracted
• The claim type that was used
• A list of all available claims in the token (helps identify the correct claim name)

References

• Microsoft Entra ID (Azure AD) documentation: https://learn.microsoft.com/entra/identity
• OpenID Connect specifications: https://openid.net/connect
• MSAL.js documentation: https://learn.microsoft.com/entra/identity-platform/msal-overview