AITS: Single Sign-On (SSO) Fails for Microsoft Teams for Employee Service (Salesforce IT Service / IT Desk)

The following configurations should be validated in the order presented, as earlier items are prerequisites for later ones. All values must match exactly, including protocol, case, and the absence of trailing slashes.

1. Confirm the feature is enabled

Navigate to Salesforce Go → Feature Sets → Deliver IT Services Across Channels → Microsoft Teams for Employee Service and confirm the feature is turned On. SSO cannot function unless this feature is enabled.

2. Verify the External Client App

Navigate to Setup → External Client App Manager and confirm an application named ServiceCloudTeamsEca exists.

If it is missing:

1. Turn on the Microsoft Teams for Employee Service feature from Salesforce Go.
2. Confirm the application appears in External Client App Manager.
3. If the feature was already enabled, turn it off and on again to re-provision the application.

3. Verify the preferred Experience site

Navigate to Setup → Digital Experiences → All Sites and confirm:

• The intended site exists.
• The site status is Live (not "Down" or "Under Construction").
• The site's full URL (base domain plus path prefix, for example https://example.my.site.com/ITSMPortal) is recorded, as it is required when validating the Microsoft Entra ID app registration in later steps.

If misconfigured, configure and publish the preferred site and ensure it is Live.

4. Verify the Microsoft authentication provider

Navigate to Setup → Auth. Providers → microsoft_auth_provider and confirm the following values:

Note: The Registration Handler and Execute Registration As values are specific to SSO and are the most commonly overlooked settings.

If misconfigured:

1. Edit microsoft_auth_provider.
2. Set Registration Handler Type to Apex class.
3. Set Registration Handler to MsTeamsItsmSSOHandler.
4. Set Execute Registration As to a user with the System Administrator profile.
5. Save.

5. Verify the Microsoft Entra ID application registration

This step requires the Microsoft Entra ID Tenant ID and access to the Microsoft Entra admin center (Azure Portal). Navigate to App Registrations and open the Teams application, then confirm:

• Supported account types is set to Multitenant.
• The Client ID matches the Consumer Key configured in the Salesforce authentication provider (Step 4).
• The Redirect URIs (Authentication section) include both of the following, constructed from the org domain and the Experience site full URL from Step 3:
  • Org callback: https://<org-domain>/services/authcallback/microsoft_auth_provider
  • Site callback: https://<site-domain><site-path>/services/authcallback/microsoft_auth_provider
• The API Permissions include Organization.ReadWrite.All (Application permission) with admin consent granted.

If misconfigured:

1. In Authentication, add the two redirect URIs above as exact matches with no trailing slashes.
2. Set Supported account types to Multitenant.
3. In API Permissions, add Organization.ReadWrite.All (Application) and grant admin consent.

Note: If the Tenant ID is unavailable, this validation must be performed manually in the Microsoft Entra admin center.

6. Verify the Named Credential and External Credential

These configurations allow Salesforce to call Microsoft Graph.

Navigate to Setup → Named Credentials → MSGraphApplicationNC and confirm:

Navigate to Setup → Named Credentials → External Credentials → MSTeamsClientCredentialsEC and confirm:

Important: In the Identity Provider (Token) URL, the <tenant-id> placeholder must be replaced with the actual Microsoft Entra ID Tenant ID (for example, https://login.microsoftonline.com/22d62500-afdf-49d5-9bcf-c9341bb96c51/oauth2/v2.0/token). This is a common oversight — if the literal <tenant-id> text is left in place, authentication to Microsoft Graph will fail.

If the Authentication Status is not "Configured":

1. Open External Credentials → MSTeamsClientCredentialsEC → Principals → NamedAuthPrincipal.
2. Under Authentication Parameters, set the Client ID and Client Secret from the Microsoft Entra ID application registration.
3. Save.

If other settings are incorrect (URL, scope, linked External Credential, or token endpoint), correct each value to match the tables above.

7. Verify the SSO registration handler Apex class

Navigate to Setup → Apex Classes → MsTeamsItsmSSOHandler and confirm the class exists and its Status is Active.

• If the class is missing, it is delivered with the Teams for Employee Service managed package; verify the package is installed and current.
• If the class is inactive, open it, edit it, set Status to Active, and save.

8. Verify user mapping (Salesforce Username matches Microsoft email)

This step requires the affected user's Salesforce username. The SSO registration handler maps the Microsoft identity to the Salesforce user by matching the email address returned by Microsoft Entra ID against the Salesforce Username field. The user must already exist in Salesforce — the handler does not create new users. Navigate to Setup → Users and open the affected user, then confirm:

• The user is Active.
• The Salesforce Username exactly matches the user's Microsoft Entra ID email address, for example user@example.com.

If the Username does not match the Microsoft email address, the mapping fails and the user cannot sign in. Ensure the Salesforce Username is set to the exact email address the user authenticates with in Microsoft Entra ID.

Note: When SSO fails for only a subset of users, this is the most likely cause and should be verified for each affected user. The Federation ID field is not used by this handler and does not need to be set for SSO mapping.

Application-specific validations

The SSO backend configuration is shared, but the target application has additional prerequisites. If all SSO validations above pass, the following application-specific settings should also be confirmed.

For Salesforce IT Desk (fulfiller) users

• Setup → CORS: "Enable CORS for OAuth endpoints" is enabled.
• CORS Allowed Origins includes both https://cdn.scs.static.lightning.force.com and https://teams.cloud.microsoft.
• The Microsoft Teams for Employee Service feature is enabled.
• The Salesforce IT Desk feature is enabled.
• The affected user has the Microsoft Teams for IT Services permission set license assigned.

For Salesforce IT Service (employee) users

• CORS and Allowed Origins as above.
• The Microsoft Teams for Employee Service feature is enabled.
• The Salesforce IT Service feature is enabled.
• For Customer Community Plus (CCP) users: the affected user has the API Enabled permission (via profile or permission set).
• For Unified Employee Login (UEL) users: the Unified Employee profile has "Allow OAuth for employees" enabled (Profile → Session Settings), and the affected user has the Teams for Employee permission set license assigned.