API를 통해 PowerShell에서 Google 사용자 만들기

Привет!

이 문서에서는 G Suite 사용자를 조작하기 위해 Google API와 PowerShell 상호 작용을 구현하는 방법을 설명합니다.

우리는 조직 전체에서 여러 내부 및 클라우드 서비스를 사용합니다. 대부분의 경우 승인은 Google 또는 Active Directory로 귀속되며 그 사이에는 복제본을 유지할 수 없으므로 신규 직원이 퇴사할 경우 이 두 시스템에서 계정을 생성/활성화해야 합니다. 프로세스를 자동화하기 위해 우리는 정보를 수집하여 두 서비스 모두에 보내는 스크립트를 작성하기로 결정했습니다.

권한 부여

요구 사항을 작성할 때 실제 인간 관리자를 사용하여 승인을 하기로 결정했습니다. 이는 우발적이거나 의도적인 대규모 변경이 발생할 경우 조치 분석을 단순화합니다.

Google API는 인증 및 승인을 위해 OAuth 2.0 프로토콜을 사용합니다. 사용 사례와 자세한 설명은 여기에서 확인할 수 있습니다. OAuth 2.0을 사용하여 Google API에 액세스.

데스크톱 애플리케이션에서 인증에 사용되는 스크립트를 선택했습니다. 사용자의 불필요한 이동이 필요하지 않은 서비스 계정을 사용하는 옵션도 있습니다.

아래 그림은 Google 페이지에서 선택한 시나리오에 대한 개략적인 설명입니다.

1. 먼저 GET 매개변수를 지정하여 사용자를 Google 계정 인증 페이지로 보냅니다.
   • 애플리케이션 ID
   • 애플리케이션이 액세스해야 하는 영역
   • 절차 완료 후 사용자가 리디렉션될 주소
   • 토큰을 업데이트하는 방법
   • 보안 코드
   • 인증번호 전송 형식

2. 인증이 완료된 후 사용자는 GET 매개변수에 의해 전달된 오류 또는 인증 코드와 함께 첫 번째 요청에 지정된 페이지로 리디렉션됩니다.
3. 애플리케이션(스크립트)은 이러한 매개변수를 수신해야 하며, 코드를 수신한 경우 토큰을 얻기 위해 다음 요청을 수행해야 합니다.
4. 요청이 정확하면 Google API는 다음을 반환합니다.
   • 요청을 할 수 있는 액세스 토큰
   • 이 토큰의 유효 기간
   • 액세스 토큰을 새로 고치려면 새로 고침 토큰이 필요합니다.

먼저 Google API 콘솔로 이동해야 합니다. 자격 증명 - Google API 콘솔에서 원하는 애플리케이션을 선택하고 자격 증명 섹션에서 클라이언트 OAuth 식별자를 만듭니다. 여기(또는 나중에 생성된 식별자의 속성)에서 리디렉션이 허용되는 주소를 지정해야 합니다. 우리의 경우에는 서로 다른 포트를 가진 여러 localhost 항목이 있습니다(아래 참조).

스크립트 알고리즘을 더 쉽게 읽을 수 있도록 애플리케이션에 대한 액세스 및 새로 고침 토큰을 반환하는 별도의 함수에 첫 번째 단계를 표시할 수 있습니다.

$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 클라이언트 식별자 속성에서 얻은 클라이언트 ID와 클라이언트 비밀을 설정하고, 코드 검증자는 예약되지 않은 문자([AZ] / [az] / [43-128 ])에서 무작위로 생성되어야 하는 0~9자의 문자열입니다. / "-" / "." / "_" / "~".

그러면 이 코드가 다시 전송됩니다. 이는 공격자가 사용자 인증 후 리디렉션으로 반환된 응답을 가로챌 수 있는 취약성을 제거합니다.
현재 요청의 코드 검증기를 일반 텍스트(의미 없음 - SHA256을 지원하지 않는 시스템에만 적합함)로 보내거나 BASE256Url로 인코딩해야 하는 SHA64 알고리즘을 사용하여 해시를 생성하여 보낼 수 있습니다(다름) Base64에서 두 개의 테이블 문자로) 및 문자 줄 끝을 제거합니다: =.

다음으로, 인증 후 응답을 수신하기 위해 로컬 시스템에서 http 수신을 시작해야 하며, 이는 리디렉션으로 반환됩니다.

관리 작업은 특수 서버에서 수행되므로 여러 관리자가 동시에 스크립트를 실행할 가능성을 배제할 수 없으므로 현재 사용자에 대한 포트를 무작위로 선택하지만 미리 정의된 포트를 지정했습니다. 또한 API 콘솔에서 신뢰할 수 있는 것으로 추가해야 합니다.

access_type=오프라인 이는 사용자가 브라우저와 상호 작용하지 않고도 애플리케이션이 만료된 토큰을 자체적으로 업데이트할 수 있음을 의미합니다.
응답 유형=코드 코드가 반환되는 방식의 형식을 설정합니다(사용자가 브라우저에서 스크립트로 코드를 복사할 때 이전 인증 방법에 대한 참조).
범위 액세스 범위와 유형을 나타냅니다. URL 인코딩에 따라 공백이나 %20으로 구분해야 합니다. 유형이 포함된 액세스 영역 목록은 여기에서 볼 수 있습니다. Google API용 OAuth 2.0 범위.

인증 코드를 받은 후 애플리케이션은 브라우저에 닫기 메시지를 반환하고 포트 수신 대기를 중지한 후 토큰을 얻기 위해 POST 요청을 보냅니다. 여기에는 콘솔 API에서 이전에 지정한 ID와 비밀, 프로토콜 사양에 따라 사용자가 리디렉션될 주소 및 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'])
      }
    }
  }
}

각 요청에서 토큰 유형과 액세스 토큰 자체가 포함된 Authorization 헤더를 보내야 합니다. 현재 토큰 유형은 항상 Bearer입니다. 왜냐하면 토큰이 만료되지 않았는지 확인하고 발급된 지 한 시간 후에 업데이트해야 합니다. 저는 액세스 토큰을 반환하는 다른 함수에 대한 요청을 지정했습니다. 첫 번째 액세스 토큰을 받을 때 스크립트 시작 부분에 동일한 코드 조각이 있습니다.

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 요청 메소드를 사용하여 데이터를 삽입하십시오(계정 생성 또는 그룹에 구성원 추가) - POST, 기존 데이터 업데이트 - PUT, 레코드 삭제(예: 그룹의 구성원) - 삭제.

또한 스크립트는 전화번호(검증되지 않은 문자열)와 지역 배포 그룹에 포함을 요청합니다. 선택한 Active Directory OU를 기반으로 사용자가 보유해야 하는 조직 단위를 결정하고 비밀번호를 제공합니다.

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
}

계정을 업데이트하고 생성하는 함수는 구문이 비슷합니다. 모든 추가 필드가 필요한 것은 아닙니다. 전화번호가 있는 섹션에서는 번호와 해당 유형이 포함된 레코드를 최대 XNUMX개까지 포함할 수 있는 배열을 지정해야 합니다.

사용자를 그룹에 추가할 때 오류가 발생하지 않도록 하려면 먼저 사용자로부터 그룹 구성원 목록이나 구성 목록을 얻어서 해당 사용자가 이미 이 그룹의 구성원인지 여부를 확인할 수 있습니다.

특정 사용자의 그룹 멤버십을 쿼리하면 재귀적이지 않으며 직접 멤버십만 표시됩니다. 사용자가 구성원으로 속한 하위 그룹이 이미 있는 상위 그룹에 사용자를 포함하면 성공합니다.

결론

남은 것은 사용자에게 새 계정의 비밀번호를 보내는 것뿐입니다. 우리는 SMS를 통해 이를 수행하고 채용 부서에서 제공한 전화번호와 함께 개인 이메일에 대한 지침 및 로그인과 함께 일반 정보를 보냅니다. 대안으로, 비용을 절약하고 비밀 전보 채팅에 비밀번호를 보낼 수 있습니다. 이는 두 번째 요소로 간주될 수도 있습니다(MacBook은 예외임).

끝까지 읽어주셔서 감사합니다. 기사 작성 스타일을 개선하기 위한 제안을 보게 되어 기쁘고 스크립트를 작성할 때 오류가 줄어들기를 바랍니다 =)

주제별로 유용하거나 단순히 질문에 답변할 수 있는 링크 목록:

• 모바일 및 데스크톱 앱용 OAuth 2.0
• 웹 서버 애플리케이션에 OAuth 2.0 사용
• OAuth 공개 클라이언트에 의한 코드 교환을 위한 증명 키
• PowerShell을 사용하여 임의의 문자 생성
• ASCII 테이블 및 설명
• PowerShell: 문자열의 해시 값 가져오기
• Base64Url 인코딩/디코딩
• Base64 인코딩과 Base64url 인코딩 비교
• PowerShell 5.1의 Invoke-RestMethod
• 1단계에서 access_type이 오프라인인데도 새로 고침 토큰을 받지 못함
• 비교 연산자 정보
• 디렉터리 API: 사용자 계정
• 사용자 검색
• 디렉토리 API: 그룹
• Invoke-RestMethod에 대한 오류 처리 - Powershell

출처 : habr.com