> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace integration setup

> Connect Google Workspace to Living Security for user lifecycle, sign-in, MFA, administrative, and data-protection activity.

export const PublicIntegrationNextSteps = () => <>
    <hr />
    <h2>Related resources</h2>
    <ul>
      <li>
        <a href="/signals/data-sources">Learn how integration data becomes Human Risk Management signals</a>
      </li>
      <li>
        <a href="https://www.livingsecurity.com/integrations">Explore Living Security integrations</a>
      </li>
      <li>
        <a href="https://app.livingsecurity.ai/">Open the Living Security Platform</a>
      </li>
      <li>
        <a href="https://www.livingsecurity.com/request-demo/">Request a Living Security demo</a>
      </li>
    </ul>
  </>;

export const ConnectInPlatform = ({tile, children}) => <Step title="Enter the credentials in the Living Security Platform">
    <p>
      Completed by whoever holds Living Security access — the program owner, or the system
      admin if they've been invited (delegated setup).
    </p>
    <ol>
      <li>
        Go to <strong>Settings → Integrations → Catalog</strong>, find the{' '}
        <strong>{tile}</strong> tile, click <strong>Connect</strong>.
      </li>
      <li>
        Fill in the fields below, then click <strong>Connect</strong>.
      </li>
    </ol>
    {children}
  </Step>;

export const SystemAdminBanner = ({system, recommendDelegated}) => <Note>
    <p>
      <strong>This guide is for your {system} administrator.</strong> It covers creating API
      credentials inside {system}, which requires admin access to {system} — not to the
      Living Security Platform.
    </p>
    <p>
      If you're the Living Security <strong>program owner</strong> and don't administer {system},
      send this page to whoever does. They complete Part A and hand the credentials back to you
      (or enter them directly if you've invited them into the platform).
      {recommendDelegated && <>
          {' '}Because setup produces sensitive key material, we recommend the{' '}
          <strong>delegated setup</strong> path so the secret is never sent back to you.
        </>}
    </p>
  </Note>;

<SystemAdminBanner system="Google Workspace" recommendDelegated={true} />

## What this integration contributes

Google Workspace can contribute normalized user lifecycle, sign-in, MFA, administrative, and data-protection activity. Reviewed examples include:

* `account.compromised` — account flagged as compromised
* `data.sensitive.downloaded` — downloads sensitive data
* `auth.login.unusual` — signs in from unusual contexts

See [how integration data becomes signals](/signals/data-sources).

## What Living Security needs

| Credential                  | Description                                                                      |
| --------------------------- | -------------------------------------------------------------------------------- |
| **Service-account key**     | A JSON key for a dedicated Google Cloud service account.                         |
| **Delegated administrator** | A Google Workspace administrator email that the service account can impersonate. |

Enable the Admin SDK APIs and authorize only the scopes the connection reads:

* `https://www.googleapis.com/auth/admin.reports.audit.readonly`
* `https://www.googleapis.com/auth/admin.directory.user.readonly`
* `https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly`

## Setup

<Steps>
  <Step title="Create a Google Cloud service account">
    Create a dedicated service account, enable domain-wide delegation, and download its JSON key. Store the key securely.
  </Step>

  <Step title="Authorize domain-wide delegation">
    In the Google Admin Console, open **Security → Access and data control → API controls → Manage Domain Wide Delegation**. Add the service account's numeric client ID and the three read-only scopes above.
  </Step>

  <Step title="Choose the delegated administrator">
    Select an active Workspace administrator who can read the directory, role assignments, and audit reports. Living Security uses this identity only for delegated API reads.
  </Step>

  <ConnectInPlatform tile="Google Workspace Admin">
    Upload or paste the service-account credential as prompted and enter the delegated administrator email.
  </ConnectInPlatform>
</Steps>

## Verify and troubleshoot

Verify that the connection can read one directory user and recent login activity. Google notes that new domain-wide delegation grants can take time to propagate.

<AccordionGroup>
  <Accordion title="unauthorized_client">
    Confirm that domain-wide delegation uses the service account's numeric client ID, not its email address, and that all three scopes match exactly.
  </Accordion>

  <Accordion title="Directory works but role assignments are missing">
    Add `admin.directory.rolemanagement.readonly` to the delegation entry and confirm the delegated administrator can view role assignments.
  </Accordion>

  <Accordion title="Reports are empty">
    Confirm that the Admin Reports API is enabled and that the delegated administrator can access audit reporting for the Workspace tenant.
  </Accordion>
</AccordionGroup>

For vendor-side details, see [Google's domain-wide delegation guide](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority).

<PublicIntegrationNextSteps />