> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/nightfall_integrations/saas-apps-authorization-authentication-and-best-practices.md). # SaaS Apps -Authorization, Authentication & Best Practices **Audience:** Customer admins who connect and maintain Nightfall SaaS integrations **Applies to:** Slack, Google Drive, Microsoft 365 (Teams / OneDrive / SharePoint), Jira, Confluence, Salesforce, GitHub, Notion, Gmail & Exchange Online (inline email DLP) *** ### 1. Overview: How Each Integration Authenticates Nightfall integrations use one of two fundamental authentication models. Understanding which model your integration uses tells you what can break it — and how to prevent that. | **Integration** | **Authentication model** | **Tied to the person who connected it?** | **Impact if that person leaves** | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Google Drive** | Google service account with Domain-Wide Delegation (DWD) | Partially — the connecting admin's email is registered and used for admin-level operations | **Medium-High** — directory sync, audit logs, admin operations, and the connection health check break; reconnect with another admin to restore | | **Microsoft 365** | Dedicated Entra ID (Azure AD) app registrations in your tenant, app-only (client credentials) | No — admin identity is used only once, during setup consent | **None** | | **Slack** | OAuth bot token (plus a user token for admin/discovery operations), issued via the installing user's session | **Yes** | **High** — the #1 cause of stuck disconnections; requires uninstall + reinstall to fix | | **Jira** | Two credentials: an Atlassian Marketplace (Connect) app secret for scanning, plus a user OAuth token for remediation features | Partially — scanning is app-level; remediation (e.g., redaction) uses the authorizing user's token | **Medium** — scanning continues; redaction/remediation breaks until someone re-authorizes | | **Confluence** | Atlassian Marketplace (Connect) app secret only — fully app-level | No | **None** | | **Salesforce** | OAuth 2.0 (authorization code + PKCE) bound to the authorizing user, plus the Nightfall managed package | **Yes** | **High** — token is invalidated when the user is deactivated or their permissions are revoked | | **GitHub** | GitHub App installation (app-level tokens minted from Nightfall's app key) | No — the installer identity is recorded only as metadata | **None** | | **Notion** | Workspace-level bot token issued via Notion's public OAuth | No — the token belongs to the workspace, not the installer | **None** — but removing the integration in Notion can fail silently (see Notion section) | | **Gmail / Exchange Online (email DLP)** | No stored credential — mail-routing rules in your email platform direct messages through Nightfall's scanning relay | No | **None** — but see the email section: risks are rule/connector misconfiguration, not tokens | > **Important Note:** For Slack, Salesforce, Google Drive, and Jira, connect Nightfall using a **dedicated, non-personal service/admin account** that is excluded from routine employee offboarding. This prevents the most common cause of disconnections. *** ### 2. Universal Best Practices (All Integrations) 1. **Use a dedicated service account to authorize integrations.** Create a persistent account (e.g., `nightfall-svc@yourcompany.com`) with the required admin privileges in each SaaS platform. Never authorize integrations with a personal employee account. 2. **Exclude that account from offboarding automation.** Deactivating, deprovisioning, or demoting the authorizing account is the leading cause of disconnections across Slack, Salesforce, Google Drive, and Jira. 3. **Add Nightfall to your change-management allowlists.** Admin-console cleanups that revoke third-party app access, reduce OAuth scopes, or tighten app-access policies frequently disconnect DLP integrations as a side effect. Document Nightfall's required grants (listed per app below) so security reviews don't remove them. 4. **Check the Integrations page in the Nightfall console after any admin change** in the connected SaaS platform (permission changes, app audits, security policy changes, domain migrations). 5. **Re-authorize proactively, not reactively.** If the person who connected an integration is leaving the company, re-authorize the integration with the service account *before* their account is deactivated. 6. **Don't uninstall to "refresh" a connection** unless instructed by these steps or Nightfall support — some platforms (notably Slack) require a specific uninstall/reinstall order, and an out-of-order attempt can leave the integration in a stuck state. *** ### 3. Google Drive #### How authentication works Nightfall connects to Google Workspace using a **Google service account with Domain-Wide Delegation (DWD)** — not an ordinary user OAuth grant. During setup: 1. You authorize Nightfall's service account **Client ID** in the Google Admin Console (**Security → Access and data control → API controls → Domain-Wide Delegation**) with the OAuth scopes listed below. 2. You complete a short sign-in as a Google Workspace admin. This does **not** create an ongoing user token — it registers your email as the integration's **admin email**, which Nightfall impersonates for all admin-level operations (directory sync, audit logs, connection health checks, labels, and certain remediation actions). File scanning impersonates individual users via DWD; the admin email is used for everything at the domain/admin level. **Required Domain-Wide Delegation scopes** (grant all of these to Nightfall's Client ID): ``` https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/drive.apps.readonly https://www.googleapis.com/auth/drive.admin.labels https://www.googleapis.com/auth/admin.directory.user.readonly https://www.googleapis.com/auth/admin.directory.group.readonly https://www.googleapis.com/auth/admin.directory.group.member.readonly https://www.googleapis.com/auth/admin.directory.domain.readonly https://www.googleapis.com/auth/admin.reports.audit.readonly https://www.googleapis.com/auth/admin.directory.user ``` #### What can cause a disconnection
#CauseEffect
1DWD grant removed in Google Admin Console, or Nightfall's Client ID deleted from the Domain-Wide Delegation listTotal outage — all scanning, directory sync, and monitoring stop; integration shows Not Connected
2Scopes reduced on the DWD grant (e.g., a security review trims "unused" scopes)Partial outage — features tied to the removed scope fail (e.g., removing admin.reports.audit.readonly breaks audit-log/exfiltration monitoring; removing admin.directory.* breaks user/group sync and the connection check)
3The registered admin's account is deleted, suspended, or demoted from adminDirectory sync, audit logs, admin-level Drive operations, and the connection health check fail — the integration shows Not Connected even though per-user file scanning may briefly continue
4The registered admin loses Google Drive access (license or service toggle)Connection health check fails; integration shows Not Connected
5Drive access disabled for an organizational unit ("Drive apps" turned off for an OU)Users in that OU are skipped; the integration overall stays connected
> **Note:** The admin account you sign in with matters more than you might expect. It is not just used once — it is the identity Nightfall impersonates for all admin operations, and the connection status check runs as that account. Treat it as critical integration infrastructure. #### How to reconnect 1. In Google Admin Console, confirm Nightfall's Client ID is present under **Domain-Wide Delegation** with **all** scopes listed above (the Nightfall console displays the Client ID during setup). 2. From the Nightfall console, re-run the Google Drive connection flow, signing in as a **current Google Workspace admin** (the account must be able to administer users/domains and have Drive enabled). Setup fails with a "not admin" error otherwise. 3. Verify the integration shows **Connected**. #### Best practices * Authorize with a dedicated admin service account, not a person's account. * If the registered admin is leaving, re-run the connection with the service account **before** their account is suspended. * Record the DWD grant (Client ID + all nine scopes) in your change-management documentation so security audits don't remove it. * After any Google Admin Console change to API controls or app access, check the Nightfall Integrations page. *** ### 4. Microsoft 365 (Teams, OneDrive, SharePoint) #### How authentication works During onboarding, a **Global Administrator or Privileged Role Administrator** signs in once. Nightfall uses that one-time consent to create dedicated **Entra ID (Azure AD) app registrations inside your tenant** — one per workload you enable (Teams, OneDrive, SharePoint, and exfiltration monitoring if applicable) — each with its own client secret and the Microsoft Graph application permissions it needs. After onboarding, **no user identity is involved**. All operational calls authenticate app-to-app (client credentials) using those app registrations. The admin who consented can leave the company with no impact. **Graph application permissions assigned (by workload):** * All workloads: `Files.ReadWrite.All`, `Team.ReadBasic.All`, `Channel.ReadBasic.All` * OneDrive: adds `InformationProtectionPolicy.Read.All` * Teams: adds `Group.Read.All`, `ChannelMessage.Read.All`, `User.Read.All`, `Chat.Read.All` * SharePoint: adds `Sites.Read.All` * Exfiltration monitoring: adds `User.Read.All`, `Activity.Read.All`, `User.EnableDisableAccount.All`, `RoleManagement.ReadWrite.Directory` #### What can cause a disconnection
#CauseEffect
1Client secret expires — the app registrations Nightfall creates have client secrets with a fixed expiry (the most common cause)All Graph API calls fail once the secret lapses. The console shows the secret expiry date — renewing requires an admin to re-authenticate, so plan ahead
2App registrations or their secrets deleted in Entra ID (e.g., during an app-registration cleanup)Total outage for the affected workload
3API permissions revoked on the app registrations by a tenant adminGraph calls fail with insufficient-privileges errors
4Change-notification subscriptions lapse — Microsoft Graph webhook subscriptions have hard expiries (about 2 days for Teams messages, about 29 days for OneDrive/SharePoint). Nightfall renews them automatically, but if renewal repeatedly fails (e.g., permissions were reduced), real-time event scanning stopsSilent degradation: the integration can still show Connected while real-time scanning is stalled. If real-time findings stop while status looks healthy, contact Nightfall support
#### How to reconnect / renew * **Secret renewal:** In the Nightfall console, use the M365 integration settings to renew the client secret before its expiry date. A Global Administrator or Privileged Role Administrator must sign in to complete the renewal. * **Full repair:** Re-run the M365 setup flow with a Global Administrator or Privileged Role Administrator. Re-running setup re-creates or updates the app registrations and re-assigns permissions. #### Best practices * **Calendar the client secret expiry** alerted in the Nightfall console and renew it at least two weeks early. This prevents the most common M365 disconnection. * Exclude Nightfall's app registrations (and their Graph permissions) from Entra ID app-governance cleanups; document them in your app inventory. * Keep at least one Global Admin identified as the owner of renewal — the renewal step requires that role. *** ### 5. Slack #### How authentication works Nightfall for Slack is installed via Slack OAuth. Two tokens are issued and stored: * A **bot token** used for most scanning and remediation operations. * A **user token** from the installing admin, used for admin-level operations (and, on Enterprise Grid, org-wide Discovery API access). Both tokens are **bound to the installing user's Slack account**. This is a Slack platform behavior, not a Nightfall design choice — and it is why the installer's account status matters so much. **Enterprise Grid** installs are a two-step flow: first an org-level authorization by an **Org Owner/Admin** (Discovery access), then the bot installation. The app must be installed at the **organization** level, not a single workspace, for multi-workspace coverage. #### What can cause a disconnection
#CauseEffect
1The installer's Slack account is deactivated (typically employee offboarding) — the #1 causeSlack returns account_inactive on API calls. Re-authorizing from the Nightfall console alone does not fix this — Slack keeps the app bound to the departed user. See the reconnect steps below for the required order of operations
2The installer loses admin/owner privileges in SlackAdmin-level operations fail; the integration shows Not Connected until re-authorized by a current admin
3The app is uninstalled or its token revoked from Slack (workspace/org admin removes it)All API calls fail (token_revoked / invalid_auth); integration shows Not Connected
4Enterprise Grid installed at the wrong level — installed into a single workspace instead of org-wide, or not shared to all workspacesChannels in other workspaces can't be scanned; errors indicate the app isn't installed in the owning workspace or is missing scopes
#### How to reconnect **Standard case (token revoked, admin change):** 1. In the Nightfall console, open the Slack integration and re-run the OAuth installation, signing in as a **current Slack admin/owner** (Org Owner for Enterprise Grid). **Installer's account was deactivated (`account_inactive`):** 1. **First**, have a Slack admin uninstall the Nightfall app on the Slack side: **Slack Admin → Manage Apps → Nightfall → Uninstall** (org-level app management on Enterprise Grid). 2. **Then** re-install from the Nightfall console, signing in with the dedicated service account. 3. The order matters: re-running OAuth without the Slack-side uninstall leaves the app bound to the departed user, and the integration can appear stuck ("can't disable, can't reconnect"). If you reach that state, contact Nightfall support. #### Best practices * **Install Slack with a dedicated service account** that is a Workspace Owner/Admin (Org Owner on Enterprise Grid) and is permanently excluded from offboarding deactivation. This is the highest-value preventive action for Slack. * If the person who installed Nightfall is leaving, **reinstall with the service account before their Slack account is deactivated** (Slack-side uninstall first, then reinstall — same order as above). * On Enterprise Grid, always install at the **organization** level and ensure the app is shared to all workspaces you want covered. * After reinstalling, spot-check that alerting destinations (Slack alert channels configured in Nightfall) still work — reinstallation can require re-selecting alert channels. *** ### 6. Jira #### How authentication works Nightfall for Jira uses **two credentials with different jobs**: 1. **Atlassian Marketplace (Connect) app** — installed from the Atlassian Marketplace into your Jira site. Atlassian issues an app-level shared secret that authenticates webhook delivery and content scanning. This is **not tied to any user**. 2. **A user OAuth authorization** (Atlassian 3-legged OAuth) — granted by a Jira admin during setup. This delegated token is used for operations the Marketplace app cannot perform, most notably **redaction/remediation**. Scopes requested for the OAuth authorization: ``` read:jira-user, read:jira-work, write:jira-work, read:permission:jira, read:application-role:jira, read:license:jira, read:me, redact:issue:jira, offline_access ``` #### What can cause a disconnection
#CauseEffect
1Marketplace app uninstalled from the Jira siteTotal outage — webhook events stop and scanning credentials are removed
2Marketplace app disabled (Jira admin toggles it off in Manage Apps)Events are silently dropped — no scanning occurs while disabled; re-enable in Manage apps to resume
3OAuth refresh token invalidated — the authorizing user revokes Nightfall in their Atlassian account settings, their Atlassian account is deactivated/deprovisioned, or Atlassian invalidates the tokenScanning continues (it uses the app-level credential), but redaction and other remediation actions fail until a Jira admin re-authorizes
4Site URL changes (Jira site rename/migration)Credentials no longer match the site; reinstall/reconnect required
#### How to reconnect * **App uninstalled/disabled:** Reinstall (or re-enable) the Nightfall app from **Jira Settings → Apps → Manage apps**. Reinstalling re-issues the app credential automatically. * **Remediation failing (OAuth broken):** From the Nightfall console, re-run the Jira authorization flow signed in as a current Jira admin. This stores a fresh token; no Marketplace reinstall is needed. #### Best practices * Perform the OAuth authorization step with a **dedicated service account** that has Jira admin rights, so remediation doesn't break when an individual leaves. * Treat "app disabled" as an outage: disabling the Nightfall app in Manage Apps silently stops scanning. Add it to your admin runbook as a do-not-disable app. * If the authorizing user is leaving, re-authorize from the Nightfall console with the service account before their Atlassian account is deprovisioned. Scanning won't stop, but remediation will. *** ### 7. Confluence #### How authentication works Nightfall for Confluence is a pure **Atlassian Marketplace (Connect) app**. When you install it from the Marketplace, Atlassian delivers an app-level shared secret to Nightfall, which authenticates all subsequent API calls and webhooks. **No user token exists anywhere in the integration** — there is nothing bound to the person who clicked "install." #### What can cause a disconnection
#CauseEffect
1Marketplace app uninstalled from the Confluence siteTotal outage — the app credential is removed; integration shows Not Connected
2App disabled in Confluence admin (Manage Apps toggle)Real-time events are silently dropped while disabled — the integration may still display as connected, so this is easy to miss
3Site URL changes (site rename/migration)The stored site linkage breaks; reinstall required
**Installer leaving: no impact.** The app credential persists regardless of any individual's account status. #### How to reconnect 1. Reinstall (or re-enable) the Nightfall app from **Confluence Settings → Manage apps** / Atlassian Marketplace. Reinstallation automatically re-issues the credential and re-links to your Nightfall tenant. #### Best practices * Add the Nightfall Confluence app to your do-not-disable/do-not-uninstall app list — the "disabled" state silently stops scanning without an obvious status change. * After a Confluence site rename or migration, plan to reinstall the Nightfall app as part of the migration runbook. *** ### 8. Salesforce #### How authentication works Nightfall for Salesforce uses **OAuth 2.0 (authorization code + PKCE)**. A Salesforce user authorizes the Nightfall connected app; Salesforce issues a long-lived refresh token (stored encrypted by Nightfall) **bound to that user**. OAuth scopes: `api`, `refresh_token`, `id`, `content`. In addition, the **Nightfall managed package** must be installed in the org. The package provides the real-time event plumbing (object triggers, platform events, and the webhook authentication secret). Both the OAuth authorization *and* the package are required. #### What can cause a disconnection
#CauseEffect
1Refresh token revoked or invalidated — the authorizing user is deactivated/frozen, revokes Nightfall from their personal settings, an admin revokes tokens on the Connected App, or an org token policy expires it (the most common cause)All API access fails; the org shows Token Expired in Nightfall. Re-authorization required
2Connected App OAuth policies tightened (e.g., refresh token validity changed to a short fixed lifetime, or IP restrictions added)Tokens expire on the new schedule; recurring Token Expired states
3Nightfall managed package uninstalledReal-time scanning and remediation plumbing disappears, and reconnection attempts fail until the package is reinstalled — even if the OAuth token is still valid
4Sandbox refresh — refreshing a sandbox keeps its URL but creates a new org identityThe old connection becomes stale; the refreshed sandbox must be re-authorized as a (re)new connection
5Org deleted or unreachable (e.g., sandbox deleted)Connection shows as deleted/disconnected
#### How to reconnect 1. Confirm the **Nightfall managed package** is still installed (**Setup → Installed Packages**). Reinstall it first if missing. 2. From the Nightfall console, re-run the Salesforce authorization for the affected org, signing in as your integration user. Re-authorizing the same org automatically reactivates it and replaces the stored tokens. 3. For a refreshed sandbox, run the authorization flow against the refreshed sandbox; Nightfall links the new org identity and retires the stale record. #### Best practices * **Authorize with a dedicated integration user** (e.g., a user with a Salesforce Integration license or a service account) that has **API Enabled** and read access to the objects/files you scan, and that is excluded from deactivation during offboarding. This is the highest-value preventive action for Salesforce. * If your Connected App policies enforce refresh-token expiry, align the expiry with a scheduled re-authorization cadence — or exempt the Nightfall connected app. * Add the Nightfall managed package to your do-not-uninstall list. * After every sandbox refresh, include "re-authorize Nightfall" in the refresh runbook. * If the authorizing user must be deactivated, re-authorize as the integration user **first**. *** ### 9. GitHub #### How authentication works Nightfall for GitHub is a **GitHub App**. During setup, an **organization admin** installs the app on your GitHub org and chooses which repositories it can access; a brief sign-in identifies the installer, but that is recorded only as onboarding metadata. All ongoing scanning authenticates with **short-lived installation access tokens** that Nightfall mints from the app's credentials — no user token is involved, and nothing is bound to the installing admin's GitHub account. #### What can cause a disconnection
#CauseEffect
1App uninstalled from the GitHub organization (Org Settings → GitHub Apps)Total outage — the integration immediately shows Not Connected
2App suspended in GitHub org settingsTreated the same as an uninstall — Not Connected until unsuspended
3Repository access reduced post-install (repos deselected from the app's access list)Deselected repositories silently drop out of scanning coverage; the integration overall stays connected
4Integration deleted from the Nightfall consoleNightfall uninstalls the app from your org and removes the connection
**Installer leaving: no impact.** The installation belongs to the organization, not to the admin who performed the install. #### How to reconnect 1. Reinstall **Nightfall for GitHub** from the Nightfall console (or unsuspend the app in **GitHub Org Settings → GitHub Apps** if it was suspended). The installer must be a GitHub **organization admin** — installation by a non-admin stalls as a pending approval request. 2. Re-confirm the repository selection during install, then verify the integration shows Connected. #### Best practices * Add the Nightfall GitHub App to your org's do-not-uninstall/do-not-suspend list; suspension looks reversible but stops all scanning while active. * When adding new repositories you want scanned, remember to grant the app access to them (or select "All repositories") — repo selection is controlled in GitHub, not in Nightfall. * After any GitHub org audit that touches installed GitHub Apps, verify Nightfall's repo access list is intact. *** ### 10. Notion #### How authentication works Nightfall for Notion is installed via **Notion's public OAuth flow** (Notion Marketplace). When a Notion workspace member with permission to install integrations (typically a workspace owner/admin) completes the authorization, Notion issues a **workspace-level bot token** to Nightfall. That token belongs to the workspace — not to the person who authorized it — so the installer leaving the organization does not, by itself, break the integration. **Scanning coverage follows Notion's sharing model:** the Nightfall integration can only read pages and databases that have been shared with it (per Notion's integration-access rules and the selections made during authorization). Content not accessible to the integration is silently outside scanning coverage. #### What can cause a disconnection
#CauseEffect
1Integration removed from the Notion workspace (Notion Settings → My Connections / Integrations)API calls fail with authorization errors. Important: Notion does not always notify Nightfall of the removal, so the console may continue to show Connected while scanning has silently stopped
2Bot token revoked or integration capabilities reduced on the Notion sideSome or all API calls fail; same silent-failure caveat — the console status may not change
3Pages/databases unshared from the integrationNot a disconnection, but those pages drop out of scanning coverage without any error
4Integration deleted from the Nightfall consoleShows Not Connected; a deliberate disconnect
#### How to reconnect 1. If any Nightfall policies reference the Notion workspace, detach or delete them first — deletion of the installation is blocked while policies reference it. 2. Delete the existing Notion installation from the Nightfall console (this works even if the token was already revoked on the Notion side). 3. Re-run the Notion authorization from the Nightfall console, signing in as a workspace admin. Note: a workspace can only be connected once — the old installation must be deleted before re-authorizing, and a workspace already connected to a different Nightfall tenant cannot be connected again. #### Best practices * Because a Notion-side removal can be invisible to the console, **verify scanning is producing findings after any change to workspace integrations or connections in Notion** — don't rely on the Connected status alone. * Keep the pages/databases you want scanned shared with the Nightfall integration; review integration access after major workspace restructures. * Keep the integration's capabilities intact (including "read user information"), as reducing them degrades functionality without an obvious status change. *** ### 11. Gmail & Exchange Online (Inline Email DLP) #### How it works — and why "disconnection" doesn't apply Unlike the integrations above, inline email DLP is **not an OAuth or token-based integration**. Nightfall never stores a credential for your Google Workspace or Microsoft 365 email environment. Instead, **mail-routing rules that you configure in your email platform** direct outbound messages through Nightfall's scanning relay: * **Gmail:** Content compliance / routing rules in the Google Admin Console route messages to Nightfall and stamp a Nightfall identification header. After scanning, Nightfall delivers the message onward through Google's SMTP relay (secured by TLS certificates and IP allowlisting — Nightfall's relay IPs must be allowlisted in your Gmail SMTP relay settings). * **Exchange Online:** Mail flow rules / connectors in the Exchange admin center route messages to Nightfall. After scanning, Nightfall delivers onward to your domain's Microsoft 365 mail host (the `*.mail.protection.outlook.com` relay address you provide during setup). Additional mail flow rules act on Nightfall's remediation headers (e.g., to divert quarantined messages). Because there is no stored token, **there is nothing to expire or revoke, and no person is bound to the integration** — an admin leaving the organization has no effect. #### What can break mail scanning (it won't look like a "disconnection") The console's connected status for email reflects setup completion, not live mail flow — so email issues usually appear as **delivery problems or missing findings while the integration still shows Connected**. The causes are configuration drift:
#CauseEffect
1Routing / content compliance / mail flow rule deleted, disabled, or re-scoped (e.g., an OU or group change excludes users)Affected mail silently bypasses Nightfall — no scanning, no errors visible to Nightfall
2The Nightfall identification header removed from the rule (Gmail content compliance custom header)Nightfall cannot attribute the mail to your tenant; messages are not scanned. Misconfigured rule headers can also cause mail-loop bounces
3Nightfall's relay IPs removed from the Gmail SMTP relay allowlistOutbound delivery fails with relay/credential errors; senders receive bounce notifications
4Exchange relay host out of date — your domain's MX/mail host changed (e.g., domain migration) but the relay address configured in Nightfall wasn't updatedScanned mail for that domain fails to deliver
5Quarantine/remediation rules removed (rules matching Nightfall's remediation headers)Scanning continues, but quarantine/block actions stop being enforced
#### How to restore mail flow 1. Verify the routing/compliance rules (Gmail) or mail flow rules and connectors (Exchange Online) still exist, are enabled, and cover the intended users — recreate them from the Nightfall help center setup guide if needed. 2. Gmail: confirm Nightfall's relay IP addresses are still allowlisted in **Google Admin → Apps → Google Workspace → Gmail → Routing/SMTP relay** settings. 3. Exchange Online: confirm the relay host configured in the Nightfall console still matches your domain's current Microsoft 365 mail host. 4. If the integration shows Not Connected in the console (rare — it means setup was removed), re-run email onboarding from the Nightfall console. #### Best practices * Treat the Nightfall mail rules as protected infrastructure: document them, and require change-management review before anyone edits Gmail routing/compliance rules or Exchange mail flow rules. * Include "verify Nightfall mail rules and relay settings" in your runbook for email domain migrations and MX changes. * Periodically send a test message containing benign test data to confirm end-to-end scanning, since rule misconfiguration is silent. *** ### 12. FAQ **Q: The person who set up one of our integrations is leaving. What should we do?** A: Before their accounts are deactivated, re-authorize the affected integrations with a dedicated service account. Priority order: **Slack and Salesforce** (full outage risk), then **Google Drive** (admin functions and connection status break), then **Jira** (remediation breaks; scanning continues). Microsoft 365, Confluence, and GitHub are unaffected by personnel changes. **Q: Our integration shows "Connected" but we've stopped receiving findings. How?** A: Four known patterns: (1) **Microsoft 365** — Graph change-notification subscriptions can lapse without changing the connection status, stalling real-time scanning; (2) **Jira/Confluence** — disabling (not uninstalling) the Marketplace app silently drops events; (3) **Notion** — removing the integration or revoking its token on the Notion side isn't always reported to Nightfall, so the console can show Connected while scans fail; (4) **Gmail/Exchange Online** — email scanning depends on mail-routing rules in your email platform, so a deleted or re-scoped rule silently stops scanning while the console still shows Connected. Check the app-enabled/connection state in the source platform's admin console, and contact Nightfall support for M365 subscription issues. **Q: Slack is disconnected and re-authorizing from the Nightfall console doesn't fix it. Why?** A: The original installer's Slack account was probably deactivated. Slack keeps the app installation bound to that user, so re-running OAuth isn't enough. A Slack admin must **uninstall the Nightfall app from Slack's Manage Apps page first**, then reinstall from the Nightfall console. If the integration appears stuck even after this, contact Nightfall support. **Q: Which integrations survive employee offboarding without any action?** A: Microsoft 365, Confluence, and GitHub are fully app-level. Google Drive's file scanning uses a service account, but the registered admin email is still load-bearing (directory sync, audit logs, connection checks) — so plan a re-connection if that admin leaves. Jira scanning survives, but remediation doesn't. **Q: A security review wants to trim the permissions Nightfall has. What's safe to remove?** A: None of the granted scopes/permissions are decorative — each maps to product functionality (scanning, directory sync, audit monitoring, remediation). Removing scopes causes partial, often confusing breakage (e.g., trimming Google Drive's audit scope breaks exfiltration monitoring while file scanning continues). If you want to reduce Nightfall's footprint, disable the corresponding product feature first, and involve Nightfall support. **Q: How do we know when the Microsoft 365 client secret expires?** A: The expiry date is shown in the M365 integration settings in the Nightfall console. Renewal requires a Global Administrator (or Privileged Role Administrator) to re-authenticate, so calendar it in advance — the secret expiring is the most common cause of M365 disconnections. **Q: Does uninstalling and reinstalling an integration lose our policies or history?** A: Policies and historical findings live in Nightfall, not in the SaaS-side installation, and reconnecting re-links them. However, you should verify policy scoping (e.g., selected channels/sites/repos) after any reinstall, since the set of resources visible to Nightfall can change with the new authorization. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.nightfall.ai/nightfall_integrations/saas-apps-authorization-authentication-and-best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.