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.

Prerequisites

• A Workmate team administrator who can add a Microsoft Entra app.
• 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>.
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 and Sites.Read.All. Workmate also requests the sign-in scopes openid, profile, and offline_access during connection.
3. Remove unrelated permissions unless another reviewed use of this exact app requires them.
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. Microsoft marks delegated Sites.Read.All as not inherently admin-consent required, but tenant consent policy can still require an administrator. Cloud Application Administrator or Application Administrator can grant tenant-wide consent for these delegated Graph permissions.

Adding a permission to the registration is not consent. Consent is not proof that a token contains the scope. Workmate records the scopes Microsoft actually returns and displays them in connection diagnostics.

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.
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, and granted scopes.
2. Select Check health. A healthy result means Microsoft accepted the token and Graph /me confirmed the expected identity.
3. Perform a read operation against an approved SharePoint site through the assigned Workmate. The health check does not prove access to a particular site.
4. Test an intentionally unauthorized site when your policy requires negative evidence. The result should match whether the signed-in user can access that site.

Safe diagnostics include tenant and client IDs, principal name and object ID, token expiration, granted scope names, last-check time, connection state, and a stable diagnostic message. 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.

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 asks Microsoft for the connection's previously observed product capabilities, forces a consent prompt, and requires the same Microsoft identity. Reconnect does not change the tenant or client ID and does not grant SharePoint membership.

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