Skip to content

Commit bbc704f

Browse files
TheodoreSpeaksTheodore Li
TheodoreSpeaks
and
Theodore Li
authored
feat(credentials) Add google service account support (#3828)
* feat(auth): allow google service account * Add gmail support for google services * Refresh creds on typing in impersonated email * Switch to adding subblock impersonateUserEmail conditionally * Directly pass subblock for impersonateUserEmail * Fix lint * Update documentation for google service accounts * Fix lint * Address comments * Remove hardcoded scopes, remove orphaned migration script * Simplify subblocks for google service account * Fix lint * Fix build error * Fix documentation scopes listed for google service accounts * Fix issue with credential selector, remove bigquery and ad support * create credentialCondition * Shift conditional render out of subblock * Simplify sublock values * Fix security message * Handle tool service accounts * Address bugbot * Fix lint * Fix manual credential input not showing impersonate * Fix tests * Allow watching param id and subblock ids * Fix bad test --------- Co-authored-by: Theodore Li <theo@sim.ai>
1 parent c016537 commit bbc704f

File tree

66 files changed

+16296
-179
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+16296
-179
lines changed

‎apps/docs/content/docs/en/credentials/google-service-account.mdx‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Google Service Accounts
3+
description: Set up Google service accounts with domain-wide delegation for Gmail, Sheets, Drive, Calendar, and other Google services
4+
---
5+
6+
import { Callout } from 'fumadocs-ui/components/callout'
7+
import { Step, Steps } from 'fumadocs-ui/components/steps'
8+
import { Image } from '@/components/ui/image'
9+
import { FAQ } from '@/components/ui/faq'
10+
11+
Google service accounts with domain-wide delegation let your workflows access Google APIs on behalf of users in your Google Workspace domain — without requiring each user to complete an OAuth consent flow. This is ideal for automated workflows that need to send emails, read spreadsheets, or manage files across your organization.
12+
13+
For example, you could build a workflow that iterates through a list of employees, impersonates each one to read their Google Docs, and uploads the contents to a shared knowledge base — all without requiring any of those users to sign in.
14+
15+
## Prerequisites
16+
17+
Before adding a service account to Sim, you need to configure it in the Google Cloud Console and Google Workspace Admin Console.
18+
19+
### 1. Create a Service Account in Google Cloud
20+
21+
<Steps>
22+
<Step>
23+
Go to the [Google Cloud Console](https://console.cloud.google.com/) and select your project (or create one)
24+
</Step>
25+
<Step>
26+
Navigate to **IAM & Admin** → **Service Accounts**
27+
</Step>
28+
<Step>
29+
Click **Create Service Account**, give it a name and description, then click **Create and Continue**
30+
31+
<div className="flex justify-center">
32+
<Image
33+
src="/static/credentials/gcp-create-service-account.png"
34+
alt="Google Cloud Console — Create service account form"
35+
width={700}
36+
height={500}
37+
className="my-4"
38+
/>
39+
</div>
40+
</Step>
41+
<Step>
42+
Skip the optional role and user access steps and click **Done**
43+
</Step>
44+
<Step>
45+
Click on the newly created service account, go to the **Keys** tab, and click **Add Key** → **Create new key**
46+
</Step>
47+
<Step>
48+
Select **JSON** as the key type and click **Create**. A JSON key file will download — keep this safe
49+
50+
<div className="flex justify-center">
51+
<Image
52+
src="/static/credentials/gcp-create-private-key.png"
53+
alt="Google Cloud Console — Create private key dialog with JSON selected"
54+
width={700}
55+
height={400}
56+
className="my-4"
57+
/>
58+
</div>
59+
</Step>
60+
</Steps>
61+
62+
<Callout type="warn">
63+
The JSON key file contains your service account's private key. Treat it like a password — do not commit it to source control or share it publicly.
64+
</Callout>
65+
66+
### 2. Enable the Required APIs
67+
68+
In the Google Cloud Console, go to **APIs & Services** → **Library** and enable the APIs for the services your workflows will use. See the [scopes reference](#scopes-reference) below for the full list of APIs by service.
69+
70+
### 3. Set Up Domain-Wide Delegation
71+
72+
<Steps>
73+
<Step>
74+
In the Google Cloud Console, go to **IAM & Admin** → **Service Accounts**, click on your service account, and copy the **Client ID** (the numeric ID, not the email)
75+
</Step>
76+
<Step>
77+
Open the [Google Workspace Admin Console](https://admin.google.com/) and navigate to **Security** → **Access and data control** → **API controls**
78+
</Step>
79+
<Step>
80+
Click **Manage Domain Wide Delegation**, then click **Add new**
81+
</Step>
82+
<Step>
83+
Paste the **Client ID** from your service account, then add the OAuth scopes for the services your workflows need. Copy the full scope URLs from the [scopes reference](#scopes-reference) below — only authorize scopes for services you plan to use.
84+
85+
<div className="flex justify-center">
86+
<Image
87+
src="/static/credentials/gcp-add-client-id.png"
88+
alt="Google Workspace Admin Console — Add a new client ID with OAuth scopes"
89+
width={350}
90+
height={300}
91+
className="my-4"
92+
/>
93+
</div>
94+
</Step>
95+
<Step>
96+
Click **Authorize**
97+
</Step>
98+
</Steps>
99+
100+
<Callout type="info">
101+
Domain-wide delegation must be configured by a Google Workspace admin. If you are not an admin, send the Client ID and required scopes to your admin.
102+
</Callout>
103+
104+
### Scopes Reference
105+
106+
The table below lists every Google service that supports service account authentication in Sim, the API to enable in Google Cloud Console, and the delegation scopes to authorize. Copy the scope string for each service you need and paste it into the Google Workspace Admin Console.
107+
108+
<table>
109+
<thead>
110+
<tr>
111+
<th className="whitespace-nowrap">Service</th>
112+
<th className="whitespace-nowrap">API to Enable</th>
113+
<th>Delegation Scopes</th>
114+
</tr>
115+
</thead>
116+
<tbody>
117+
<tr><td>Gmail</td><td>Gmail API</td><td><code>{'https://www.googleapis.com/auth/gmail.send'}</code><br/><code>{'https://www.googleapis.com/auth/gmail.modify'}</code><br/><code>{'https://www.googleapis.com/auth/gmail.labels'}</code></td></tr>
118+
<tr><td>Google Sheets</td><td>Google Sheets API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
119+
<tr><td>Google Drive</td><td>Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
120+
<tr><td>Google Docs</td><td>Google Docs API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
121+
<tr><td>Google Slides</td><td>Google Slides API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/drive.file'}</code></td></tr>
122+
<tr><td>Google Forms</td><td>Google Forms API, Google Drive API</td><td><code>{'https://www.googleapis.com/auth/drive'}</code><br/><code>{'https://www.googleapis.com/auth/forms.body'}</code><br/><code>{'https://www.googleapis.com/auth/forms.responses.readonly'}</code></td></tr>
123+
<tr><td>Google Calendar</td><td>Google Calendar API</td><td><code>{'https://www.googleapis.com/auth/calendar'}</code></td></tr>
124+
<tr><td>Google Contacts</td><td>People API</td><td><code>{'https://www.googleapis.com/auth/contacts'}</code></td></tr>
125+
<tr><td>BigQuery</td><td>BigQuery API</td><td><code>{'https://www.googleapis.com/auth/bigquery'}</code></td></tr>
126+
<tr><td>Google Tasks</td><td>Tasks API</td><td><code>{'https://www.googleapis.com/auth/tasks'}</code></td></tr>
127+
<tr><td>Google Vault</td><td>Vault API, Cloud Storage API</td><td><code>{'https://www.googleapis.com/auth/ediscovery'}</code><br/><code>{'https://www.googleapis.com/auth/devstorage.read_only'}</code></td></tr>
128+
<tr><td>Google Groups</td><td>Admin SDK API</td><td><code>{'https://www.googleapis.com/auth/admin.directory.group'}</code><br/><code>{'https://www.googleapis.com/auth/admin.directory.group.member'}</code></td></tr>
129+
<tr><td>Google Meet</td><td>Google Meet API</td><td><code>{'https://www.googleapis.com/auth/meetings.space.created'}</code><br/><code>{'https://www.googleapis.com/auth/meetings.space.readonly'}</code></td></tr>
130+
</tbody>
131+
</table>
132+
133+
<Callout type="info">
134+
You only need to enable APIs and authorize scopes for the services you plan to use. When authorizing multiple services, combine their scope strings with commas into a single entry in the Admin Console.
135+
</Callout>
136+
137+
## Adding the Service Account to Sim
138+
139+
Once Google Cloud and Workspace are configured, add the service account as a credential in Sim.
140+
141+
<Steps>
142+
<Step>
143+
Open your workspace **Settings** and go to the **Integrations** tab
144+
</Step>
145+
<Step>
146+
Search for "Google Service Account" and click **Connect**
147+
148+
<div className="flex justify-center">
149+
<Image
150+
src="/static/credentials/integrations-service-account.png"
151+
alt="Integrations page showing Google Service Account"
152+
width={800}
153+
height={150}
154+
className="my-4"
155+
/>
156+
</div>
157+
</Step>
158+
<Step>
159+
Paste the full contents of your JSON key file into the text area
160+
<div className="flex justify-center">
161+
<Image
162+
src="/static/credentials/add-service-account.png"
163+
alt="Add Google Service Account dialog"
164+
width={350}
165+
height={420}
166+
className="my-6"
167+
/>
168+
</div>
169+
</Step>
170+
<Step>
171+
Give the credential a display name (the service account email is used by default)
172+
</Step>
173+
<Step>
174+
Click **Save**
175+
</Step>
176+
</Steps>
177+
178+
The JSON key file is validated for the required fields (`type`, `client_email`, `private_key`, `project_id`) and encrypted before being stored.
179+
180+
## Using Delegated Access in Workflows
181+
182+
When you use a Google block (Gmail, Sheets, Drive, etc.) in a workflow and select a service account credential, an **Impersonate User Email** field appears below the credential selector.
183+
184+
Enter the email address of the Google Workspace user you want the service account to act as. For example, if you enter `alice@yourcompany.com`, the workflow will send emails from Alice's account, read her spreadsheets, or access her calendar — depending on the scopes you authorized.
185+
186+
<div className="flex justify-center">
187+
<Image
188+
src="/static/credentials/workflow-impersonated-account.png"
189+
alt="Gmail block in a workflow showing the Impersonated Account field with a service account credential"
190+
width={800}
191+
height={350}
192+
className="my-4"
193+
/>
194+
</div>
195+
196+
<Callout type="warn">
197+
The impersonated email must belong to a user in the Google Workspace domain where you configured domain-wide delegation. Impersonating external email addresses will fail.
198+
</Callout>
199+
200+
<FAQ items={[
201+
{ question: "Can I use a service account without domain-wide delegation?", answer: "Yes, but it will only be able to access resources owned by the service account itself (e.g., spreadsheets shared directly with the service account email). Without delegation, you cannot impersonate users or access their personal data like Gmail." },
202+
{ question: "What happens if the impersonation email field is left blank?", answer: "The service account will authenticate as itself. This works for accessing shared resources (like a Google Sheet shared with the service account email) but will fail for user-specific APIs like Gmail." },
203+
{ question: "Can I use the same service account for multiple Google services?", answer: "Yes. A single service account can be used across Gmail, Sheets, Drive, Calendar, and other Google services — as long as the required API is enabled in Google Cloud and the corresponding scopes are authorized in the Workspace admin console." },
204+
{ question: "How do I rotate the service account key?", answer: "Create a new JSON key in the Google Cloud Console under your service account's Keys tab, then update the credential in Sim with the new key. Delete the old key from Google Cloud once the new one is working." },
205+
{ question: "Does the impersonated user need a Google Workspace license?", answer: "Yes. Domain-wide delegation only works with users who have a Google Workspace account in the domain. Consumer Gmail accounts (e.g., @gmail.com) cannot be impersonated." },
206+
]} />

‎apps/docs/content/docs/en/credentials/meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"title": "Credentials",
3+
"pages": ["index", "google-service-account"],
4+
"defaultOpen": false
5+
}

‎apps/docs/public/static/credentials/add-service-account.png‎

58.9 KB
Loading

‎apps/docs/public/static/credentials/gcp-add-client-id.png‎

75 KB
Loading

‎apps/docs/public/static/credentials/gcp-create-private-key.png‎

67 KB
Loading

‎apps/docs/public/static/credentials/gcp-create-service-account.png‎

92.2 KB
Loading

‎apps/docs/public/static/credentials/integrations-service-account.png‎

16.4 KB
Loading

‎apps/docs/public/static/credentials/workflow-impersonated-account.png‎

46.8 KB
Loading

‎apps/sim/app/api/auth/oauth/credentials/route.ts‎

Lines changed: 96 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,10 @@ import { z } from 'zod'
77
import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
88
import { generateRequestId } from '@/lib/core/utils/request'
99
import { syncWorkspaceOAuthCredentialsForUser } from '@/lib/credentials/oauth'
10-
import { getCanonicalScopesForProvider } from '@/lib/oauth/utils'
10+
import {
11+
getCanonicalScopesForProvider,
12+
getServiceAccountProviderForProviderId,
13+
} from '@/lib/oauth/utils'
1114
import { authorizeWorkflowByWorkspacePermission } from '@/lib/workflows/utils'
1215
import { checkWorkspaceAccess } from '@/lib/workspaces/permissions/utils'
1316

@@ -36,7 +39,8 @@ function toCredentialResponse(
3639
displayName: string,
3740
providerId: string,
3841
updatedAt: Date,
39-
scope: string | null
42+
scope: string | null,
43+
credentialType: 'oauth' | 'service_account' = 'oauth'
4044
) {
4145
const storedScope = scope?.trim()
4246
// Some providers (e.g. Box) don't return scopes in their token response,
@@ -52,6 +56,7 @@ function toCredentialResponse(
5256
id,
5357
name: displayName,
5458
provider: providerId,
59+
type: credentialType,
5560
lastUsed: updatedAt.toISOString(),
5661
isDefault: featureType === 'default',
5762
scopes,
@@ -149,6 +154,7 @@ export async function GET(request: NextRequest) {
149154
displayName: credential.displayName,
150155
providerId: credential.providerId,
151156
accountId: credential.accountId,
157+
updatedAt: credential.updatedAt,
152158
accountProviderId: account.providerId,
153159
accountScope: account.scope,
154160
accountUpdatedAt: account.updatedAt,
@@ -159,6 +165,49 @@ export async function GET(request: NextRequest) {
159165
.limit(1)
160166

161167
if (platformCredential) {
168+
if (platformCredential.type === 'service_account') {
169+
if (
170+
workflowId &&
171+
(!effectiveWorkspaceId || platformCredential.workspaceId !== effectiveWorkspaceId)
172+
) {
173+
return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
174+
}
175+
176+
if (!workflowId) {
177+
const [membership] = await db
178+
.select({ id: credentialMember.id })
179+
.from(credentialMember)
180+
.where(
181+
and(
182+
eq(credentialMember.credentialId, platformCredential.id),
183+
eq(credentialMember.userId, requesterUserId),
184+
eq(credentialMember.status, 'active')
185+
)
186+
)
187+
.limit(1)
188+
189+
if (!membership) {
190+
return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
191+
}
192+
}
193+
194+
return NextResponse.json(
195+
{
196+
credentials: [
197+
toCredentialResponse(
198+
platformCredential.id,
199+
platformCredential.displayName,
200+
platformCredential.providerId || 'google-service-account',
201+
platformCredential.updatedAt,
202+
null,
203+
'service_account'
204+
),
205+
],
206+
},
207+
{ status: 200 }
208+
)
209+
}
210+
162211
if (platformCredential.type !== 'oauth' || !platformCredential.accountId) {
163212
return NextResponse.json({ credentials: [] }, { status: 200 })
164213
}
@@ -238,14 +287,52 @@ export async function GET(request: NextRequest) {
238287
)
239288
)
240289

241-
return NextResponse.json(
242-
{
243-
credentials: credentialsData.map((row) =>
244-
toCredentialResponse(row.id, row.displayName, row.providerId, row.updatedAt, row.scope)
245-
),
246-
},
247-
{ status: 200 }
290+
const results = credentialsData.map((row) =>
291+
toCredentialResponse(row.id, row.displayName, row.providerId, row.updatedAt, row.scope)
248292
)
293+
294+
const saProviderId = getServiceAccountProviderForProviderId(providerParam)
295+
296+
if (saProviderId) {
297+
const serviceAccountCreds = await db
298+
.select({
299+
id: credential.id,
300+
displayName: credential.displayName,
301+
providerId: credential.providerId,
302+
updatedAt: credential.updatedAt,
303+
})
304+
.from(credential)
305+
.innerJoin(
306+
credentialMember,
307+
and(
308+
eq(credentialMember.credentialId, credential.id),
309+
eq(credentialMember.userId, requesterUserId),
310+
eq(credentialMember.status, 'active')
311+
)
312+
)
313+
.where(
314+
and(
315+
eq(credential.workspaceId, effectiveWorkspaceId),
316+
eq(credential.type, 'service_account'),
317+
eq(credential.providerId, saProviderId)
318+
)
319+
)
320+
321+
for (const sa of serviceAccountCreds) {
322+
results.push(
323+
toCredentialResponse(
324+
sa.id,
325+
sa.displayName,
326+
sa.providerId || saProviderId,
327+
sa.updatedAt,
328+
null,
329+
'service_account'
330+
)
331+
)
332+
}
333+
}
334+
335+
return NextResponse.json({ credentials: results }, { status: 200 })
249336
}
250337

251338
return NextResponse.json({ credentials: [] }, { status: 200 })

0 commit comments

Comments
 (0)