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

# Connect Google Workspace

> Step-by-step guide to connect Google Workspace for SSO discovery

# Connect Google Workspace to Porcia

Connect your Google Workspace to automatically discover all applications your team accesses via Google SSO.

## Prerequisites

* Google Workspace admin account
* Super Admin privileges in Google Workspace
* 5-10 minutes for setup

<Info>
  You need Super Admin access to grant the necessary permissions. If you don't have admin access, ask your IT administrator to set this up.
</Info>

## What Porcia Will Discover

Once connected, Porcia will discover:

<CardGroup cols={2}>
  <Card title="SAML Applications" icon="key">
    All SAML SSO apps configured in Google Workspace
  </Card>

  <Card title="OAuth Applications" icon="shield">
    Third-party apps with OAuth access to Google services
  </Card>

  <Card title="User Access" icon="users">
    Which team members have access to each application
  </Card>

  <Card title="Usage Patterns" icon="chart-line">
    Login frequency and usage analytics
  </Card>
</CardGroup>

## Step-by-Step Setup

<Steps>
  <Step title="Navigate to SSO Integration">
    Go to **Settings → Integrations → SSO** in your Porcia dashboard
  </Step>

  <Step title="Click 'Connect Google Workspace'">
    Click the **Connect Google Workspace** button
  </Step>

  <Step title="Review Privacy Notice">
    A privacy notice will appear explaining exactly what data Porcia collects (app names, user emails, login timestamps, OAuth scopes). You must check two acknowledgement boxes and click **Accept & Continue** to proceed.
  </Step>

  <Step title="Sign in with Admin Account">
    You'll be redirected to Google's sign-in page. **Important:** Sign in with your Google Workspace admin account, not a regular user account.
  </Step>

  <Step title="Review Permissions">
    Google will show the permissions Porcia is requesting:

    **Admin SDK API:**

    * View users on your domain
    * View groups on your domain
    * View organizational units on your domain

    **Reports API:**

    * View audit reports for your Google Workspace domain
    * View usage reports for your Google Workspace domain

    These permissions allow Porcia to discover applications and track usage.
  </Step>

  <Step title="Grant Admin Consent">
    Click **Allow** to grant Porcia access to your Google Workspace

    <Warning>
      If you see "This app isn't verified," click **Advanced → Go to Porcia (unsafe)**. This warning appears for apps with fewer than 100 users but Porcia is safe.
    </Warning>
  </Step>

  <Step title="Wait for Initial Sync">
    You'll be redirected back to Porcia. The initial sync will begin automatically and takes 5-10 minutes.

    Porcia will:

    * Discover all SSO applications
    * Map user access and permissions
    * Analyze recent login activity
    * Match applications to vendor database
  </Step>

  <Step title="View Discovered Applications">
    Once sync completes, go to your dashboard to see all discovered applications
  </Step>
</Steps>

## Permissions Explained

### What We Can Access

**User Directory (Read-Only):**

* ✅ User names and email addresses
* ✅ Group memberships
* ✅ Organizational unit structure
* ✅ User status (active/suspended)

**Application Catalog (Read-Only):**

* ✅ SAML applications configured
* ✅ OAuth applications with access
* ✅ Application names and logos
* ✅ User assignments to applications

**Usage Reports (Read-Only):**

* ✅ Login events and frequency
* ✅ Application usage statistics
* ✅ User activity patterns
* ✅ Security and audit logs

### What We CANNOT Do

* ❌ **Modify users** - We never add, remove, or change users
* ❌ **Change permissions** - We never modify app access or permissions
* ❌ **Access user data** - We never read emails, files, or personal data
* ❌ **Modify applications** - We never change SSO configurations
* ❌ **Send emails** - We never send emails on behalf of users

<Info>
  All permissions are read-only. Porcia cannot make any changes to your Google Workspace configuration.
</Info>

## What Gets Discovered

### SAML Applications

**Examples of SAML apps Porcia will find:**

* Salesforce
* Slack
* Zoom
* Atlassian (Jira, Confluence)
* Adobe Creative Cloud
* Okta (if using as secondary IdP)

**Information extracted:**

* Application name and logo
* Vendor identification
* User assignments
* Login frequency
* Last access date

### OAuth Applications

**Examples of OAuth apps Porcia will find:**

* Third-party apps with Google Drive access
* Apps using Google Calendar integration
* Apps with Gmail API access
* Google Workspace Marketplace apps

**Information extracted:**

* Application name and permissions
* OAuth scopes granted
* User consent status
* Usage frequency

### User Access Patterns

**Analytics Porcia provides:**

* Most used applications by team
* Unused application licenses
* Login frequency distribution
* Access pattern anomalies
* Shadow IT detection (apps added without IT approval)

## Troubleshooting

### Connection Failed

**Error: "Access denied"**

* Ensure you're signing in with a Super Admin account
* Check that the admin account has all necessary privileges
* Try signing out of all Google accounts and signing in again

**Error: "This app isn't verified"**

* Click **Advanced → Go to Porcia (unsafe)**
* This is a standard Google warning for newer applications
* Porcia is safe and only requests read-only access

**Error: "Admin consent required"**

* Your organization may require admin approval for new apps
* Contact your Google Workspace administrator
* They may need to pre-approve Porcia in the Admin Console

<Accordion title="Pre-approve Porcia in Google Admin Console">
  If your organization requires pre-approval:

  1. Go to **Google Admin Console → Security → API Controls**
  2. Click **Manage Third-Party App Access**
  3. Click **Add app → OAuth App Name or Client ID**
  4. Search for "Porcia" and click **Select**
  5. Select **Trusted** and click **Configure**
  6. Choose which organizational units can access Porcia
  7. Click **Finish**

  After pre-approval, users can connect without additional admin consent.
</Accordion>

### No Applications Discovered

**If no applications appear after sync:**

1. **Wait longer** - Large organizations can take 10-15 minutes for initial sync
2. **Check SSO usage** - Verify your organization actually uses Google SSO for third-party apps
3. **Verify admin permissions** - Ensure the connected account has Super Admin privileges
4. **Check organizational units** - Porcia may only have access to specific OUs

### Sync Stopped Working

**If sync stops after working initially:**

1. **Check connection status** - Go to Settings → Integrations → SSO
2. **Reconnect if needed** - Click **Reconnect** if status shows "Disconnected"
3. **Check admin account** - Verify the admin account is still active
4. **Check API limits** - Google has API rate limits; sync will resume automatically

<Info>
  **Need Help?** Check our [FAQ](/troubleshooting/faq) or contact [support@porcia.org](mailto:support@porcia.org) for SSO troubleshooting assistance.
</Info>

## Google Workspace Admin Console

### Viewing Connected Apps

To see all apps connected to your Google Workspace:

1. Go to **Google Admin Console → Security → API Controls**
2. Click **App access control**
3. View **Third-party apps with account access**

### Managing App Access

To control which apps can access your Google Workspace:

1. Go to **Google Admin Console → Security → API Controls**
2. Click **Manage Third-Party App Access**
3. Configure access for each app (Trusted, Limited, Blocked)

### Audit Logs

To view audit logs for app access:

1. Go to **Google Admin Console → Reporting → Audit and investigation**
2. Select **OAuth Token** or **SAML** events
3. Filter by application or user

## Data Sync Frequency

**Initial Sync:**

* Complete application catalog
* All user assignments
* 90 days of login history

**Ongoing Sync:**

* **Applications:** Daily (new apps, configuration changes)
* **User assignments:** Daily (new users, permission changes)
* **Usage data:** Daily (login events, activity)
* **Real-time events:** Via webhook (if available)

<Tip>
  You can manually trigger a sync anytime from Settings → Integrations → SSO → Sync Now.
</Tip>

## Privacy & Security

### Data Storage

* **User directory** - Names, emails, group memberships (encrypted)
* **Application catalog** - App names, logos, configurations
* **Usage analytics** - Login events, frequency (anonymized in reports)
* **Access patterns** - User-to-app relationships

### Data Protection

* **Encryption** - AES-256 at rest, TLS 1.3 in transit
* **Access control** - Only workspace admins can view detailed user data
* **Audit logs** - Complete audit trail of all sync activity
* **Token security** - OAuth tokens stored securely with encryption at rest

### Compliance

* **Data privacy** - Right to access, delete, and export data (GDPR compliance in progress)
* **Industry-standard security** - Follows security best practices for cloud integrations

<Info>
  **Security:** Porcia follows industry-standard security practices including end-to-end encryption and role-based access control. Full security documentation coming soon.
</Info>

## Disconnecting Google Workspace

To disconnect your Google Workspace:

1. Go to **Settings → Integrations → SSO**
2. Find Google Workspace connection
3. Click **Disconnect**
4. Confirm disconnection

<Info>
  Disconnecting will stop new application discovery and usage tracking. Historical data will be preserved unless you choose to delete it.
</Info>

### Revoke Access in Google

To completely revoke Porcia's access:

1. Go to **Google Admin Console → Security → API Controls**
2. Click **Manage Third-Party App Access**
3. Find "Porcia" in the list
4. Click **Block** or **Remove**

## Next Steps

<CardGroup cols={2}>
  <Card title="Connect Email" icon="envelope" href="/integrations/email/overview">
    Add email discovery for complete visibility
  </Card>

  <Card title="Install Extension" icon="puzzle-piece" href="/integrations/extension/installation">
    Track browser usage
  </Card>

  <Card title="Manage Vendors" icon="building" href="/features/vendor-management">
    Organize discovered applications
  </Card>

  <Card title="View Analytics" icon="chart-line" href="/features/spend-analytics">
    Analyze application usage
  </Card>
</CardGroup>