🥇Google kasutajate loomine PowerShelli kaudu API abil

Tere!

Selles artiklis käsitletakse PowerShelli ja Google API koostööd G Suite'i kasutajate haldamiseks.

Meie organisatsioonis kasutame mitmeid sisemisi ja pilveteenuseid. Suurel määral kõikide teenuste autoriseerimine toimub Google'i või Active Directory kaudu, mille vahel me ei saa replikatsiooni toetada, seega tuleb uue töötaja puhul luua/aktiveerida konto nendes kahes süsteemis. Protsessi automatiseerimiseks otsustasime kirjutada skripti, mis kogub teavet ja saadab selle mõlemasse teenusesse.

Autoriseerimine

Nõudeid koostades otsustasime kasutada autoriseerimiseks tegelikke administraatoreid, et lihtsustada juhtumite analüüsimist juhuslike või tahtlike massiliste muutuste korral.

Google API kasutab autentimiseks ja autoriseerimiseks protokolli OAuth 2.0. Kasutusskeeme ja üksikasjalikku kirjeldust saab vaadata siin: Using OAuth 2.0 to Access Google APIs.

Valisin stsenaariumi, mida kasutatakse lauaarvuti rakendustesse autoriseerimisel. Samuti on võimalus kasutada teenusekontot, mis ei nõua kasutajalt täiendavaid toiminguid.

Allolev joonis on valitud stsenaariumi visand lehelt Google.

Esmalt suuname kasutaja Google'i konto autentimise lehele, määrates GET parameetrid:
- rakenduse identifikaator
- valdkonnad, millele rakendus vajab ligipääsu
- aadress, kuhu kasutaja suunatakse pärast protseduuri lõpetamist
- meetod, millega me värskendame tokenit
- kontrollikood
- kontrollikoodi edastamise formaat
Pärast autoriseerimise lõpetamist suunatakse kasutaja tagasi esimeses päringus määratud lehele, koos vea või autoriseerimiskoodiga, edastatuna GET parameetrites.
Rakendusel (skriptil) tuleb need parameetrid kätte saada ja, kui kood on saadud, teha järgmine päring tokenite saamiseks.
Korrektselt esitatud päringu korral tagastab Google API:
- Access token, millega me saame päringuid esitada
- Selle tokeni kehtivusaeg
- Refresh token, mis on vajalik Access tokeni uuendamiseks.

Esmalt tuleb minna Google API konsooli: Credentials — Google API Console, vali sobiv rakendus ja sektsioonis Credentials loo OAuth kliendi ID. Seal (või hiljem, loodud ID omadustes) tuleb näidata aadresse, kuhu suunamine on lubatud. Meie puhul on need mitu localhost'i kirjet erinevate portidega (vt edasi).

Selleks, et skripti algoritmi oleks mugavam lugeda, saab esimesed sammud eraldi funktsiooni välja tuua, mis tagastab juurdepääsu- ja värskenduse tokenid rakenduse jaoks:

$client_secret = 'Meie Klientide Salasõna'
$client_id = 'Meie Klientide ID'
function Get-GoogleAuthToken {
  if (-not [System.Net.HttpListener]::IsSupported) {
    "HttpListener ei ole toetatud."
    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 "Käivitame brauseri..."
  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 {
    "Klistenerit ei õnnestu käivitada."
    exit 1
  }
  while (($code -eq $null)) {
    $context = $listener.GetContext()
    Write-Host "Ühendus aktsepteeritud" -f 'mag'
    $url = $context.Request.RawUrl
    $code = $url.split('?')[1].split('=')[1].split('&')[0]
    if ($url.split('?')[1].split('=')[0] -eq 'error') {
      Write-Host "Viga!"$code -f 'red'
      $buffer = [System.Text.Encoding]::UTF8.GetBytes("Viga!"+$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("Nüüd võid selle brauseri vahelehe sulgeda.")
    $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

Me seadistame Client ID ja Client Secret, mis on saadud OAuth kliendi ID omadustes, ja code verifier – see on 43 kuni 128 sümboli pikkune string, mis tuleb genereerida juhuslikult mittereserveeritud sümbolitest: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~".

Edasi antakse see kood uuesti. See välistab haavatavuse, kus pahatahtlik inimene võib vastuse, mis tagastati pärast kasutaja autentimist, ummistada.
Saada koodivahendi praegusesse päringusse võib saata avatud kujul (mis muudab selle mõttetuks - see sobib ainult süsteemidele, mis ei toeta SHA256) või luua SHA256 algoritmiga hash, mis tuleb kodeerida BASE64Url (erineb Base64 kahe sümboli poolest) ja eemaldada reavahetusmärk: =.

Seejärel peame alustama http kuulamist lokaalses masinas, et saada vastus autoriseerimise järel, mis naaseb ümbersuunamisega.

Haldusülesanded toimuvad spetsiaalsel serveril, me ei saa välistada tõenäosust, et mitu administraatorit käivitab skripti samaaegselt, seetõttu valib see juhuslikult porti praeguse kasutaja jaoks, kuid ma määrasin ette antud pordid, kuna need tuleb samuti lisada usaldusväärseteks API konsoolis.

access_type=offline tähendab, et rakendus võib iseseisvalt uuendada aegunud tokeni ilma, et kasutaja peaks brauseriga suhtlema.
response_type=code määrab formaadi, kuidas kood naaseb (viide vanale autoriseerimise meetodile, kus kasutaja kopeeris koodi brauserist skripti),
scope näitab alasid ja juurdepääsu tüüpe. Need peavad olema eraldatud tühikute või (vastavalt URL-kodeeringule). Juurdepääsu alade ja tüüpide loetelu saab näha siit: OAuth 2.0 ulatused Google'i API-de jaoks.

Pärast autoriseerimise koodi saamist saadab rakendus brauserisse sulgemisettepaneku, lõpetab pordi kuulamise ja saadab POST-päringu tokeni saamiseks. Me määrame selles antud id ja secret API konsoolist, aadress, kuhu kasutaja suunatakse ja grant_type vastavalt protokolli spetsifikatsioonile.

Vastuseks saame Access tokeni, selle kehtivuse aja sekundites ja Refresh tokeni, millega saame Access tokeni uuendada.

Rakendus peab hoidma tokeneid turvalises kohas pikaajalise säilitamisega, seega, kuni me ei tühista saadud juurdepääsu, ei tagastata rakendusele refresh tokenit. Lõpuks lisasin päringu tokeni tühistamiseks, kui rakendus ei olnud edukas ja refresh tokenit ei tagastatud, alustab see protseduuri uuesti (me pidasime ebaturvaliseks hoida tokeneid kohalikult terminalis ning ei soovi keerulisemaks muuta krüptograafiaga või tihti brauserit avada).

do {
  $token_result = Get-GoogleAuthToken
  $token = $token_result.access_token
  if ($token_result.refresh_token -eq $null) {
    Write-Host ("Seanss ei ole hävitatud. Tühistatakse token...")
    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
}

Nagu olete juba märganud, kasutatakse tokeni tühistamiseks Invoke-WebRequest'i. Erinevalt Invoke-RestMethod'ist ei naita see saadud andmeid mugavas vormingus ning näitab päringu staatust.

Seejärel palub skript sisestada kasutaja ees- ja perekonnanime, genereerides sisenemisnime + e-posti.

Päringud

Järgmised toimingud on päringud – kõigepealt tuleb kontrollida, kas kasutajaga, kellel on selline sisenemisnimi, on juba olemas, et teha otsus uue loomise või olemasoleva aktiveerimise üle.

Otsustasin kõik päringud ellu viia ühe funktsiooni formaadis, kasutades switch'i:

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'])
      }
    }
  }
}

Iga taotluses tuleb saata Authorization päis, mis sisaldab tokeni tüüpi ja ise Access tokenit. Praegu on tokeni tüüp alati Bearer. Kuna meile on vajalik kontrollida, et token pole aegunud ja värskendada seda tunni jooksul pärast väljaandmist, olen määranud päringu teise funktsioonile, mis tagastab Access tokeni. See sama koodijupp on skripti alguses, kui saadakse esimene Access token:

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 on aegunud. Uuendamine..."
    $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
}

Kontrolli kasutajanime olemasolu:

function Check_Google {
  $query = (GoogleQuery 'SearchAccount' $username)
  if ($query.users -ne $null) {
    $user = $query.users[0]
    Write-Host $user.name.fullName' - '$user.PrimaryEmail' - peatatud: '$user.Suspended
    $GAresult = $user
  }
  if ($GAresult) {
      $return = $GAresult
  } else {$return = 'gg'}
  return $return
}

Küsi email: $query palub API-l otsida kasutajat just sellise emailiga, sealhulgas leidub ka alias'e. Samuti võid kasutada wildcard'i: =, :, :{PREFIX}*.

Andmete saamiseks kasutatakse meetodit GET, andmete sisestamiseks (konto loomine või grupi liikme lisamine) – POST, olemasolevate andmete uuendamiseks – PUT, kirje kustutamiseks (näiteks grupist liikme eemaldamiseks) – DELETE.

Kood küsib ka telefoninumbrit (valideerimata string) ja kas liituda regionaalse postitusgrupiga. See otsustab, milline organisatsiooniline üksus kasutajal olema peaks vastavalt valitud OU Active Directory-s ja loob parooli:

do {
  $phone = Read-Host "Telefon vormingus +7хххххххх"
} while (-not $phone)
do {
    $moscow = Read-Host "Moskva kontorisse? (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 "Luua aadressile /Team delivery"
    $orgunit = "/Team delivery"
}
$Password =  -join ( 48..57 + 65..90 + 97..122 | Get-Random -Count 12 | % {[char]$_})+"*Ba"

Ja siis alustab see konto manipuleerimist:

$query = @{
  email = $email
  givenName = $firstname
  familyName = $lastname
  password = $password
  phone = $phone
  orgunit = $orgunit
}
if ($GMailExist) {
  Write-Host "Käivitame konto muutmise" -f mag
  (GoogleQuery 'UpdateAccount' $query) | fl
  write-host "Ära unusta kontrollida gruppe, kuhu '$Username' Google'is kuulub."
} else {
  Write-Host "Käivitame konto loomise" -f mag
  (GoogleQuery 'CreateAccount' $query) | fl
}
if ($moscow -eq "y"){
  write-host "Lisame moscowoffice gruppi"
  $query = @{
    groupkey = 'moscowoffice@rocketguys.com'
    email = $email
  }
  (GoogleQuery 'AddMember' $query) | fl
}

Konto loomise ja uuendamise funktsioonidel on sarnane süntaks, mitte kõik täiendavad väljad ei ole kohustuslikud, telefoninumbrite jaotises tuleb esitada massiiv, mis võib sisaldada vähemalt ühte kirjet koos numbri ja selle tüübiga.

Kuna võib esineda viga kasutaja lisamisel rühma, saame eelnevalt kontrollida, kas ta kuulub juba sellesse rühma, saades rühmaliikmete nimekirja või muud kasutaja andmed.

Teatud kasutaja rühmade koosseisu päring ei ole rekursiivne ja näitab ainult vahetut kuuluvust. Kasutaja lisamine ülemrühma, milles juba eksisteerib alamrühm, mille liige ta on, õnnestub.

Kokkuvõte

Jäänud on saata kasutajale uus konto parool. Teeme seda SMS-iga ning üldise teabe koos juhiste ja sisselogimisega saadame isiklikule e-postile, mille andis personaliosakond koos telefoninumeroga. Alternatiivina saame raha säästa ja saata parooli salajasesse Telegrami vestlusesse, mis võib samuti arvestada teise tegurina (välja arvatud MacBookid).

Aitäh, et lugesite lõpuni. Olen avatud ettepanekutele artiklite kirjutamisstiili parandamiseks ja soovin, et te teeks, et teie skriptide kirjutamises vähem vigu =)

Nimekiri lingitud, mis võivad olla temaatiliselt kasulikud või lihtsalt vastata tekkinud küsimustele: