Google'i kasutajate loomine PowerShelli kaudu API abil

Tere!

Selles artiklis käsitletakse PowerShelli ja Google API vaheline integreerimist G Suite'i kasutajate haldamiseks.

Organisatsioonis kasutame mitmeid sisemisi ja pilves teenuseid. Enamasti piirdub autoriseerimine Google'i või Active Directoryga, mille vahel ei saa me sünkroonimist tagada. Seega tuleb uue töötaja puhul luua/aktiveerida konto mõlemas süsteemis. Protsessi automatiseerimiseks otsustasime kirjutada skripti, mis kogub vajalikku teavet ja saadab selle mõlemasse teenusesse.

Autoriseerimine

Nõudeid koostades otsustasime kasutada autoriseerimiseks reaalseid administraatoreid, mis lihtsustab tegevuste tõlgendamist juhuslike või tahtlike massiliste muutuste korral.

Google API autentimiseks ja autoriseerimiseks kasutatakse OAuth 2.0 protokolli. Kasutusskenaarid ja detailne kirjeldus on saadaval siin: Using OAuth 2.0 to Access Google APIs.

Valisin skripti, mida kasutatakse desktop-rakendustes autoriseerimise jaoks. Samuti on olemas teenusekonto kasutamise võimalus, mis ei nõua kasutajalt täiendavaid samme.

Allpool on joon allpool – see on valitud stsenaariumi skeem Google'i lehelt.

1. Esialgu suuname kasutaja Google'i konto autentimislehele, edastades GET parameetrites:
   • rakenduse identifikaator
   • tegevusvaldkonnad, millele rakendus vajab ligipääsu
   • aadress, kuhu kasutaja suunatakse pärast protseduuri lõppu
   • meetod, millega me uuendame tokenit
   • kontrollikood
   • kontrollikoodi edastamise formaat

2. Pärast autentimise lõpetamist suunatakse kasutaja tagasi esimeses päringus näidatud lehele, koos veateate või autoriseerimisoodisega, mis edastatakse GET parameetrites.
3. Rakendusel (skriptil) on vaja need parameetrid hankida ja, kui kood on saadud, teha järgmine päring tokenite hankimiseks.
4. Korraliku päringu korral tagastab Google API:
   • Access token, millega saame teha päringuid
   • Selle tokeni kehtivusaeg
   • Refresh token, mis on vajalik Access tokeni uuendamiseks.

Esmalt tuleb käia Google API konsoolis: Credentials — Google API Console, valige vajalik rakendus ja jaotises Credentials looge OAuth kliendi identifikaator. Seal (või hiljem, loodud identifikaatori omadustes) tuleb märkida aadressid, kuhu suunamine on lubatud. Meie puhul on need mitu localhost'i sissekannet erinevate portidega (vt allpool).

Kuna skripti algoritmi on mugavam lugeda, saab esimesed sammud välja tuua eraldi funktsiooni, mis tagastab rakenduse Access ja refresh tokenid:

$client_secret = 'Meie kliendi salajane kood'
$client_id = 'Meie kliendi 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 "Avatud brauser..."
  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 {
    "Listeneri käivitamine ei õnnestunud."
    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 saate selle brauseri vahekaardi 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 identifikaatori omadustes, ja code verifier – see on 43 kuni 128 märki pikk string, mis peab olema juhuslikult genereeritud, kasutades reservatsioonivabu märke: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~".

Seejärel saadetakse see kood uuesti. See välistab haavatavuse, kus kurjategija võib pealt kuulata vastuse, mis naaseb ümber suunamise kaudu pärast kasutaja autoriseerimist.
Saada code verifier praeguses päringus võib avatud kujul (mis muudab selle mõttetuks – see sobib ainult süsteemidele, mis ei toeta SHA256), või luues räsingu SHA256 algoritmi kaudu, mis tuleb kodeerida BASE64Url (erineb Base64-st kahe tabelisümboli poolest) ja eemaldada realõpu märk: =.

Seejärel peame alustama http kuulamist lokaatorkonfiguratsioonis, et saada vastus pärast autoriseerimist, mis naaseb ümber suunamise kaudu.

Halduse ülesandeid täidetakse spetsiaalsel serveril, seetõttu ei saa me välistada tõenäosust, et mitu administraatorit käivitavad skripti samal ajal, mistõttu valitakse sadam praeguse kasutaja jaoks juhuslikult. Olen eelnevalt määranud kindlad sadamad, kuna need tuleb ka usaldatud nimekirja lisada API konsoolis.

access_type=offline tähendab, et rakendus saab aegunud tokenit automaatselt värskendada ilma kasutaja sekkumiseta brauserisse.
response_type=code määrab formaadi, kuidas kood tagasi antakse (viidates vana 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 -ga (vastavalt URL kodeerimisele). Juhtimise alasid ja tüüpe saab vaadata siit: OAuth 2.0 Scopes for Google APIs.

Pärast autoriseerimiskoodi saamist tagastab rakendus brauseris sulgem sõnumi, lõpetab sadama kuulamise ja saadab POST-i päringu tokeni saamiseks. Me määrame selles eelnevalt määratud ID ja salajase võtme API konsoolist, aadressi, kuhu kasutaja suunatakse, ja grant_type vastavalt protokolli spetsifikatsioonile.

Vastusena saame Access-tokeni, selle kehtivuse aja sekundites ja Refresh-tokeni, mille abil saame Access-tokeni uuendada.

Rakendus peab hoidma tokeneid turvalises kohas pikaajalise säilitamisega. Seetõttu ei returnita rakendusele refresh-tokenit, kuni me saadud juurdepääsu tagasi ei võta. Lõpus lisasin tokeni tühistamise päringu, kui rakendus lõpetatakse ebaõnnestunult ja refresh-tokenit ei tagastata, algab see protseduur uuesti (peame ebaohutuks hoida tokeneid kohalikus terminalis, ning ei soovi krüptograafiaga keeruliseks muuta või pidevalt brauserit avada).

do {
  $token_result = Get-GoogleAuthToken
  $token = $token_result.access_token
  if ($token_result.refresh_token -eq $null) {
    Write-Host ("Sessioon ei ole hävitatud. Tühistan tokeni...")
    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 juba märkisite, kasutatakse tokeni tühistamisel Invoke-WebRequesti. Erinevalt Invoke-RestMethodist ei tagasta see andmeid kasutamiseks mugavas formaadis ning näitab päringu staatust.

Küsimiseks palub skript sisestada kasutaja ees- ja perekonnanimi, genereerides sisselogimise + e-posti.

Päringud

Järgmised küsimused – esmajärjekorras tuleb kontrollida, kas sellise sisselogimisega kasutaja juba eksisteerib, et teha otsus uue loomise või praeguse aktiveerimise osas.

Otsustasin kõik päringud rakendada ühe funktsiooni formaadis, kasutades valikustruktuuri (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'])
      }
    }
  }
}

Igas päringus tuleb saata Authorization päis, mis sisaldab tokeni tüüpi ja ise Access tokenit. Hetkel on tokeni tüüp alati Bearer. Kuna peame kontrollima, et token ei ole aegunud ja uuendama seda tunni jooksul alates väljastamisest, viisin ma sisse päringu teise funktsiooni, mis tagastab Access tokeni. Sama koodijupp on ka 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
}

Logi olemasolu kontroll:

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
}

Emaili päring: $query palub API-l otsida kasutajat selle e-posti aadressiga, sealhulgas leidub ka alias. Samuti on võimalik kasutada wildcard'i: =, :, :{PREFIX}*.

Andmete saamiseks kasutatakse GET päringut, andmete lisamiseks (kasutajakonto loomine või grupi liikme lisamine) - POST, olemasolevate andmete uuendamiseks - PUT, kirje kustutamiseks (näiteks grupi liikme eemaldamiseks) - DELETE.

Skript küsib ka telefoninumbrit (kehtetu string) ja kas liituda piirkondliku jaotuse gruppiga. See otsustab, milline organisatsiooniline üksus peaks kasutajal olema, tuginedes valitud OU Active Directoryle, ja genereerib 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 "Loo ma: /Team delivery"
    $orgunit = "/Team delivery"
}
$Password =  -join (48..57 + 65..90 + 97..122 | Get-Random -Count 12 | % {[char]$_}) + "*Ba"

Ja seejärel alustab konto manipuleerimist:

$query = @{
  email = $email
  givenName = $firstname
  familyName = $lastname
  password = $password
  phone = $phone
  orgunit = $orgunit
}
if ($GMailExist) {
  Write-Host "Konto muutmine on käimas" -f mag
  (GoogleQuery 'UpdateAccount' $query) | fl
  write-host "Ära unusta kontrollida gruppide olekut Google'is kasutaja $Username jaoks."
} else {
  Write-Host "Konto loomine on käimas" -f mag
  (GoogleQuery 'CreateAccount' $query) | fl
}
if ($moscow -eq "y"){
  write-host "Lisame Moskva kontori gruppi"
  $query = @{
    groupkey = 'moscowoffice@rocketguys.com'
    email = $email
  }
  (GoogleQuery 'AddMember' $query) | fl
}

Konto uuendamise ja loomise funktsioonidel on sarnane süntaks, mitte kõik täiendavad väljad ei ole kohustuslikud; telefoninumbri osas tuleb näidata massiivi, mis võib sisaldada vähemalt ühte numbrit koos selle tüübiga.

Kasutaja grupi lisamisel vea vältimiseks saame eelnevalt kontrollida, kas ta juba kuulub sellesse gruppi, saades kas grupi liikmete nimekirja või kasutaja endi koosseisu.

Teatud kasutaja grupi koosseisu pärimine ei ole rekursiivne ja näitab vaid vahetut kuuluvust. Kasutaja lisamine vanemgruppi, kuhu juba kuulub alamgrupp, mille liige kasutaja on, õnnestub.

Kokkuvõte

Kasutajale jääb saata uut kontot puudutav salasõna. Teeme seda SMS-iga, samas saadame üldise teabe juhiste ja sisselogimisega isiklikule meilile, mille koos telefoninumbriga esitas personalivaliku osakond. Alternatiivina saab raha säästa ja saata salasõna Telegrami salajasesse vestlusesse, mida võib samuti pidada teiseks teguriks (välja arvatud MacBook'id).

Aitäh, et lugesite lõpuni. Olen huvitatud teie ettepanekutest artiklite kirjutamisstiili parandamiseks ja soovin, et te kirjutamisel vähem vigu teeks.

Siin on loetelu linkidest, mis võivad olla temaatiliselt kasulikud või lihtsalt vastata tekkivatele küsimustele:

• OAuth 2.0 mobiil- ja lauaarvutirakendustele
• OAuth 2.0 kasutamine veebi serveri rakendustes
• Proof Key for Code Exchange OAuth avalike klientide jaoks
• Juhuslike tähtede genereerimine PowerShelliga
• ASCII tabel ja kirjeldus
• PowerShell: stringi hash-väärtuse saamine
• Base64Url kodeerimine/dekodeerimine
• Base64 kodeerimine vs Base64url kodeerimine
• Invoke-RestMethod PowerShell 5.1-s
• Ei saa värskendusketast, kuigi access_type on offline 1. sammus
• Võrdlusoperaatorite kohta
• Directory API: Kasutajakontod
• Kasutajate otsimine
• Directory API: Grupid
• Viga käsitlemine Invoke-RestMethodis — Powershell

Allikas: habr.com