Google Workspace Account Lockdown
Draft
Google Workspace Account Lockdown
Draft
Press a step to see its codeLook up the account, lines 40 to 60Revoke third-party app access, lines 62 to 114Require a new password at next sign-in, lines 116 to 126Sign out every session, lines 128 to 137Note it on the ticket, lines 139 to 159

Look up the account

An alias works too; the summary names the primary address.

lookup.status_code === 404

Fail

No Google account for ${params.user_email}. Check the address.

lookup.status_code !== 200

Fail

Lookup failed (${lookup.status_code}). Check the Google connection.

lookup.body.suspended === true

Fail

${email} is already suspended. Hand the ticket to IT.

lookup.body.isAdmin === true || lookup.body.isDelegatedAdmin === true

Fail

${email} is an admin, so a person locks it down. Hand it to IT.

Revoke third-party app access

Each OAuth token and app password is deleted, one call per grant.

params.revoke_app_access

tokens.status_code !== 200 || asps.status_code !== 200

Fail

Could not list ${email}'s app access. Nothing was changed.

for (const grant of grants)

Require a new password at next sign-in

flag.status_code !== 200

Fail

Google refused the flag (${flag.status_code}). Run it again.

Sign out every session

signOut.status_code >= 300

Fail

Google refused the sign-out (${signOut.status_code}). Run it again.

Note it on the ticket

A run with no ticket, from MCP or an automation, skips the note.

ticket !== null

Return

return

true
false
true
false
true
false
true
false
true
true
false
done
false
true
false
true
false
true
false
1// Contain a Google Workspace account after a suspected compromise or a
2// sudden departure: revoke the access third-party apps hold, require a new
3// password at the next sign-in, and sign the person out of every session.
4// Notes the outcome on the ticket when there is one.
5//
6// It never handles a password. If the current one may be known to someone
7// else, also reset it with the Google Workspace reset password tool, which
8// sends the new one by direct message. The next-sign-in flag doesn't apply to
9// people who sign in through another identity provider.
10//
11// Before publishing: connect Google Workspace on the Tool connectors page.
12// The admin who connects it approves the two scopes below and needs the User
13// Management admin privilege. No key is stored in this tool.
14
15export const input = z.object({
16 user_email: z
17 .string()
18 .email()
19 .describe("The Google Workspace account to lock down, e.g. sam@acme.com"),
20 revoke_app_access: z
21 .boolean()
22 .default(true)
23 .describe(
24 "Revoke the OAuth tokens and app passwords third-party apps use; " +
25 "turn off to keep the person's app connections working",
26 ),
27});
28
29// PUT, POST and DELETE need a "read_write" posture; publishing a script with
30// one forces the tool's approval requirement on.
31export const domains = { "admin.googleapis.com": "read_write" };
32
33const USERS = "https://admin.googleapis.com/admin/directory/v1/users";
34
35type Grant = { kind: "token" | "app password"; name: string; url: string };
36
37export default async function run(params: z.infer<typeof input>) {
38 const userUrl = `${USERS}/${encodeURIComponent(params.user_email)}`;
39
40 // **Look up the account**
41 // An alias works too; the summary names the primary address.
42 const lookup = await http.get(userUrl, {
43 auth: {
44 type: "google",
45 scopes: ["https://www.googleapis.com/auth/admin.directory.user"],
46 },
47 });
48 if (lookup.status_code === 404) {
49 fail(`No Google account for ${params.user_email}. Check the address.`);
50 }
51 if (lookup.status_code !== 200) {
52 fail(`Lookup failed (${lookup.status_code}). Check the Google connection.`);
53 }
54 const email: string = lookup.body.primaryEmail;
55 if (lookup.body.suspended === true) {
56 fail(`${email} is already suspended. Hand the ticket to IT.`);
57 }
58 if (lookup.body.isAdmin === true || lookup.body.isDelegatedAdmin === true) {
59 fail(`${email} is an admin, so a person locks it down. Hand it to IT.`);
60 }
61
62 // **Revoke third-party app access**
63 // Each OAuth token and app password is deleted, one call per grant.
64
65 // Order matters: revoke app access and set the flag before the sign-out,
66 // so nothing can sign back in on the old grants in between.
67 const revoked: Grant[] = [];
68 const missed: Grant[] = [];
69 if (params.revoke_app_access) {
70 const tokens = await http.get(`${userUrl}/tokens`, {
71 auth: {
72 type: "google",
73 scopes: [
74 "https://www.googleapis.com/auth/admin.directory.user.security",
75 ],
76 },
77 });
78 const asps = await http.get(`${userUrl}/asps`, {
79 auth: {
80 type: "google",
81 scopes: [
82 "https://www.googleapis.com/auth/admin.directory.user.security",
83 ],
84 },
85 });
86 if (tokens.status_code !== 200 || asps.status_code !== 200) {
87 fail(`Could not list ${email}'s app access. Nothing was changed.`);
88 }
89 const grants: Grant[] = [
90 ...(tokens.body.items ?? []).map(
91 (t: { clientId: string; displayText: string }) => ({
92 kind: "token" as const,
93 name: t.displayText,
94 url: `${userUrl}/tokens/${encodeURIComponent(t.clientId)}`,
95 }),
96 ),
97 ...(asps.body.items ?? []).map((a: { codeId: number; name: string }) => ({
98 kind: "app password" as const,
99 name: a.name,
100 url: `${userUrl}/asps/${a.codeId}`,
101 })),
102 ];
103 for (const grant of grants) {
104 const removed = await http.delete(grant.url, {
105 auth: {
106 type: "google",
107 scopes: [
108 "https://www.googleapis.com/auth/admin.directory.user.security",
109 ],
110 },
111 });
112 (removed.status_code < 300 ? revoked : missed).push(grant);
113 }
114 }
115
116 // **Require a new password at next sign-in**
117 const flag = await http.put(userUrl, {
118 json: { changePasswordAtNextLogin: true },
119 auth: {
120 type: "google",
121 scopes: ["https://www.googleapis.com/auth/admin.directory.user"],
122 },
123 });
124 if (flag.status_code !== 200) {
125 fail(`Google refused the flag (${flag.status_code}). Run it again.`);
126 }
127
128 // **Sign out every session**
129 const signOut = await http.post(`${userUrl}/signOut`, {
130 auth: {
131 type: "google",
132 scopes: ["https://www.googleapis.com/auth/admin.directory.user.security"],
133 },
134 });
135 if (signOut.status_code >= 300) {
136 fail(`Google refused the sign-out (${signOut.status_code}). Run it again.`);
137 }
138
139 // **Note it on the ticket**
140 // A run with no ticket, from MCP or an automation, skips the note.
141 const tokenCount = revoked.filter((g) => g.kind === "token").length;
142 const aspCount = revoked.length - tokenCount;
143 const apps = params.revoke_app_access
144 ? `revoked ${tokenCount} app tokens and ${aspCount} app passwords, `
145 : "left app access in place, ";
146 const done =
147 `Locked down ${email}: ${apps}required a new password at next ` +
148 "sign-in and signed out every session.";
149 const leftover =
150 missed.length === 0
151 ? ""
152 : ` Could not revoke: ${missed.map((g) => g.name).join(", ")}. ` +
153 "Run the tool again to retry them.";
154 const ticket = await risotto.get_ticket();
155 if (ticket !== null) {
156 await risotto.add_ticket_comment({ comment: done + leftover });
157 }
158 const lag = " Sign-out can take a few minutes to reach every device.";
159 return `${done}${leftover}${lag}`;
160}
40 // **Look up the account**
41 // An alias works too; the summary names the primary address.
42 const lookup = await http.get(userUrl, {
43 auth: {
44 type: "google",
45 scopes: ["https://www.googleapis.com/auth/admin.directory.user"],
46 },
47 });
48 if (lookup.status_code === 404) {
49 fail(`No Google account for ${params.user_email}. Check the address.`);
50 }
51 if (lookup.status_code !== 200) {
52 fail(`Lookup failed (${lookup.status_code}). Check the Google connection.`);
53 }
54 const email: string = lookup.body.primaryEmail;
55 if (lookup.body.suspended === true) {
56 fail(`${email} is already suspended. Hand the ticket to IT.`);
57 }
58 if (lookup.body.isAdmin === true || lookup.body.isDelegatedAdmin === true) {
59 fail(`${email} is an admin, so a person locks it down. Hand it to IT.`);
60 }
62 // **Revoke third-party app access**
63 // Each OAuth token and app password is deleted, one call per grant.
64
65 // Order matters: revoke app access and set the flag before the sign-out,
66 // so nothing can sign back in on the old grants in between.
67 const revoked: Grant[] = [];
68 const missed: Grant[] = [];
69 if (params.revoke_app_access) {
70 const tokens = await http.get(`${userUrl}/tokens`, {
71 auth: {
72 type: "google",
73 scopes: [
74 "https://www.googleapis.com/auth/admin.directory.user.security",
75 ],
76 },
77 });
78 const asps = await http.get(`${userUrl}/asps`, {
79 auth: {
80 type: "google",
81 scopes: [
82 "https://www.googleapis.com/auth/admin.directory.user.security",
83 ],
84 },
85 });
86 if (tokens.status_code !== 200 || asps.status_code !== 200) {
87 fail(`Could not list ${email}'s app access. Nothing was changed.`);
88 }
89 const grants: Grant[] = [
90 ...(tokens.body.items ?? []).map(
91 (t: { clientId: string; displayText: string }) => ({
92 kind: "token" as const,
93 name: t.displayText,
94 url: `${userUrl}/tokens/${encodeURIComponent(t.clientId)}`,
95 }),
96 ),
97 ...(asps.body.items ?? []).map((a: { codeId: number; name: string }) => ({
98 kind: "app password" as const,
99 name: a.name,
100 url: `${userUrl}/asps/${a.codeId}`,
101 })),
102 ];
103 for (const grant of grants) {
104 const removed = await http.delete(grant.url, {
105 auth: {
106 type: "google",
107 scopes: [
108 "https://www.googleapis.com/auth/admin.directory.user.security",
109 ],
110 },
111 });
112 (removed.status_code < 300 ? revoked : missed).push(grant);
113 }
114 }
116 // **Require a new password at next sign-in**
117 const flag = await http.put(userUrl, {
118 json: { changePasswordAtNextLogin: true },
119 auth: {
120 type: "google",
121 scopes: ["https://www.googleapis.com/auth/admin.directory.user"],
122 },
123 });
124 if (flag.status_code !== 200) {
125 fail(`Google refused the flag (${flag.status_code}). Run it again.`);
126 }
128 // **Sign out every session**
129 const signOut = await http.post(`${userUrl}/signOut`, {
130 auth: {
131 type: "google",
132 scopes: ["https://www.googleapis.com/auth/admin.directory.user.security"],
133 },
134 });
135 if (signOut.status_code >= 300) {
136 fail(`Google refused the sign-out (${signOut.status_code}). Run it again.`);
137 }
139 // **Note it on the ticket**
140 // A run with no ticket, from MCP or an automation, skips the note.
141 const tokenCount = revoked.filter((g) => g.kind === "token").length;
142 const aspCount = revoked.length - tokenCount;
143 const apps = params.revoke_app_access
144 ? `revoked ${tokenCount} app tokens and ${aspCount} app passwords, `
145 : "left app access in place, ";
146 const done =
147 `Locked down ${email}: ${apps}required a new password at next ` +
148 "sign-in and signed out every session.";
149 const leftover =
150 missed.length === 0
151 ? ""
152 : ` Could not revoke: ${missed.map((g) => g.name).join(", ")}. ` +
153 "Run the tool again to retry them.";
154 const ticket = await risotto.get_ticket();
155 if (ticket !== null) {
156 await risotto.add_ticket_comment({ comment: done + leftover });
157 }
158 const lag = " Sign-out can take a few minutes to reach every device.";
159 return `${done}${leftover}${lag}`;
Config you will fill in

None. It signs in through your Google Workspace connection, so there is no key to store.