Microsoft SharePoint administrator runbook

Tasks in this runbook

1. Understand the permission model
2. Prepare roles and values
3. Register and connect the Entra app
4. Restrict who may authenticate
5. Verify the connection
6. Choose an app boundary
7. Rotate, reconnect, disconnect, and revoke
8. Respond to an incident
9. Troubleshoot safely

Permission model

Microsoft Entra ID is Microsoft's identity and access service. An app registration identifies the customer-owned application that Workmate uses. Its corresponding enterprise application is the tenant-local object where an administrator controls sign-in, assignment, and consent.

Microsoft Graph is Microsoft's API for Microsoft 365. Delegated access means Workmate calls Graph on behalf of a signed-in Microsoft user. A delegated permission, also called a scope, limits what the app may ask Graph to do. Consent records that a user or administrator approved those scopes.

Effective access is the intersection of all applicable controls:

1. Delegated Microsoft Graph permissions configured on the Entra app.
2. User or tenant-wide admin consent granted to the enterprise application.
3. The scopes actually present on the delegated access token.
4. The signed-in user's SharePoint permissions and Microsoft policies.
5. Enterprise-application assignment, when “Assignment required” is enabled.
6. Workmate's own team ownership and Workmate-to-connection assignment.

Workmate validates and uses the resulting access. It does not create users, grant SharePoint membership, grant tenant consent, assign users to the enterprise application, or change Microsoft-side permissions.

The Entra app registration is the administrator-facing permission source of truth. Workmate requests Microsoft Graph https://graph.microsoft.com/.default and records the concrete delegated scopes Microsoft returns on each token. Workmate still exposes only its implemented operations; an extra token scope does not create generic Graph access.

Prerequisites

• A Workmate team administrator who can add a Microsoft Entra app.
• A dedicated Entra app registration used only for Workmate. Do not share it with unrelated software, because every consented delegated Graph permission may be represented by /.default tokens issued to this client.
• A Microsoft tenant ID and permission to register an app. Microsoft lists Application Developer as the minimum built-in role for its registration quickstart; tenant policy may require an application administrator.
• A Microsoft identity that can read every SharePoint site the Workmate should use. Use a dedicated, accountable identity when your policy requires it.
• A Cloud Application Administrator, Application Administrator, or appropriately configured custom role if users cannot consent or you want tenant-wide consent for these delegated Graph permissions. Privileged Role Administrator can grant consent for any permission.

Open Workmate's Entra app setup dialog before configuring authentication. It displays the exact redirect URI for your Workmate deployment.

Set up the connection

1. Register a single-tenant application

1. Sign in to the Microsoft Entra admin center and switch to the tenant that owns the SharePoint sites.
2. Go to Entra ID > App registrations > New registration.
3. Enter a recognizable name, such as <WORKMATE-SHAREPOINT-APP-NAME>. This registration must be dedicated to Workmate and must not be reused by unrelated applications.
4. For Supported account types, choose Accounts in this organizational directory only. A Workmate app record is bound to one tenant; a multitenant registration adds no benefit to this customer-managed setup.
5. Select Register. Record the Directory (tenant) ID and Application (client) ID from Overview.

2. Add the exact redirect URI

1. In Workmate, open Apps, choose Microsoft Entra App, and copy the displayed Web redirect URI.
2. In the Entra app registration, open Authentication > Add a platform > Web.
3. Paste the URI exactly, including scheme, host, path, and any port. Do not choose the single-page application platform and do not invent a localhost or production URI.
4. Select Configure or Save.

Microsoft requires the redirect in an authorization request to exactly match a registered redirect URI. Copy it again from Workmate when moving between environments.

3. Create the client secret

1. In the app registration, open Certificates & secrets > Client secrets > New client secret.
2. Use a description that names its Workmate purpose and choose the shortest lifetime your rotation process can support. Microsoft allows at most 24 months and recommends less than 12 months.
3. Copy the secret Value immediately. Do not copy the Secret ID. Microsoft shows the value only once.
4. Store the value only in your approved secret handoff process until it has been submitted to Workmate, then remove temporary copies.

4. Configure delegated Microsoft Graph permissions

1. Open API permissions > Add a permission > Microsoft Graph > Delegated permissions.
2. Add User.Read for identity verification. Then add the delegated permissions for each Workmate service your team will connect — grant only the services you intend to use:
   • Outlook Mail: Mail.Read, Mail.ReadWrite, Mail.Send
   • Outlook Calendar: Calendars.Read, Calendars.ReadWrite
   • Outlook Contacts: Contacts.Read, Contacts.ReadWrite
   • SharePoint: Sites.Read.All
   For SharePoint, Sites.Selected (with explicit site grants) works in place of Sites.Read.All. Workmate recognizes broader observed authority such as Sites.ReadWrite.All, but its curated SharePoint operations remain read-only; do not grant SharePoint write authority for Workmate.
3. Remove unrelated permissions. This app is dedicated to Workmate, so another application's requirements must not widen it.
4. If your organization uses tenant-wide consent, select Grant admin consent and review the prompt. Otherwise, the connecting user may consent if tenant policy permits it. Tenant consent policy can still require an administrator even where Microsoft's permission reference does not mark a delegated scope as inherently admin-consent required.

Workmate requests Microsoft Graph /.default, plus the sign-in protocol scopes openid, profile, and offline_access. Microsoft uses /.default to issue the statically configured Graph permissions that have been consented for this client and user. Adding a permission to the registration is not consent, and consent is not proof that a particular token contains the scope. Workmate records and displays the exact delegated scopes Microsoft returns.

When using Sites.Selected

1. Configure and consent delegated Sites.Selected on the Entra app.
2. Use Microsoft's selected-permissions procedure to grant this Entra application the read role on each intended SharePoint site.
3. Confirm that the signed-in delegated user also has sufficient SharePoint access to the site.

All three conditions are required: token scope, explicit site grant, and delegated-user access. Workmate does not copy selected-site grants into its database. Microsoft evaluates them on each site request.

Do not combine a broad scope with Sites.Selected when your goal is a selected-only boundary. If a token contains Sites.Read.All or Sites.ReadWrite.All as well as Sites.Selected, the broad scope remains effective. Selected grants are not deny rules.

5. Enter the app in Workmate and connect an identity

1. In the Workmate dialog, enter a customer-recognizable name, Directory (tenant) ID, Application (client) ID, and the client secret Value.
2. Submit the app. Workmate never displays the secret again.
3. Select Connect identity for the new Entra app and choose the Workmate that will use the connection.
4. Sign in at Microsoft with the intended tenant identity. Review the requested permissions and complete consent if prompted. Microsoft's prompt reflects the permissions configured on the dedicated app, not a separate Workmate scope chooser.
5. Return to Workmate and confirm that the expected identity appears under the Entra app. Assign the connection only to the intended Workmates.

Restrict which identities may authenticate

Enterprise-application assignment is a Microsoft sign-in control. It is separate from Workmate assignment:

• Entra assignment decides which users or groups may sign in to this app and receive delegated tokens.
• Workmate assignment decides which Workmate may attempt a curated operation using an already connected identity.
• Neither assignment grants SharePoint site access; SharePoint and token permissions still apply.

1. In the Entra admin center, go to Entra ID > Enterprise apps > All applications and open the customer-owned Workmate app.
2. Open Properties, set Assignment required? to Yes, and save.
3. Open Users and groups > Add user/group, select only approved identities, and assign.
4. Test with an assigned identity before relying on the restriction.

Microsoft documents Cloud Application Administrator, Application Administrator, User Administrator, or service-principal owner as roles that can make assignments, with differences in what each may assign. Group assignment requires Microsoft Entra ID P1 or P2, and nested group membership does not cascade. When assignment is required, grant needed consent before expecting assigned users to sign in.

Verify the connection

1. Open the connected app in Workmate and confirm the tenant ID, Entra app, client ID, identity, object ID, requested /.default authority, and observed scopes.
2. Select Check health. A healthy result means Microsoft accepted the token and Graph /me confirmed the expected identity.
3. Enter the exact approved site URL under Target SharePoint site and select Check site. This runs a bounded SharePoint metadata lookup through the assigned Workmate.
4. For selected-only negative evidence, test a site the signed-in user can access but this Entra app has not received a read grant for. Microsoft should deny or hide that site. If a broad scope is also observed, the user's access may still allow the request because selected-site grants are not deny rules.

Safe diagnostics include tenant and client IDs, principal name and object ID, token expiration, requested resource authority, observed scope names, effective curated capability state, last-check time, connection state, and stable site outcomes. Do not request raw tokens or provider response bodies.

Choose an app boundary

• One app for one security boundary: use the same app where identities share credential ownership, consent review, rotation, and incident response.
• Separate apps for separate boundaries: use different apps when departments, regions, or regulated workloads require independent credentials, consent, enterprise assignments, rotation, or revocation.
• SharePoint access: grant each connected Microsoft identity access only to the sites it should read through Workmate.

Prefer the smallest number of apps that still matches your organization's ownership, audit, and incident-response boundaries.

Every app in this model is dedicated to Workmate. “Same boundary” means multiple Workmate identities may use one reviewed Workmate app; it does not mean the registration may be shared with unrelated products.

Routine operations

Rotate a client secret without interruption

1. In Microsoft Entra, create the replacement secret first. Keep the current secret active.
2. In Workmate, select Rotate secret for the Entra app. Enter the replacement secret Value and, optionally, its Microsoft expiration date.
3. Select Validate and rotate. Workmate uses an eligible delegated refresh credential to ask Microsoft to validate the replacement.
4. If Workmate reports validated, the replacement is current. Delete the old secret in Microsoft, then run connection health and a SharePoint read.
5. If validation is not available because no usable delegated credential exists, the replacement may still be promoted. Reconnect the affected identity and verify it before deleting the old Microsoft secret.

Microsoft rejection of the replacement as an invalid or unauthorized client leaves the current Workmate secret unchanged. A revoked delegated grant may allow emergency promotion and mark the identity for reconnect. A transient Microsoft or network failure does not promote the candidate. Successful promotion is atomic: Workmate immediately removes the prior encrypted secret value and retains only safe version metadata. There is no stored old secret to roll back to.

The optional expiration date is customer-supplied metadata for operations; it is not proof from Microsoft. Initial app setup does not collect an expiration date.

Reconnect an identity

Use Reconnect when consent, the refresh grant, or identity authorization needs repair. Workmate requests Graph /.default, forces a consent prompt, records the newly returned delegated scopes, and requires the same Microsoft identity. Reconnect does not change the tenant or client ID and does not grant SharePoint membership or a selected-site role.

Apply Entra permission changes and migrate existing connections

Adding or removing an API permission in Entra does not rewrite an access token already issued, and Workmate does not reinterpret its last observed scopes as current Entra configuration. Complete required consent and reconnect for a deterministic new token. Refresh and secret-rotation validation also replace observed scopes when Microsoft returns a new scope set, but their timing is not an administrator-facing deployment mechanism.

Connections created before Workmate adopted /.default are labeled as legacy in diagnostics. They continue renewing with their previously observed resource scopes so deployment does not silently broaden them. Reconnect once to migrate that connection to the dedicated-app /.default authority model.

Understand each stop or revoke action

To review or revoke delegated consent, go to Enterprise apps > the application > Permissions. Microsoft allows tenant-wide admin consent to be revoked in the portal. User-specific consent must be revoked with Microsoft Graph or PowerShell. Use a Cloud Application Administrator or Application Administrator for this permission review, and record the grant that was removed.

Emergency response

1. Contain Workmate use: remove the affected Workmate assignment or disconnect the connection. Disconnect removes Workmate's encrypted delegated credentials but is not Microsoft-side revocation.
2. Contain Microsoft sign-in: disable sign-in on the enterprise application or remove assignments when appropriate.
3. Invalidate credentials: delete the suspected client secret in Microsoft, revoke affected delegated grants, and apply your tenant's user-session revocation procedure. Existing access tokens may remain usable until Microsoft rejects them or they expire.
4. Recover: create a new Microsoft secret, rotate it into Workmate, reconnect the intended identity, restore only reviewed assignments and consent, then run health and positive/negative site tests.
5. Preserve safe evidence: record times, actor names, tenant and client IDs, object IDs, secret version numbers, state, and stable diagnostics. Never preserve secret or token values in the incident record.

Troubleshooting

Security-review summary

• The customer owns the Entra app, tenant consent, Microsoft identities, client-secret lifecycle, enterprise assignments, and SharePoint permissions.
• Workmate encrypts client secrets and delegated access, refresh, and ID tokens with team-scoped AES-256-GCM envelopes bound to the stored record context.
• Workmate authorizes the exact team, connection, and Workmate assignment before decrypting credentials or calling Microsoft.
• Client secrets are write-only after submission. Product APIs and UI expose safe metadata, scope names, state, timestamps, and stable diagnostics, not plaintext credentials.
• Microsoft provider error text and response bodies are mapped to stable customer-safe outcomes. Secrets, tokens, and provider payloads are prohibited from application logs, errors, and agent-visible results.
• The native customer-managed path uses the customer's Entra app, Workmate's encrypted credential custody, and direct bounded Graph operations. Pipedream-backed integrations instead broker OAuth and API request/response payloads through Pipedream; do not assume the same scopes, custody, or lifecycle controls.

Official Microsoft procedures

• Register an application
• Add a redirect URI
• Add application credentials
• Microsoft identity platform admin consent
• Grant tenant-wide admin consent
• Assign users and groups to an enterprise application
• Review and revoke enterprise-application permissions
• Microsoft Graph Sites.Read.All permission reference
• Microsoft identity platform .default scope
• Microsoft Graph selected permissions overview