Skip to main content

​
Introduction

When your Guru runs inside SharePoint, the page itself can tell Gurubase who the visitor is. A page can claim anything, so those claims are never trusted for access decisions. This integration closes that gap. The SharePoint page obtains a token signed by Microsoft Entra ID, Gurubase verifies it server side, and the identity in that token replaces whatever the page said. The group memberships inside the verified token then decide which data sources the answer may draw on.
The Entra ID application this uses belongs to you, in your own tenant. Gurubase never holds credentials for your directory, and the token itself is never stored: it is verified, read, and discarded within the request.

​
What you need

  • A Microsoft 365 tenant with SharePoint Online.
  • Permission to upload a package to your tenant App Catalog and approve its API request, or someone who can.
No Microsoft Graph permission is needed, and in most tenants no app registration either: the Gurubase application is multi-tenant and already asks for the group claim, so a SharePoint administrator approves it once and that is the whole Entra side. Registering your own application stays available for tenants whose policy requires it.

​
Setup

1

Approve the Gurubase application, or register your own

Most tenants do not need an app registration at all. The Gurubase application is multi-tenant and already asks for the group claim, so a SharePoint administrator only has to approve it once:
  1. Upload the package (next step), which carries the permission request with it.
  2. In the SharePoint admin center, open Advanced → API access and approve Gurubase Ask AI / user_impersonation.
Then enter your own Directory (tenant) ID in Gurubase and use api://cb4a840d-b9e8-4fd9-96e7-b173018cc6c6 as the Application ID URI. Only tokens issued by the directory you name are accepted, so approving the application in your tenant never exposes it to another one.Gurubase holds no credentials for your directory either way: the application exposes a scope for SharePoint to request a token against, and nothing else.If your policy requires the application to live in your own tenant, register one instead and follow the step below.
2

Or: register your own application

In the Entra admin center, go to Applications → App registrations → New registration. Name it something recognisable, for example Gurubase Ask AI, and register it.On the app’s Overview page, copy the Directory (tenant) ID and the Application (client) ID.Then open Expose an API and set an Application ID URI. Accepting the default api://<client-id> is fine. Add a scope named user_impersonation so SharePoint can request a token on the user’s behalf.Finally, open Token configuration and add the groups claim, choosing Security groups. Without this the token carries no group memberships and every verified user falls back to sources visible to everyone.
3

Connect it in Gurubase

Open your guru, go to Integrations → Identity → SharePoint (Entra ID) and fill in:
  • Directory (tenant) ID — from the previous step. Only tokens issued by this directory are accepted.
  • Application ID URI — either the bare client ID or the full api:// form; both are accepted.
Leave Require verified identity off for now. See Enforcement below for when to turn it on.Click Connect.
4

Install the SharePoint package

The integration page has a download link for the Gurubase SharePoint package (gurubase-sharepoint.sppkg). Upload it to your tenant App Catalog and approve it for the whole tenant when prompted.To update later, download the package again and upload it to the App Catalog, replacing the existing file. The file name stays the same in every version, so the catalog updates the existing entry instead of adding a second one. The integration page shows the current version next to the download link.The package contains two components. The Application Customizer puts the assistant on every page in the tenant. The web part, listed as Gurubase Ask AI when you add a web part to a page, places it on one page only.
5

Approve the API request

After the package is deployed, open the SharePoint admin center and go to Advanced → API access. Approve the pending request for Gurubase Ask AI / user_impersonation.Until it is approved, SharePoint issues no token, so every visitor stays unverified. That looks exactly like the integration working, which is why Check a token reports it explicitly.
6

Point the package at the application

In the package configuration, set the identity resource to the same Application ID URI you entered in Gurubase. SharePoint then issues a token for that application on each page load and hands it to the assistant.Besides the identity resource, the package needs only the Widget ID. Button text, language, theme, colors and the other appearance options are set in the widget’s settings in Gurubase and apply without redeploying the package (package 1.7.0 or later).

​
Mapping directory groups to content groups

A verified token carries the user’s Entra ID security group IDs. To act on them, tell Gurubase which of your content groups each directory group corresponds to. Open Team → Groups, edit a group, and paste the directory group’s object ID into Directory group IDs, one per line. A group can map to several directory groups. Once mapped, a user whose verified token carries that directory group joins the content group for the duration of their request, and sees every data source scoped to it. See Groups & Content Access Control for how source visibility works. Anything not mapped is ignored: unknown IDs, IDs belonging to another guru’s groups, and tokens with no group claim all fall back to sources visible to everyone. Access is never widened by a value Gurubase does not recognise.
Entra ID replaces the groups claim with a pointer when a user belongs to more groups than fit in a token. Gurubase treats that case as “no groups” rather than guessing, and Check a token reports it explicitly, so it is not mistaken for a user who belongs to nothing.The fix is to emit fewer groups: in the application’s token configuration, choose Groups assigned to the application rather than all security groups, and assign the groups you actually map here. Filtering only helps below Entra’s limit of 1,000 group memberships per user; above it Entra sends the overage pointer regardless, and those users are answered from sources visible to everyone.

​
Has it reached anyone?

The integration page shows when a verified request last arrived, or says that none has. Until one does, the package has not reached anybody: the assistant still answers, from sources visible to everyone, which is why the absence is worth stating rather than leaving to be noticed.

​
Check a token

Setting this up spans two products, so a mistake is quiet: the assistant still answers, it just answers from sources visible to everyone. Rather than reading logs to find out why, paste a real token and let Gurubase tell you.
1

Get a token from the page

Open any SharePoint page carrying the assistant and add ?gurubaseIdentity=1 to the end of its URL. A small panel appears at the bottom left with a Copy diagnostics button. If your tenant blocks clipboard access, the panel puts the token in a selectable box instead.If the panel says no token was issued, the API permission request for the package is usually still waiting for approval in the SharePoint admin center, under Advanced → API access.
2

Check it in Gurubase

On Integrations → Identity → SharePoint (Entra ID), paste it under Check a token and press Run check. The token is not stored.
The answer names whichever of these applies:
  • the token is accepted, and which content groups it opens,
  • the directory group IDs it carries that no content group claims, which is the list to paste into a content group,
  • the group list was dropped because the user is in too many groups,
  • or why it was refused: the wrong tenant, the wrong audience, an expired token, or a signature that does not check out.
Only guru admins can run it, which is why the answer is this specific.

​
Who the caller is

With a valid token, the verified user is the caller on every widget endpoint, not only the one that answers. Whatever the page sent about the user is dropped, not merged:
  • The Entra user is the external_user_id for analytics, End-User Memory, and ownership of follow-up conversations.
  • The Entra username (the token’s preferred_username, usually the UPN) and display name reach Custom Actions as GURUBASE_USER_EMAIL and GURUBASE_USER_NAME. A UPN is not always a mailbox.
  • A ticket filed from the widget uses the Entra username and display name as its requester, whatever the ticket form says. If the UPN is not a mailbox, replies to the requester may not arrive.
Without a valid token, these fields come from the page and remain untrusted.

​
Enforcement

Require verified identity decides what happens to a request that arrives without a valid token. When it is on, every endpoint the assistant uses is covered, not only the one that answers: asking, follow-ups, voice input and playback, the guru’s own configuration, and ticket creation all refuse an unverified caller. Leave it off while the SharePoint package is still reaching people. Turning it on before everyone has it makes the assistant look broken for anyone who is missing it. Turn it on once rollout is complete and you want the assistant to answer only people the directory can vouch for.
A token lasts about an hour, and an intranet tab often stays open longer than that. The SharePoint package refreshes the token in the background while the tab is open, so a long-lived page keeps working rather than starting to refuse mid-conversation. This needs package 1.6.3 or later.
Disconnecting the integration stops all verification. Every request then falls back to sources visible to everyone, including requests that would previously have been rejected. Gurubase asks for confirmation before disconnecting for exactly this reason.

​
What gets verified

For every token, Gurubase checks that:
  • the signature matches Microsoft’s published signing keys for the tenant,
  • the tenant matches the Directory (tenant) ID on the integration,
  • the audience matches the Application ID URI on the integration,
  • the issuer belongs to that same tenant,
  • the token has not expired.
A token that fails any of these is treated as absent, not as an identity. Failures are logged without the token value. When Require verified identity is on, the refusal tells the widget what is missing, so the visitor sees “this assistant needs to confirm who you are” rather than a message about an invalid widget ID.