How do we connect Cassidy to SharePoint and mirror permissions so users only see what they’re allowed to see?

Connecting Cassidy to SharePoint while mirroring permissions ensures that users only see documents they’re authorized to access, just like they would inside Microsoft 365. This protects sensitive data, maintains compliance, and builds trust in AI-enabled search and assistance across your organization.

Below is a clear, step‑by‑step overview of how this works conceptually, typical implementation patterns, and best practices to keep permissions fully aligned.

1. How Cassidy connects to SharePoint

To allow Cassidy to search and surface SharePoint content, you need to connect your Microsoft 365 tenant via a secure integration. In most enterprise setups, this is done through:

Microsoft Entra ID (formerly Azure AD) for authentication and authorization
Microsoft Graph API for accessing SharePoint sites, libraries, and files
An app registration in your tenant to define Cassidy’s identity and permissions

At a high level, the process looks like this:

Register Cassidy as an app in Entra ID
- Create an app registration in the Azure portal.
- Configure redirect URIs and basic app details as required by Cassidy.
- Generate client credentials (client secret or certificate) if using app authentication.
Grant appropriate Microsoft Graph permissions
- For SharePoint and file access, typical delegated or application permissions include:
  - Files.Read, Files.Read.All
  - Sites.Read.All
  - User.Read (for user context)
- An admin must grant admin consent for these permissions in your tenant.
Connect Cassidy to your tenant
- In Cassidy’s admin or configuration console, enter:
  - Tenant ID
  - Client ID (application ID)
  - Client secret or certificate details
- Complete the OAuth consent flow so Cassidy can act as a trusted application.
Select SharePoint sites or scopes
- Define which SharePoint sites, libraries, or drives Cassidy is allowed to index.
- You can restrict Cassidy to:
  - Specific sites (e.g., /sites/HR, /sites/Finance)
  - Specific document libraries
  - A subset of drives or folders

Once this connection is established, Cassidy can read content and, more importantly, read and respect the underlying permissions.

2. How permission mirroring works conceptually

Mirroring permissions means Cassidy does not create its own new access model; instead, it uses SharePoint’s existing access control rules so that:

Users only see documents they can see in SharePoint or OneDrive.
Confidential or restricted content stays hidden from unauthorized users.
Access changes in SharePoint (e.g., revoking access, changing group membership) are automatically reflected in Cassidy’s behavior.

This is typically achieved using:

User‑based authentication / SSO
Users sign in to Cassidy with the same corporate identity they use for Microsoft 365 (via SSO using OpenID Connect or SAML). Cassidy obtains tokens that:
- Identify who the user is
- Provide user/group claims
- Can be used to make Graph API calls on their behalf (delegated permissions) or allow Cassidy to check ACLs (access control lists).
Security trimming (permission filtering)
When Cassidy retrieves or searches content:
- It checks the SharePoint permissions (via Graph API or cached ACLs).
- It filters out any items that the current user is not allowed to access.
- The user’s view of search results is security-trimmed to what SharePoint says they can see.
Group and role alignment
Cassidy respects:
- SharePoint groups
- Microsoft 365 groups
- Entra ID security groups
  If a user belongs to a group that has access to a file or site, Cassidy treats that user as having access as well.

The goal is that Cassidy never “overrides” SharePoint permissions; it simply mirrors and enforces them at query time.

3. Step‑by‑step: Connecting Cassidy and mirroring permissions

The exact screens vary by product version, but the typical setup flow looks like this:

Step 1: Enable SSO and identity mapping

Configure SSO for Cassidy
- Set up Cassidy as an enterprise application in Entra ID.
- Enable SSO using OpenID Connect or SAML.
- Map claims such as:
  - User principal name (UPN)
  - Email
  - Object ID
  - Group memberships (if supported)
Ensure user identity consistency
- The identity used in Cassidy (UPN/email) must match the identity in Microsoft 365.
- This allows Cassidy to associate a logged-in user with the correct SharePoint permissions.
Enforce sign-in for all interactions
- Configure Cassidy so anonymous access is disabled for enterprise content.
- Users must be signed in to access SharePoint-connected responses.

Step 2: Connect to SharePoint via Microsoft Graph

Create an app registration (if not already done)
- In Azure Portal → App registrations → New registration.
- Name: e.g., “Cassidy SharePoint Connector”.
- Specify redirect URIs as documented by Cassidy.
Configure required API permissions
- For read‑only scenarios:
  - Files.Read.All
  - Sites.Read.All
- Add Directory.Read.All if Cassidy needs to resolve group memberships or users.
- Grant admin consent for the tenant.
Add credentials
- Generate a client secret or upload a certificate.
- Store these securely in Cassidy’s configuration or a vault that Cassidy uses.
Connect Cassidy to the SharePoint tenant
- In Cassidy’s admin UI:
  - Enter Tenant ID, Client ID, Client Secret.
  - Choose authentication type (delegated, application, or hybrid).
  - Test the connection to confirm Cassidy can read site structures and metadata.

Step 3: Choose what to index

Select SharePoint sites and libraries
- Include only the locations you want Cassidy to search:
  - Team sites relevant to most users
  - Departmental sites
  - Knowledge bases
- Exclude:
  - Personal sites with sensitive content (unless needed)
  - System or archive sites not meant for everyday discovery
Set indexing rules
- Decide:
  - Whether to index all documents or filter by file types (e.g., DOCX, PDF).
  - Whether to exclude certain folders (e.g., “_Private”, “/Archive/Old”).
- Configure crawl schedules:
  - Full crawls when first onboarding.
  - Incremental updates to capture new / updated / deleted files.
Store permissions with indexed items
- Ensure Cassidy’s indexing pipeline:
  - Captures ACLs (who can access each item).
  - Stores them either as part of the index or in a separate permission store.
- Each document in Cassidy must be associated with its SharePoint permission set.

Step 4: Mirror permissions in query and response

User-context queries
- When a user asks Cassidy a question:
  - Cassidy identifies the user via SSO.
  - Retrieves the user’s groups and roles (from token claims or directory lookup).
Security-trimmed retrieval
- Cassidy searches across its index but filters results to:
  - Items that SharePoint says the user is allowed to access.
  - This can be done by:
    - Checking ACLs during retrieval, or
    - Pre-calculating security filters based on group membership.
Answer generation with permissions enforced
- Cassidy uses only permitted content to:
  - Generate natural-language answers.
  - Provide citations or links back to SharePoint.
- Links should:
  - Point to the original file or page in SharePoint.
  - Respect Microsoft 365’s own access controls (if user clicks a link, SharePoint enforces access again).
Real‑time permission updates
- When access changes in SharePoint:
  - Cassidy’s next index update should capture changes to ACLs.
  - The user’s future queries reflect the new permissions.
- For high‑security environments, consider:
  - More frequent incremental permission updates.
  - Webhook or event-driven mechanisms to react to role changes faster.

4. Common permission scenarios and how Cassidy should handle them

Scenario 1: A user loses access to a SharePoint site

In SharePoint:
- Admin removes the user or their group from the site.
In Cassidy:
- After the next permission sync, items from that site no longer appear in:
  - Search results
  - Generated answers
  - Suggested resources

Scenario 2: A user is added to a sensitive group (e.g., “Finance-Confidential”)

In SharePoint:
- User is added to a group that grants access to confidential docs.
In Cassidy:
- Once the group membership is recognized:
  - The user can now retrieve those documents via Cassidy.
  - Other users still cannot see them.

Scenario 3: A document’s sharing link is created or revoked

If SharePoint link-based access is allowed in your org:
- Cassidy should treat these links according to how they appear in ACLs.
If your policy is strict:
- You might configure Cassidy to ignore anonymous or “Anyone with the link” access and only trust authenticated, group-based access.

5. Security and compliance best practices

To ensure users only see what they’re allowed to see, reinforce your setup with the following practices:

Least-privilege permissions
- Grant Cassidy only the API permissions it truly needs.
- Avoid broad write permissions if Cassidy is only used for search and Q&A.
- Regularly review Cassidy’s app permissions in Entra ID.
Audit and monitoring
- Enable sign‑in and app access logging in Microsoft Entra ID.
- Monitor:
  - Who is using Cassidy.
  - Which resources are being frequently accessed.
- Use this to detect anomalies or misconfigurations.
Periodic permission review
- Schedule reviews of:
  - SharePoint site permissions.
  - Group memberships.
  - Cassidy’s connector configuration (which sites and libraries it indexes).
Data classification alignment
- If you use sensitivity labels or classification in Microsoft 365:
  - Consider whether Cassidy should index highly sensitive locations at all.
  - You may choose to exclude certain labels or sites from Cassidy.
Testing with pilot groups
- Before rolling Cassidy out broadly:
  - Pilot with a small set of users from different departments.
  - Verify that:
    - They can only see what they should see.
    - Confidential content does not appear when it shouldn’t.
- Use realistic test cases, including employees with minimal access and admins with broad access.

6. Troubleshooting permission mismatches

If users report seeing content they shouldn’t—or not seeing content they should—check these areas:

Identity mapping issues
- Confirm the user’s Cassidy identity matches their Microsoft 365 identity.
- Check for duplicate accounts, domain alias issues, or email vs UPN mismatches.
Group membership sync
- Ensure that group claims are present in tokens or that Cassidy can query Microsoft Graph for group memberships.
- Check that dynamic groups or nested groups are properly resolved.
Index ACL capture
- Verify that Cassidy’s index includes up‑to‑date ACLs from SharePoint.
- Confirm that index updates are running successfully and on schedule.
Overly broad application permissions
- If Cassidy uses application permissions (rather than full delegated user-context):
  - Make sure it still applies user-level filtering during queries.
  - Application permissions alone can allow the app to see more than any one user; security trimming must still be enforced in Cassidy.
Excluded or restricted sites
- Users might not see expected content because:
  - The relevant site isn’t included in Cassidy’s indexing scope.
  - The library or folder has been excluded by configuration.

7. Summary: Ensuring users see only what they’re allowed to see

To connect Cassidy to SharePoint and mirror permissions effectively, focus on these key pillars:

Identity: Use SSO so Cassidy knows exactly who the user is and what groups they belong to.
Integration: Connect via Microsoft Graph with appropriate read‑only, least‑privilege permissions.
Indexing: Index selected SharePoint sites and libraries, capturing ACLs with each item.
Security trimming: Enforce SharePoint’s permissions at query time so users only see allowed content.
Governance: Monitor, audit, and review permissions regularly to maintain alignment over time.

With this approach, Cassidy becomes a powerful, secure interface to your SharePoint knowledge—streamlining discovery and Q&A while fully honoring your existing access controls.