Креирање Гоогле корисника из ПоверСхелл-а преко АПИ-ја

Здраво!

Овај чланак ће описати имплементацију ПоверСхелл интеракције са Гоогле АПИ-јем за манипулацију Г Суите корисницима.

Користимо неколико интерних услуга и услуга у облаку широм организације. Углавном се ауторизација у њима своди на Гоогле или Ацтиве Дирецтори, између којих не можемо одржавати реплику, сходно томе, када нови запослени оде, потребно је да креирате/омогућите налог у ова два система. Да бисмо аутоматизовали процес, одлучили смо да напишемо скрипту која прикупља информације и шаље их обема услугама.

Овлашћење

Приликом састављања захтева одлучили смо да користимо праве људске администраторе за ауторизацију, што поједностављује анализу поступања у случају случајних или намерних масовних промена.

Гоогле АПИ-ји користе ОАутх 2.0 протокол за аутентификацију и ауторизацију. Случајеви коришћења и детаљнији описи могу се наћи овде: Коришћење ОАутх 2.0 за приступ Гоогле АПИ-јима.

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

Слика испод је шематски опис одабраног сценарија са Гоогле странице.

1. Прво шаљемо корисника на страницу за потврду аутентичности Гоогле налога, наводећи ГЕТ параметре:
   • ИД апликације
   • области којима апликација треба приступ
   • адресу на коју ће корисник бити преусмерен након завршеног поступка
   • начин на који ћемо ажурирати токен
   • Сигурносни код
   • формат преноса верификационог кода

2. Након што је ауторизација завршена, корисник ће бити преусмерен на страницу наведену у првом захтеву, са грешком или кодом за ауторизацију који су прослеђивали ГЕТ параметри
3. Апликација (скрипта) ће морати да прими ове параметре и, ако добије код, упути следећи захтев за добијање токена
4. Ако је захтев тачан, Гоогле АПИ враћа:
   • Приступни токен са којим можемо да постављамо захтеве
   • Период важења овог токена
   • За освежавање токена за приступ потребан је освежавајући токен.

Прво морате да одете на Гоогле АПИ конзолу: Акредитиви – Гоогле АПИ конзола, изаберите жељену апликацију и у одељку Акредитиви креирајте клијентски ОАутх идентификатор. Тамо (или касније, у својствима креираног идентификатора) морате да наведете адресе на које је преусмеравање дозвољено. У нашем случају, то ће бити неколико уноса локалног хоста са различитим портовима (погледајте доле).

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

$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

Поставили смо Цлиент ИД и Цлиент Сецрет добијене у својствима идентификатора ОАутх клијента, а верификатор кода је низ од 43 до 128 знакова који мора бити насумично генерисан од нерезервисаних знакова: [АЗ] / [аз] / [0-9 ] / "-" / "." / "_" / "~".

Овај код ће се затим поново пренети. Он елиминише рањивост у којој би нападач могао да пресретне одговор враћен као преусмеравање након ауторизације корисника.
Можете да пошаљете верификатор кода у тренутном захтеву у чистом тексту (што га чини бесмисленим – ово је погодно само за системе који не подржавају СХА256) или креирањем хеш користећи СХА256 алгоритам, који мора бити кодиран у БАСЕ64Урл (разликује се из Басе64 са два знака табеле) и уклањањем завршетака редова знакова: =.

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

Административни задаци се обављају на посебном серверу, не можемо искључити могућност да неколико администратора истовремено покреће скрипту, па ће насумично бирати порт за тренутног корисника, али сам навео унапред дефинисане портове јер они такође морају бити додати као поуздани у АПИ конзоли.

аццесс_типе=оффлине значи да апликација може сама да ажурира токен који је истекао без интеракције корисника са прегледачем,
респонсе_типе=цоде поставља формат како ће код бити враћен (референца на стари метод ауторизације, када је корисник копирао код из претраживача у скрипту),
обим означава обим и врсту приступа. Морају бити раздвојени размацима или %20 (према УРЛ кодирању). Списак приступних подручја са типовима можете видети овде: ОАутх 2.0 Опсези за Гоогле АПИ-је.

Након што прими ауторизациони код, апликација ће вратити претраживачу поруку о затварању, престати да слуша порт и послати ПОСТ захтев за добијање токена. У њему наводимо претходно наведени ид и тајну из АПИ-ја конзоле, адресу на коју ће корисник бити преусмерен и грант_типе у складу са спецификацијом протокола.

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

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

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
}

Као што сте већ приметили, приликом опозива токена, користи се Инвоке-ВебРекуест. За разлику од Инвоке-РестМетход, он не враћа примљене податке у употребљивом формату и приказује статус захтева.

Затим, скрипта од вас тражи да унесете име и презиме корисника, генеришући пријаву + адресу е-поште.

zahtevi

Следећи захтеви ће бити – пре свега, потребно је да проверите да ли корисник са истим логом већ постоји да бисте добили одлуку о креирању новог или омогућавању постојећег.

Одлучио сам да имплементирам све захтеве у формату једне функције са избором, користећи прекидач:

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

У сваком захтеву, потребно је да пошаљете заглавље ауторизације које садржи тип токена и сам токен за приступ. Тренутно је тип токена увек носилац. Јер морамо да проверимо да токен није истекао и да га ажурирамо након сат времена од тренутка када је издат, навео сам захтев за другу функцију која враћа Аццесс токен. Исти део кода је на почетку скрипте када се прими први токен за приступ:

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
}

Захтев емаил:$куери ће тражити од АПИ-ја да потражи корисника са управо том е-поштом, укључујући псеудониме. Такође можете користити џокер знак: =, :, :{ПРЕФИКС}*.

За добијање података користите метод ГЕТ захтева, за убацивање података (креирање налога или додавање члана у групу) - ПОСТ, за ажурирање постојећих података - ПУТ, за брисање записа (на пример, члана из групе) - ИЗБРИШИ.

Скрипта ће такође тражити број телефона (непотврђен стринг) и укључивање у регионалну групу за дистрибуцију. Одлучује коју организациону јединицу корисник треба да има на основу изабраног Ацтиве Дирецтори ОУ и доноси лозинку:

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
}

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

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

Постављање упита о чланству у групи одређеног корисника неће бити рекурзивно и показаће само директно чланство. Укључивање корисника у родитељску групу која већ има подређену групу чији је корисник члан ће успети.

Закључак

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

Хвала вам што сте прочитали до краја. Биће ми драго да видим предлоге за побољшање стила писања чланака и желим вам да ухватите мање грешака при писању скрипти =)

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

• ОАутх 2.0 за мобилне и десктоп апликације
• Коришћење ОАутх 2.0 за апликације веб сервера
• Кључ доказа за размену кодова од стране ОАутх јавних клијената
• Генеришите насумична слова помоћу ПоверСхелл-а
• АСЦИИ табела и опис
• ПоверСхелл: Добијање хеш вредности за стринг
• Енцоде/Децоде Басе64Урл
• Басе64 кодирање наспрам Басе64урл кодирање
• Инвоке-РестМетход у ПоверСхелл-у 5.1
• Не добијам токен за освежавање иако је аццесс_типе офлајн у кораку 1
• О операторима поређења
• АПИ директоријума: кориснички налози
• Тражите кориснике
• АПИ директоријума: групе
• Руковање грешкама за Инвоке-РестМетход – Поверсхелл

Извор: ввв.хабр.цом