Fix Custom Claims Issues in SharePoint Online Tokens

Learn why you cannot add custom claims directly to SharePoint Online tokens using an Entra Enterprise App, and discover Microsoft Graph API workarounds.

Dealing with Azure AD or Entra ID token configurations can be frustrating, especially when your application relies on passing specific user data to function correctly.

Problem Description: Custom Claims Insertion Failure

Developers and IT administrators often attempt to inject custom claims or extension attributes into SharePoint Online web client tokens using solely a Microsoft Entra Enterprise Application. However, this configuration is fundamentally unsupported. As a result, the application fails to read the expected data, causing authorization errors or missing user profile information within the SharePoint environment.

Quick Answer for Entra ID Token Limitations

You cannot directly add a custom claim to a SharePoint Online web client token using only an Enterprise Application. You must either utilize an App Registration with a dedicated Application ID (appId) or dynamically fetch the required additional user data via the Microsoft Graph API.

Likely Causes Behind SharePoint Authentication Restrictions

• Architecture Limitations: Microsoft Entra Enterprise Applications alone do not support custom claim mapping natively for SharePoint Online web clients.
• Missing App Registration: Custom claims and extension attributes strictly require a fully registered application with a unique appId within your tenant.
• Strict Security Policies: SharePoint Online enforces rigid token validation protocols, actively ignoring unverified extensions attached purely via Enterprise App SAML or OAuth configurations.

Recommended Solution: Implementing Microsoft Graph Data Fetching

1. Authenticate the user into SharePoint Online using standard Microsoft Entra ID credentials without attempting to pass the custom claim in the initial token.
2. Acquire a secondary access token specifically for the Microsoft Graph API, ensuring you request the appropriate scopes (such as User.Read or Directory.Read.All).
3. Make a secure REST API call to Microsoft Graph endpoints to retrieve the required extension attributes or custom profile data.
4. Store and cache the retrieved data locally within your application's active session, securely mimicking the behavior of a custom claim without violating organization security policies.

Alternative Solutions for App Identity Configurations

1. Navigate to the Microsoft Entra admin center and create a new App Registration instead of relying solely on an Enterprise Application.
2. Configure your required extension attributes and custom claims under the App Registration's Token Configuration or directly within its JSON manifest.
3. Assign the newly generated appId (Client ID) to your SharePoint environment.
4. Update your application code's authentication flow to utilize this new Client ID, enabling the native passing of custom claims.

Working with WPS Office: A Reliable Desktop Alternative

While WPS Office cannot resolve backend Microsoft Entra ID or SharePoint token authentication issues, it stands as an excellent offline alternative for document management. If cloud authentication errors temporarily block your team from accessing critical SharePoint files, WPS Office is a robust, free suite that seamlessly creates, opens, edits, and saves local Microsoft Office documents (.docx, .xlsx, .pptx). It allows your team to maintain productivity locally without requiring complex cloud identity configurations.

Prevention Tips for Secure Token Management

• Always establish full App Registrations early in the development cycle when your architecture requires custom user attributes.
• Regularly review Microsoft Entra's token limits and supported claim mapping policies before deploying new SharePoint integrations.
• Keep Microsoft Graph API permissions strictly scoped to the principle of least privilege to maintain organizational security compliance.

FAQs About SharePoint and Entra ID Tokens

Can I force custom claims through SAML instead of OAuth for SharePoint Online?

SharePoint Online primarily relies on modern authentication. While SAML claims mapping exists for external identity providers, attempting to pass custom attributes via Entra ID Enterprise Apps to a modern SharePoint web client still faces the same strict architectural restrictions. Utilizing Graph API remains the safest workaround.

Does fetching data via Microsoft Graph API slow down the user login process?

Fetching profile data via Microsoft Graph does add a minimal HTTP request delay during the initial login. However, by implementing secure server-side or session caching for the user, subsequent requests will remain incredibly fast, and the user experience will not be noticeably impacted.