# Epona365 SharePoint Permissions Reference
Audience: SharePoint/M365 admins deploying Epona365, IT staff configuring access.
This document lists every permission Epona365 requires — at the Azure AD / Graph level, the SharePoint site level, and the Epona-specific group level — and explains why each is needed.
# 1. Declared API Permissions (Azure AD / Microsoft Graph)
These permissions must be approved in the SharePoint Admin Center → Advanced → API access page during deployment. Microsoft requires the Global Administrator role to approve Microsoft Graph permissions (see Manage access to Microsoft Entra ID-secured APIs (opens new window)).
All permissions are delegated. Epona365 always acts on behalf of the signed-in user — it can never access or modify data that the user themselves does not have permission to access.
| Scope | Resource | Why it is needed |
|---|---|---|
User.ReadBasic.All | Microsoft Graph | Read basic user profiles for the people picker, matter subscriber lookups, and team member resolution. Job title and department are not part of the basic profile Microsoft returns under this permission, so they can show empty in the people picker |
Group.Read.All | Microsoft Graph | Read the matter's Microsoft 365 group resources: Planner plans (Planners), Teams channels shown as folders and used by Sync to OneDrive, and the team behind Go to Team and Team meeting. Without it, the Tasks folder, channel folders and Team links are hidden without an error |
Sites.ReadWrite.All | Microsoft Graph | All document library and list operations: reading and writing documents, creating folders, generating sharing and request-files links, converting to PDF, syncing to OneDrive, reading file-level permissions, favorite documents, recent documents, and favorite matters as followed sites |
Mail.ReadWrite | Microsoft Graph | Email (Web) only: read a document's own message and create mail drafts for Open/Reply/Reply All/Forward/Send as Attachment/Send as Link in Outlook Web. Email (Classic) goes through the desktop Outlook client and does not use this permission. Email (Web) also requires the Epona365 API |
# How approved permissions apply
- Tenant-wide, not per solution. Approved permissions are stored on the tenant's shared SharePoint Online Client Extensibility Web Application Principal, not on an Epona365 app. Once approved, they can be used by any SharePoint Framework solution or client-side script in the tenant. In the same way, Epona365 can use permissions that were approved for other solutions.
- Removing Epona365 does not revoke them. Uninstalling the package leaves approved permissions in place. Revoke them manually with Remove access on the API access page, or with
Revoke-SPOTenantServicePrincipalPermission. - Revoking does not end existing sessions. Access tokens that were already issued remain valid until they expire.
Mail.ReadWriteis optional. It is only needed for Email (Web). Enable Email (Web) is a per-user user setting that is on by default; there is no tenant-wide switch. If your organisation does not approve the scope, opening an email document shows an error until the user turns Enable Email (Web) off in their user settings menu. All other features, including Email (Classic), keep working.
Note:
Sites.ReadWrite.Allis a broad scope. Epona365 reads and writes documents only in the site collections defined in the matters list. The exceptions are favorite documents, recent documents and followed sites: these read the user's own lists, which can include other sites and the user's OneDrive, and adding or removing a favorite matter updates the user's followed sites. If your organisation requires a more restricted setup usingSites.Selected(which limits access to specific site collections), this can be implemented on request. It is not supported in the current version.
# access_as_user (Epona365 api) — granted directly, not declared
Unlike the Graph scopes above, access_as_user is not requested through package-solution.json's webApiPermissionRequests — it never appears as a pending request in SharePoint Admin Center → Advanced → API access. Requesting it that way required the resource string to match the Epona365 API app registration's exact display name in Azure AD, which broke silently whenever that name diverged (a customized -ApiAppName at deploy time, a renamed app, or a managed vs self-hosted naming difference) [#60898].
It is instead granted directly on the SharePoint Online Client Extensibility Web Application Principal in Entra: open the app in Entra admin center, add the Epona365 API app's access_as_user delegated permission, and grant admin consent. Lets the webpart call the Epona365 API (E365 Office API) as the signed-in user. Same permission backs every E365-API feature (Ask Epona/Copilot, Email (Web), license validation, term set sync, favorite document metadata, location tags, document repository), not just the proxy transport. Only relevant when the Epona365 API is deployed (api.url set in DMS Configuration) — not deployed means no effect either way.
Note: Microsoft states that this principal is managed through the SharePoint Admin Center API access page and that changing it directly in Entra is not supported. The direct grant is used because requesting
access_as_userthrough the API access page breaks when the app's display name differs (see above). After granting it, the permission also appears on the API access page.
Until Epona365 API's own deploy scripts automate this grant (Deployment/self-hosted/Assert-Epona365Apps.ps1, Deployment/managed/entraid/Assert-ManagedEpona365Apps.ps1 in the Epona365Office repo — not yet done, tracked under [#60898]), an admin must add it manually with the steps above whenever the Epona365 API is deployed. If deployed but not granted: aadHttpClientFactory.getClient() still resolves (SPFx doesn't validate consent at creation) but every call 401/403s — breaks Ask Epona/Copilot, license validation, term set sync, favorite metadata, location tags, document repository. If useEpona365OfficeProxyTransport: true is also set, impact is total: proxy is the sole transport with no fallback, so all document operations fail until granted.
# Graph permissions on the Epona365 API app (proxy only)
With useEpona365OfficeProxyTransport: true, Graph calls are made by the Epona365 API on behalf of the user, so the Graph scopes in the table above no longer apply to them — the Epona365 API app registration needs its own delegated Graph permissions. On top of the Graph and SharePoint permissions the Epona365 API app already has, add Tasks.Read.Shared (Planner auto-discovery) and Channel.ReadBasic.All (Teams channels). See Epona365 API Proxy.
# 2. SharePoint Site Permissions (User-Level)
Most users only need Read or Contribute on each DMS site collection. Manage Permissions is only required for users who need the Make Private feature.
| SharePoint Role | Features enabled | Notes |
|---|---|---|
| Read | Browse documents, view document metadata and permissions, document signing, planners, people lookups | Minimum role for any Epona365 functionality |
| Contribute | Upload and edit documents, rate documents, create documents from Contracts templates, add documents to KMS, Email (Classic/Web) actions, open the SharePoint sharing dialog, hand off documents for signing | Required for any write operation on a document library |
| Manage Permissions (or Full Control) | Make Private — removes inherited permissions on a document or folder and grants access only to the current user | Optional. Only needed for users who should be able to make documents private. Most users do not need this role. |
# 3. Feature × Permission Matrix
| Feature | Min. SharePoint Role | Graph Scope(s) | Notes |
|---|---|---|---|
| Browse / read documents | Read | Sites.ReadWrite.All | Includes full-text search |
| Upload / edit documents | Contribute | Sites.ReadWrite.All | |
| Rate documents | Contribute | Sites.ReadWrite.All | Star rating on documents |
| View document permissions | Read | Sites.ReadWrite.All | Shows who has access to a file |
| Manage Access | Contribute | Sites.ReadWrite.All | Opens the standard SharePoint sharing dialog |
| Make Private | Manage Permissions | Sites.ReadWrite.All | Removes inherited permissions; only the current user retains access |
| Recycle bin: view own items | Read (own items only) | Sites.ReadWrite.All | Manage Lists required to view all users' deleted items |
| Recycle bin: restore items | Contribute (own items only) | Sites.ReadWrite.All | Manage Lists required to restore other users' deleted items |
| Add to KMS (copy to practice area) | Contribute | Sites.ReadWrite.All | Copies the document via the user's own SharePoint permissions on the practice area's KMS library; no separate KMS authentication or group membership |
| Contracts: create from template | Contribute | Sites.ReadWrite.All | Creates a new document from a content type template |
| Email (Web) | Contribute | Mail.ReadWrite | Requires the Epona365 API (and access_as_user). Open/Reply/Reply All/Forward/Send as Attachment/Send as Link via Outlook Web — see Outlook Web Access (OWA) |
| Email (Classic) | Contribute | — | Same actions via the desktop Outlook client; no Graph mail permission needed |
| Sync to OneDrive | Read | Sites.ReadWrite.All, Group.Read.All | Feature must be enabled in DMS Configuration Center; Group.Read.All is used to offer private and shared Teams channels for sync |
| Planners | Read | Sites.ReadWrite.All, Group.Read.All | Reads Microsoft Planner plans for the associated O365 group |
| Teams channels / Go to Team / Team meeting | Read | Group.Read.All | Lists the channels of the matter's Microsoft 365 group and opens its team |
| Favorite documents / recent documents | Read | Sites.ReadWrite.All | Favorite matters as followed sites also uses this permission |
| Document signing (DocuSign / Penneo) | Read | Sites.ReadWrite.All | Document is read and sent to the external signing service |
| Advosys (send to financial system / attach to EAN invoice) | Read | Sites.ReadWrite.All | Document is read and streamed to Advosys; no SharePoint metadata is written back |
| User / people lookups | Read | User.ReadBasic.All | Used in people picker and matter subscriber fields |
| Managed metadata (read / tag) | Contribute | Sites.ReadWrite.All | Reading taxonomy values requires no special term store permissions; tagging requires Contribute |
# 4. Term Store / Managed Metadata
No special term store administrator rights are required for reading managed metadata values. Tagging documents with taxonomy values requires Contribute on the document library.
Epona365 reads the term set hierarchy for the term picker and for the full term path on the Details panel:
- The Details panel uses the Epona365 API (
/api/termsets) when it is configured. - Otherwise, and always for the term picker, it uses the SharePoint client service (
/_vti_bin/client.svc/ProcessQuery,TermSet.GetAllTerms). Unlike/_api/v2.1/termstore, this also returns terms reused from another term set. - If that call fails, it falls back to SharePoint
/_api/v2.1/termstore. Outside SharePoint (standalone, with the app's own sign-in) that endpoint requires the SharePoint delegated permissionTermStore.Read.Allon the app registration.
This uses the signed-in user's normal read access to the term set; no term store administrator rights are needed.
# 5. Recycle Bin
| Action | Required Permission |
|---|---|
| View own deleted items | Read |
| View all users' deleted items | Manage Lists |
| Restore own items | Contribute |
| Restore other users' items | Manage Lists |