Zdravo!
Ovaj članak opisuje implementaciju interakcije PowerShell-a sa Google API-jem za manipulaciju korisnicima G Suite-a.
U organizaciji koristimo nekoliko internih i cloud servisa. Većinom se autorizacija svodi na Google ili Active Directory, između kojih ne možemo održavati replikaciju, pa kada novi zaposleni dođe, potrebno je kreirati/aktivirati nalog u ovim dvjema sistemima. Kako bismo automatizovali proces, odlučili smo napisati skript koji prikuplja informacije i šalje ih u oba servisa.
Autorizacija
Prilikom sastavljanja zahteva, odlučili smo koristiti stvarne ljude-adiministratore za autorizaciju, što olakšava razumevanje akcija u slučaju slučajnih ili namernih masovnih promena.
Za autentifikaciju i autorizaciju, Google API koristi OAuth 2.0 protokol. Scenariji korišćenja i detaljniji opis mogu se pogledati ovde: .
Odabrao sam scenario koji se koristi prilikom autorizacije u desktop aplikacijama. Takođe postoji mogućnost korišćenja servisnog naloga koji ne zahteva dodatne korake od korisnika.
Sličica ispod - to je shematski prikaz odabranog scenarija sa stranice Google-a.

- Prvo šaljemo korisnika na stranicu za autentifikaciju Google naloga, navodeći GET parametrima:
- identifikator aplikacije
- oblasti kojima aplikacija treba pristup
- adresu na koju će korisnik biti preusmeren nakon završetka procedure
- metod kojim ćemo ažurirati token
- verifikacioni kod
- format prenosa verifikacionog koda
- Nakon završetka autorizacije, korisnik će biti preusmeren na stranicu navedenu u prvom zahtevu, sa greškom ili autorizačnim kodom, koji se prenose GET parametrima.
- Aplikaciji (skriptu) biće potrebno da dobije te parametre i, u slučaju da dobije kod, izvrši sledeći zahtev za dobijanje tokena.
- U slučaju ispravnog zahteva, Google API vraća:
- Access token, sa kojim možemo slati zahteve.
- Period važenja ovog tokena.
- Refresh token, potreban za ažuriranje Access tokena.
Prvo treba otići na Google API konzolu: , odabrati odgovarajuću aplikaciju i u odjeljku Credentials stvoriti identifikator OAuth klijenta. Tamo (ili kasnije, u svojstvima stvorenog identifikatora) treba navesti adrese na koje je dozvoljeno preusmjeravanje. U našem slučaju, to će biti nekoliko unosa localhost s različitim portovima (vidi dalje).
Da bi se algoritam skripte lakše čitao, možemo izdvojiti prve korake u posebnu funkciju koja će vratiti Access i refresh tokene za aplikaciju:
$client_secret = 'Naša tajna klijenta'
$client_id = 'Naš identifikator klijenta'
function Get-GoogleAuthToken {
if (-not [System.Net.HttpListener]::IsSupported) {
"HttpListener nije podržan."
exit 1
}
$codeverifier = -join ((65..90) + (97..122) + (48..57) + 45 + 46 + 95 + 126 |Get-Random -Count 60| % {[char]$_})
$hasher = new-object System.Security.Cryptography.SHA256Managed
$hashByteArray = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($codeverifier))
$base64 = ((([System.Convert]::ToBase64String($hashByteArray)).replace('=','')).replace('+','-')).replace('\/','_')
$ports = @(10600,15084,39700,42847,65387,32079)
$port = $ports[(get-random -Minimum 0 -maximum 5)]
Write-Host "Pokreni pretraživač..."
Start-Process "https://accounts.google.com/o/oauth2/v2/auth?code_challenge_method=S256&code_challenge=$base64&access_type=offline&client_id=$client_id&redirect_uri=http://localhost:$port&response_type=code&scope=https://www.googleapis.com/auth/admin.directory.user https://www.googleapis.com/auth/admin.directory.group"
$listener = New-Object System.Net.HttpListener
$listener.Prefixes.Add("http://localhost:"+$port+'\/')
try {$listener.Start()} catch {
"Nije moguće pokrenuti slušatelja."
exit 1
}
while (($code -eq $null)) {
$context = $listener.GetContext()
Write-Host "Veza prihvaćena" -f 'mag'
$url = $context.Request.RawUrl
$code = $url.split('?')[1].split('=')[1].split('&')[0]
if ($url.split('?')[1].split('=')[0] -eq 'error') {
Write-Host "Greška!"$code -f 'red'
$buffer = [System.Text.Encoding]::UTF8.GetBytes("Greška!"+$code)
$context.Response.ContentLength64 = $buffer.Length
$context.Response.OutputStream.Write($buffer, 0, $buffer.Length)
$context.Response.OutputStream.Close()
$listener.Stop()
exit 1
}
$buffer = [System.Text.Encoding]::UTF8.GetBytes("Sada možeš zatvoriti ovu karticu pretraživača.")
$context.Response.ContentLength64 = $buffer.Length
$context.Response.OutputStream.Write($buffer, 0, $buffer.Length)
$context.Response.OutputStream.Close()
$listener.Stop()
}
Return Invoke-RestMethod -Method Post -Uri "https://www.googleapis.com/oauth2/v4/token" -Body @{
code = $code
client_id = $client_id
client_secret = $client_secret
redirect_uri = 'http://localhost:'+$port
grant_type = 'authorization_code'
code_verifier = $codeverifier
}
$code = $null
Postavljamo Client ID i Client Secret, koje smo dobili u svojstvima identifikatora klijenta OAuth, i code verifier – to je niz dužine od 43 do 128 znakova, koji treba biti nasumično generiran iz ne rezerviranih znakova: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~".
Zatim će se ovaj kod ponovno proslijediti. Isključuje ranjivost, pri kojoj napadač može presresti odgovor koji se vraća preusmjeravanjem nakon autorizacije korisnika.
Možete poslati code verifier u trenutnom zahtjevu u otvorenom obliku (što ga čini besmislenim - ovo odgovara samo sustavima koji ne podržavaju SHA256), ili stvarajući hash prema SHA256 algoritmu, koji treba biti kodiran u BASE64Url (koji se razlikuje od Base64 sa dva simbola iz tabele) i ukloniti znak završetka linije: =.
Dalje, potrebno je početi slušati http na lokalnoj mašini kako bismo dobili odgovor nakon autorizacije, koji će se vratiti preusmjeravanjem.
Administrativne zadatke obavlja posebni server, ne možemo isključiti mogućnost da nekoliko administratora istovremeno pokrene skriptu, stoga će nasumično odabrati port za trenutnog korisnika, ali sam unaprijed odredio određene portove, jer ih je potrebno dodati kao pouzdane u API konzoli.
access_type=offline znači da aplikacija može samostalno ažurirati istekao token bez interakcije korisnika s preglednikom,
response_type=code određuje format na koji će se kod vratiti (upućivanje na stari način autorizacije, kada je korisnik kopirao kod iz preglednika u skriptu),
scope određuje oblasti i tipove pristupa. One treba da budu razdvojene razmacima ili (u skladu sa URL kodiranjem). Spisak oblasti pristupa sa tipovima možete videti ovde: .
Nakon što dobijemo kod autorizacije, aplikacija će vratiti poruku o zatvaranju u pregledniku, prestati slušati port i poslati POST zahtjev za dobijanje tokena. U njemu navodimo ranije zadane id i secret iz API konzole, adresu na koju će korisnik biti preusmjeren i grant_type prema specifikaciji protokola.
U odgovoru ćemo dobiti Access token, njegovo vrijeme trajanja u sekundama i Refresh token, uz pomoć kojeg možemo ažurirati Access token.
Aplikacija treba čuvati tokene na sigurnom mjestu s dugim rokom trajanja, stoga, dok ne opozovemo dobijeni pristup, aplikaciji neće biti vraćen refresh token. Na kraju sam dodao zahtjev za opoziv tokena, ako aplikacija nije uspješno završena i refresh token se nije vratio, ona će započeti proceduru ispočetka (smatrali smo nesigurnim čuvati tokene lokalno na terminalu, a ne želimo dodatno komplicirati kriptografijom ili često otvarati pregledač).
do {
$token_result = Get-GoogleAuthToken
$token = $token_result.access_token
if ($token_result.refresh_token -eq $null) {
Write-Host ("Sesija nije uništena. Oduzimanje tokena...")
Invoke-WebRequest -Uri ("https://accounts.google.com/o/oauth2/revoke?token="+$token)
}
} while ($token_result.refresh_token -eq $null)
$refresh_token = $token_result.refresh_token
$minute = ([int]("{0:mm}" -f ([timespan]::fromseconds($token_result.expires_in))))+((Get-date).Minute)-2
if ($minute -lt 0) {$minute += 60}
elseif ($minute -gt 59) {$minute -=60}
$token_expire = @{
hour = ([int]("{0:hh}" -f ([timespan]::fromseconds($token_result.expires_in))))+((Get-date).Hour)
minute = $minute
}
Kao što ste već primetili, za opoziv tokena koristi se Invoke-WebRequest. Za razliku od Invoke-RestMethod, on ne vraća stečene podatke u format koji je lak za korišćenje i prikazuje status zahteva.
Nakon toga, skripta će zatražiti unos imena i prezimena korisnika, generišući korisničko ime + email.
Upiti
Sledeće će biti upiti – prvo treba proveriti da li već postoji korisnik sa tim korisničkim imenom kako bi se donela odluka o formiranju novog ili uključivanju trenutnog.
Odlučio sam implementirati sve upite u formatu jedne funkcije sa izborom, koristeći switch:
function GoogleQuery {
param (
$type,
$query
)
switch ($type) {
"SearchAccount" {
Return Invoke-RestMethod -Method Get -Uri "https://www.googleapis.com/admin/directory/v1/users" -Headers @{Authorization = "Bearer " + (Get-GoogleToken)} -Body @{
domain = 'rocketguys.com'
query = "email:$query"
}
}
"UpdateAccount" {
$body = @{
name = @{
givenName = $query['givenName']
familyName = $query['familyName']
}
suspended = 'false'
password = $query['password']
changePasswordAtNextLogin = 'true'
phones = @(@{
primary = 'true'
value = $query['phone']
type = "mobile"
})
orgUnitPath = $query['orgunit']
}
Return Invoke-RestMethod -Method Put -Uri ("https://www.googleapis.com/admin/directory/v1/users/" + $query['email']) -Headers @{Authorization = "Bearer " + (Get-GoogleToken)} -Body (ConvertTo-Json $body) -ContentType 'application/json; charset=utf-8'
}
"CreateAccount" {
$body = @{
primaryEmail = $query['email']
name = @{
givenName = $query['givenName']
familyName = $query['familyName']
}
suspended = 'false'
password = $query['password']
changePasswordAtNextLogin = 'true'
phones = @(@{
primary = 'true'
value = $query['phone']
type = "mobile"
})
orgUnitPath = $query['orgunit']
}
Return Invoke-RestMethod -Method Post -Uri "https://www.googleapis.com/admin/directory/v1/users" -Headers @{Authorization = "Bearer " + (Get-GoogleToken)} -Body (ConvertTo-Json $body) -ContentType 'application/json; charset=utf-8'
}
"AddMember" {
$body = @{
userKey = $query['email']
}
$ifrequest = Invoke-RestMethod -Method Get -Uri "https://www.googleapis.com/admin/directory/v1/groups" -Headers @{Authorization = "Bearer " + (Get-GoogleToken)} -Body $body
$array = @()
foreach ($group in $ifrequest.groups) { $array += $group.email }
if ($array -notcontains $query['groupkey']) {
$body = @{
email = $query['email']
role = "MEMBER"
}
Return Invoke-RestMethod -Method Post -Uri ("https://www.googleapis.com/admin/directory/v1/groups/" + $query['groupkey'] + "/members") -Headers @{Authorization = "Bearer " + (Get-GoogleToken)} -Body (ConvertTo-Json $body) -ContentType 'application/json; charset=utf-8'
} else {
Return ($query['email'] + " now is a member of " + $query['groupkey'])
}
}
}
}U svakom zahtevu potrebno je poslati zaglavlje Authorization, koje sadrži tip tokena i sam Access token. Trenutno, tip tokena je uvek Bearer. Budući da treba proveriti da li je token istekao i ažurirati ga nakon jednog sata od izdavanja, naveo sam zahtev za drugu funkciju koja vraća Access token. Ovaj deo koda takođe postoji na početku skripta prilikom dobijanja prvog Access tokena:
function Get-GoogleToken {
if (((Get-date).Hour -gt $token_expire.hour) -or (((Get-date).Hour -ge $token_expire.hour) -and ((Get-date).Minute -gt $token_expire.minute))) {
Write-Host "Token je istekao. Osvježavam..."
$request = (Invoke-RestMethod -Method Post -Uri "https://www.googleapis.com/oauth2/v4/token" -ContentType 'application/x-www-form-urlencoded' -Body @{
client_id = $client_id
client_secret = $client_secret
refresh_token = $refresh_token
grant_type = 'refresh_token'
})
$token = $request.access_token
$minute = ([int]("{0:mm}" -f ([timespan]::fromseconds($request.expires_in))))+((Get-date).Minute)-2
if ($minute -lt 0) {$minute += 60}
elseif ($minute -gt 59) {$minute -=60}
$script:token_expire = @{
hour = ([int]("{0:hh}" -f ([timespan]::fromseconds($request.expires_in))))+((Get-date).Hour)
minute = $minute
}
}
return $token
}Provjera postojanja prijave:
function Check_Google {
$query = (GoogleQuery 'SearchAccount' $username)
if ($query.users -ne $null) {
$user = $query.users[0]
Write-Host $user.name.fullName' - '$user.PrimaryEmail' - suspendovan: '$user.Suspended
$GAresult = $user
}
if ($GAresult) {
$return = $GAresult
} else {$return = 'gg'}
return $return
}Zahtev za email: $query će tražiti API da potraži korisnika sa tim emailom, uključujući alias-e. Takođe se može koristiti wildcard: =, :, :{PREFIX}*.
Za dobijanje podataka koristi se GET metod, za umetanje podataka (kreiranje naloga ili dodavanje člana u grupu) - POST, za ažuriranje postojećih podataka - PUT, za brisanje zapisa (na primer, člana iz grupe) - DELETE.
Skripta će takođe pitati za broj telefona (nevalidirana string) i o uključivanju u regionalnu grupu za slanje. Određuje koja organizacijska jedinica treba da bude korisniku na osnovu odabrane OU Active Directory i smišlja lozinku:
do {
$phone = Read-Host "Telefon u formatu +7хххххххх"
} while (-not $phone)
do {
$moscow = Read-Host "U Moskovski ured? (y/n) "
} while (-not (($moscow -eq 'y') -or ($moscow -eq 'n')))
$orgunit = '\/'
if ($OU -like "*OU=Delivery,OU=Users,OU=ROOT,DC=rocket,DC=local") {
Write-host "Biće kreirano u \/Team delivery"
$orgunit = "\/Team delivery"
}
$Password = -join ( 48..57 + 65..90 + 97..122 | Get-Random -Count 12 | % {[char]$_})+"*Ba"
I dalje počinje manipulacije sa nalogom:
$query = @{
email = $email
givenName = $firstname
familyName = $lastname
password = $password
phone = $phone
orgunit = $orgunit
}
if ($GMailExist) {
Write-Host "Pokrećemo promenu naloga" -f mag
(GoogleQuery 'UpdateAccount' $query) | fl
write-host "Ne zaboravite da proverite grupe kod uključenog $Username u Google."
} else {
Write-Host "Pokrećemo kreiranje naloga" -f mag
(GoogleQuery 'CreateAccount' $query) | fl
}
if ($moscow -eq "y"){
write-host "Dodajemo u grupu moscowoffice"
$query = @{
groupkey = 'moscowoffice@rocketguys.com'
email = $email
}
(GoogleQuery 'AddMember' $query) | fl
}
Funkcije ažuriranja i kreiranja računa imaju sličnu sintaksu, nisu sva dodatna polja obavezna, a u odeljku za brojeve telefona potrebno je navesti niz koji može sadržavati od jedne stavke sa brojem i njegovim tipom.
Da ne bismo dobili grešku prilikom dodavanja korisnika u grupu, prethodno možemo proveriti da li je već član te grupe, dobijajući spisak članova grupe ili sastav samog korisnika.
Zahtev za sastav grupa određenog korisnika neće biti rekurzivan i biće prikazano samo neposredno članstvo. Uključivanje korisnika u roditeljsku grupu u kojoj se već nalazi podgrupa, čija je član korisnik, će biti uspešno.
Zaključak
Preostaje poslati korisniku lozinku za novi račun. To radimo preko SMS-a, dok se opšte informacije sa uputom i prijavom šalju na privatnu e-poštu koju je, zajedno sa brojem telefona, dostavio odeljak za zapošljavanje. Kao alternativna opcija, možemo uštedeti novac i poslati lozinku u tajnom Telegram chatu, što se takođe može smatrati drugim faktorom (izuzetak će biti MacBook-i).
Hvala što ste pročitali do kraja. Bio bih srećan da vidim predloge za poboljšanje stila pisanja članaka i želim vam da uhvatite što manje grešaka prilikom pisanja skripti =)
Lista linkova koji mogu biti tematski korisni ili jednostavno odgovoriti na postavljena pitanja:
Izvor: habr.com
