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
15 export 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.
31 export const domains = { "admin. googleapis. com" : "read_write" } ;
32
33 const USERS = "https://admin. googleapis. com/admin/directory/v1/users" ;
34
35 type Grant = { kind : "token" | "app password" ; name : string ; url : string } ;
36
37 export 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 }
39 more lines 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 }
100 more lines 61 more lines 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 }
46 more lines 138 more lines 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 } ` ;
1 more line