Создавање корисници на Google од PowerShell преку API

Здраво!

Оваа статија ќе ја опише имплементацијата на интеракцијата на PowerShell со Google API за манипулирање со корисниците на G Suite.

Ние користиме неколку внатрешни и облак услуги низ организацијата. Во најголем дел, овластувањето во нив се сведува на Google или Active Directory, меѓу кои не можеме да одржуваме реплика; соодветно, кога ќе замине нов вработен, треба да креирате/овозможите сметка во овие два системи. За да го автоматизираме процесот, решивме да напишеме скрипта што собира информации и ги испраќа до двете услуги.

Овластување

При изготвувањето на барањата, решивме да користиме вистински човечки администратори за овластување; ова ја поедноставува анализата на активностите во случај на случајни или намерни масивни промени.

Google API го користат протоколот OAuth 2.0 за автентикација и авторизација. Случаи за употреба и подетални описи може да се најдат овде: Користење на OAuth 2.0 за пристап до Google API.

Го избрав скриптата што се користи за авторизација во десктоп апликациите. Постои и опција за користење на сервисна сметка, која не бара непотребни движења од корисникот.

Сликата подолу е шематски опис на избраното сценарио од страницата на Google.

1. Прво, го испраќаме корисникот на страницата за автентикација на сметката на Google, наведувајќи ги параметрите GET:
   • ид на апликацијата
   • области до кои апликацијата има потреба од пристап
   • адресата на која ќе биде пренасочен корисникот по завршување на постапката
   • начинот на кој ќе го ажурираме токенот
   • Безбедносен код
   • формат на пренос на кодот за верификација

2. По завршувањето на овластувањето, корисникот ќе биде пренасочен на страницата наведена во првото барање, со грешка или код за овластување пренесен од параметрите GET
3. Апликацијата (скриптата) ќе треба да ги прими овие параметри и, ако ја добие шифрата, да го направи следното барање за да добие токени
4. Ако барањето е точно, Google API враќа:
   • Пристапен токен со кој можеме да поднесуваме барања
   • Периодот на важност на овој токен
   • Потребен е токен за освежување за да се освежи токенот за пристап.

Прво треба да отидете на конзолата на Google API: Ингеренциите - Google API конзола, изберете ја саканата апликација и во делот Ингеренции креирајте идентификатор за клиент OAuth. Таму (или подоцна, во својствата на креираниот идентификатор) треба да ги наведете адресите на кои е дозволено пренасочување. Во нашиот случај, ова ќе бидат неколку записи за локални домаќини со различни порти (види подолу).

За да го направите поудобно да го читате алгоритмот за скрипта, можете да ги прикажете првите чекори во посебна функција што ќе го врати пристапот и ќе ги освежи токените за апликацијата:

$client_secret = 'Our Client Secret'
$client_id = 'Our Client ID'
function Get-GoogleAuthToken {
  if (-not [System.Net.HttpListener]::IsSupported) {
    "HttpListener is not supported."
    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 "Start browser..."
  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 {
    "Unable to start listener."
    exit 1
  }
  while (($code -eq $null)) {
    $context = $listener.GetContext()
    Write-Host "Connection accepted" -f 'mag'
    $url = $context.Request.RawUrl
    $code = $url.split('?')[1].split('=')[1].split('&')[0]
    if ($url.split('?')[1].split('=')[0] -eq 'error') {
      Write-Host "Error!"$code -f 'red'
      $buffer = [System.Text.Encoding]::UTF8.GetBytes("Error!"+$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("Now you can close this browser tab.")
    $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

Ги поставивме ИД на клиентот и Тајната на клиентот добиени во својствата на идентификаторот на клиентот OAuth, а проверувачот на кодот е низа од 43 до 128 знаци што мора случајно да се генерираат од нерезервирани знаци: [AZ] / [az] / [0-9 ] / "-" / "." / "_" / "~".

Овој код потоа повторно ќе се пренесе. Ја елиминира ранливоста во која напаѓачот може да пресретне одговор вратен како пренасочување по овластувањето на корисникот.
Можете да испратите проверувач на код во тековното барање во јасен текст (што го прави бесмислено - ова е погодно само за системи кои не поддржуваат SHA256) или со создавање хаш со помош на алгоритам SHA256, кој мора да биде кодиран во BASE64Url (различно од Base64 со два знака од табелата) и отстранување на завршетоците на линиските линии: =.

Следно, треба да почнеме да слушаме http на локалната машина за да добиеме одговор по овластувањето, кој ќе биде вратен како пренасочување.

Административните задачи се извршуваат на посебен сервер, не можеме да ја исклучиме можноста неколку администратори да ја извршуваат скриптата во исто време, така што случајно ќе избере порта за тековниот корисник, но јас наведов предефинирани порти бидејќи тие исто така мора да се додадат како доверливи во конзолата API.

пристап_тип=офлајн значи дека апликацијата може сама да ажурира истечен токен без корисничка интеракција со прелистувачот,
одговор_тип=шифра го поставува форматот како ќе се врати кодот (упатување на стариот метод за авторизација, кога корисникот го копирал кодот од прелистувачот во скриптата),
опсегот го означува обемот и видот на пристапот. Тие мора да бидат одделени со празни места или %20 (според кодирањето на URL-то). Списокот на области за пристап со типови може да се види овде: Опсегот на OAuth 2.0 за API на Google.

По добивањето на кодот за авторизација, апликацијата ќе врати блиска порака до прелистувачот, ќе престане да слуша на портата и ќе испрати барање POST за да го добие токенот. Во него го означуваме претходно наведениот ID и тајната од API на конзолата, адресата на која ќе биде пренасочен корисникот и grant_type во согласност со спецификацијата на протоколот.

Како одговор, ќе добиеме токен за пристап, неговиот период на важност во секунди и токен за освежување, со кој можеме да го ажурираме токенот за пристап.

Апликацијата мора да складира токени на безбедно место со долг рок на траење, така што додека не го отповикаме добиениот пристап, апликацијата нема да го врати токенот за освежување. На крајот, додадов барање за отповикување на токенот; ако апликацијата не беше успешно завршена и токенот за освежување не беше вратен, повторно ќе ја започне постапката (сметавме дека е небезбедно да се складираат токени локално на терминалот и не не сакам да ги комплицирам работите со криптографијата или често да го отворам прелистувачот).

do {
  $token_result = Get-GoogleAuthToken
  $token = $token_result.access_token
  if ($token_result.refresh_token -eq $null) {
    Write-Host ("Session is not destroyed. Revoking 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
}

Како што веќе забележавте, при отповикување на токен, се користи Invoke-WebRequest. За разлика од Invoke-RestMethod, тој не ги враќа примените податоци во употреблив формат и го прикажува статусот на барањето.

Следно, скриптата бара од вас да ги внесете името и презимето на корисникот, генерирајќи најава + е-пошта.

Барања

Следните барања ќе бидат - пред сè, треба да проверите дали веќе постои корисник со иста најава за да се добие одлука за создавање на нов или овозможување на тековниот.

Решив да ги имплементирам сите барања во формат на една функција со избор, користејќи прекинувач:

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

Во секое барање, треба да испратите заглавие за авторизација што го содржи типот на токен и самиот токен за пристап. Во моментов, типот на токен е секогаш носител. Бидејќи треба да провериме дали токенот не е истечен и да го ажурираме по еден час од моментот на издавање, наведов барање за друга функција што враќа токен за Access. Истиот дел од кодот е на почетокот на скриптата при примањето на првиот токен за пристап:

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 Expired. Refreshing..."
    $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
}

Проверка на најавата за постоење:

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

Барањето email:$query ќе побара од API да бара корисник со токму таа е-пошта, вклучувајќи псевдоними. Може да користите и џокер: =, :, :{ПРЕФИКС}*.

За да добиете податоци, користете го методот на барање GET, за вметнување податоци (создавање сметка или додавање член во група) - ПОСТАВЕТЕ, за ажурирање постоечки податоци - PUT, за бришење запис (на пример, член од група) - ИЗБРИШИ.

Скриптата исто така ќе бара телефонски број (непотврдена низа) и вклучување во регионална дистрибутивна група. Тој одлучува која организациска единица корисникот треба да ја има врз основа на избраниот OU на Active Directory и доаѓа со лозинка:

do {
  $phone = Read-Host "Телефон в формате +7хххххххх"
} while (-not $phone)
do {
    $moscow = Read-Host "В Московский офис? (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 "Будет создана в /Team delivery"
    $orgunit = "/Team delivery"
}
$Password =  -join ( 48..57 + 65..90 + 97..122 | Get-Random -Count 12 | % {[char]$_})+"*Ba"

И тогаш тој почнува да манипулира со сметката:

$query = @{
  email = $email
  givenName = $firstname
  familyName = $lastname
  password = $password
  phone = $phone
  orgunit = $orgunit
}
if ($GMailExist) {
  Write-Host "Запускаем изменение аккаунта" -f mag
  (GoogleQuery 'UpdateAccount' $query) | fl
  write-host "Не забудь проверить группы у включенного $Username в Google."
} else {
  Write-Host "Запускаем создание аккаунта" -f mag
  (GoogleQuery 'CreateAccount' $query) | fl
}
if ($moscow -eq "y"){
  write-host "Добавляем в группу moscowoffice"
  $query = @{
    groupkey = '[email protected]'
    email = $email
  }
  (GoogleQuery 'AddMember' $query) | fl
}

Функциите за ажурирање и креирање сметка имаат слична синтакса; не се потребни сите дополнителни полиња; во делот со телефонски броеви, треба да наведете низа што може да содржи до еден запис со бројот и неговиот тип.

За да не добиеме грешка при додавање на корисник во група, прво можеме да провериме дали тој е веќе член на оваа група со добивање листа на членови на групата или состав од самиот корисник.

Прашањето за членството во групата на одреден корисник нема да биде рекурзивно и ќе прикажува само директно членство. Ќе успее да вклучите корисник во родителска група која веќе има детска група во која корисникот е член.

Заклучок

Останува само да му ја испрати на корисникот лозинката за новата сметка. Ова го правиме преку СМС и испраќаме општи информации со инструкции и најавување на лична е-пошта, која заедно со телефонскиот број е обезбедена од одделот за регрутирање. Како алтернатива, можете да заштедите пари и да ја испратите вашата лозинка на таен телеграмски разговор, што исто така може да се смета за втор фактор (MacBooks ќе биде исклучок).

Ви благодариме што прочитавте до крај. Ќе ми биде драго да видам предлози за подобрување на стилот на пишување написи и ви посакувам да фатите помалку грешки при пишување скрипти =)

Список на врски што може да бидат тематски корисни или едноставно да одговорат на прашања:

• OAuth 2.0 за мобилни и десктоп апликации
• Користење на OAuth 2.0 за апликации за веб-сервер
• Доказен клуч за размена на код од јавни клиенти на OAuth
• Генерирајте случајни букви со PowerShell
• Табела и опис на ASCII
• PowerShell: Добивање хаш вредност за низа
• Кодирај/Декодирај Base64Url
• Кодирање Base64 наспроти кодирање Base64url
• Invoke-RestMethod во PowerShell 5.1
• Не се добива токен за освежување иако access_type е офлајн во чекор 1
• За споредбените оператори
• Директориум API: кориснички сметки
• Пребарајте корисници
• Директориум API: Групи
• Ракување со грешки за Invoke-RestMethod - Powershell

Извор: www.habr.com