Set Up Forage for Copilot

Purpose: let Microsoft Copilot search Forage and read the text of the files it holds, for records administrators and, if you wish, for staff who then see only the files they can open in SharePoint. See Forage for Copilot for what it does.

What you need

• Squirrel and Forage running for your tenant, with SharePoint sites included and some files read.
• The Squirrel portal reachable over the internet at an HTTPS address with a proper certificate. Copilot calls Forage from Microsoft's cloud, so a private address will not do.
• Copilot Studio in your tenant. A trial is enough for testing.
• An administrator account that can register apps and grant admin consent: Cloud Application Administrator or Global Administrator.
• Two test accounts: one records administrator, and one ordinary user who can open some sites but not others.

Set it up on a test tenant first, with a Forage that reads that tenant's own files. A Copilot in one tenant must never be given another tenant's files.

1. Register the app. In the Microsoft Entra admin center, open App registrations, then New registration. Name it Forage for Copilot, choose accounts in this organisational directory only, and leave the redirect address empty for now. Note the Application (client) ID and the Directory (tenant) ID.
2. Expose an API. Set the Application ID URI (the suggested api://<client id> is fine) and add a scope named Forage.Read. Let admins only consent, with the admin consent display name Read Forage.
3. Create the two roles. Under App roles, create two roles, each allowed for Users/Groups:
   • Forage.RecordsAdmin, shown as Forage records administrator: sees every file Forage holds.
   • Forage.User, shown as Forage user: sees only the files the person can open in SharePoint.
4. Set the token version. In the Manifest, set requestedAccessTokenVersion (in older views, accessTokenAcceptedVersion) to 2 and save.
5. Add the permissions and grant admin consent for all three. These are delegated permissions, so Forage can only ever see what the signed-in person could see themselves:
   • My APIs, Forage for Copilot: Forage.Read.
   • Microsoft Graph: User.Read, to find which groups a person is in. It is usually there already.
   • SharePoint: AllSites.Read, to ask SharePoint whether a person can open a file.
6. Create a client secret. Under Certificates & secrets, choose New client secret with an expiry you will remember to renew. It goes into Copilot Studio (step 10) and, for staff access, into Forage's settings (step 9). Copy it straight into those two places and nowhere else.
7. Create two security groups. One for the people who see every file (the portal's administrators group can serve), and Forage Copilot Users for the staff who may use Copilot with Forage. Adding or removing a person is done in these groups, in Entra, like any other group.
8. Assign the groups. In Enterprise applications, open Forage for Copilot. Under Properties, set Assignment required to Yes, so nobody can sign in unless they are in a group assigned to it. Under Users and groups, add the records administrators group with the role Forage records administrator, and Forage Copilot Users with the role Forage user.
9. Give Forage its side of the settings. SmiKar support sets these on the portal with you: your directory (tenant) ID, the app's client ID, and, for staff access, the client secret and your SharePoint address (https://<tenant name>.sharepoint.com). Until the staff settings are in, a Forage user is told Forage for Copilot is open to records administrators only. Forage's read service is restarted once afterwards.
10. Switch on the Site Access check. Staff access needs to know who can open each site Forage reads. A nightly check reads that from SharePoint, reading only, for every site Forage reads, and again for a newly included site. Until its first check is done, staff are told Forage has not yet checked who can open each site. The Records page Site Access shows what it found: see see who can open each site.
11. Add Forage to Copilot Studio. Create an agent, for example "Ask our records", and say in its instructions that it answers from Forage and names the files it used. Under Tools, choose Add a tool, New tool, Model Context Protocol, then:
    • Server URL: the Forage for Copilot address on your portal, which SmiKar support gives you.
    • Authentication: OAuth 2.0, entered by hand, with the client ID and client secret from step 6.
    • Authorization URL: https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/authorize.
    • Token URL and refresh URL: https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token.
    • Scopes: api://<client id>/Forage.Read offline_access.
12. Add the redirect URL. Copilot Studio shows a redirect URL. In the app registration, open Authentication, Add a platform, Web, paste it as a redirect URI and save.
13. Sign each user in separately. Make sure the connection signs each user in with their own account, not one shared account. With a shared account everyone would see what that one account sees.
14. Keep the agent to Forage. Give the agent no other tools that send email or change things, so the text of a file can never be turned into an action.
15. Publish the agent to Teams or Microsoft 365 Copilot for the test accounts.

Check that it works

• As the records administrator: ask the agent about something you know is in the files. It should name the files and quote from them. Ask about an archived file: it should read the whole text, not a summary.
• In the Log: each search and each file Copilot opened is there under your name.
• As the ordinary user: ask about something in a site they can open, and something in a site they cannot. The first is found. The second is not found, and the agent does not name it. Ask the agent to read a file ID the administrator found in that second site: it says Forage could not find that file. An archived file in a site they can open is found and read in full.
• Someone not assigned to the app cannot sign in to the tool at all.
• Site Access: open a site you know on the Site Access page and check its people and groups match SharePoint's own Site permissions. Share one file on a site with a test user who is not a member. After the next night's check, that user is listed for the site under Shared items only, and Copilot finds that file for them and nothing else on the site.

When something goes wrong

What the agent says	Why	What to do
Forage for Copilot is not set up on this portal	The portal is missing your tenant ID or the app's client ID	Ask SmiKar support to complete step 9
Sign in to use Forage	No sign-in was sent	Check the tool's authentication in Copilot Studio
The sign-in is from another organisation	The sign-in belongs to a different tenant	Check the tenant ID, and that the test accounts belong to this tenant
The sign-in token was not made for Forage	The sign-in is for another app	Check the scope in Copilot Studio is api://<client id>/Forage.Read
The sign-in has expired	The sign-in is old	Sign in again in Copilot, and check the server's clock
Forage answers a person who is signed in, never an app on its own	Copilot Studio is using a sign-in with no person behind it	Use OAuth with the user's own sign-in
You do not have access to Forage for Copilot	The person holds neither role	Check step 8. It can take a few minutes, and a fresh sign-in, to apply
Forage for Copilot is open to records administrators only for now	A Forage user, but the staff settings are missing	Complete the staff settings in step 9
Forage could not check your access in SharePoint	A wrong or expired client secret, or admin consent not granted for the Graph and SharePoint permissions	Check steps 5 and 6, then step 9
Forage has not yet checked who can open each site	The Site Access check is not switched on, or has not finished its first pass	Check step 10
Forage could not find that file	For staff, the file does not exist in Forage or they cannot open it in SharePoint (the same answer, on purpose)	Nothing, if they should not see it
Too many requests in a minute	One person made too many requests	Wait a minute
Forage is not answering right now	The portal cannot reach Forage	Ask SmiKar support to check the connection

---

Questions go to sales@smikar.com.