PowerShell から API 経由で Google ユーザーを作成する

Привет！

この記事では、G Suite ユーザーを操作するための、PowerShell と Google API の対話の実装について説明します。

私たちは組織全体でいくつかの内部サービスとクラウド サービスを使用しています。 ほとんどの場合、それらの認証は Google または Active Directory によって行われますが、これらの間ではレプリカを維持できないため、新しい従業員が退職する場合は、これら XNUMX つのシステムでアカウントを作成/有効にする必要があります。 プロセスを自動化するために、情報を収集して両方のサービスに送信するスクリプトを作成することにしました。

承認

要件を作成する際、承認には実際の人間の管理者を使用することにしました。これにより、偶発的または意図的な大規模な変更が発生した場合のアクションの分析が簡素化されます。

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 とクライアント シークレットを設定します。コード ベリファイアは、予約されていない文字からランダムに生成する必要がある 43 ～ 128 文字の文字列です: [AZ] / [az] / [0-9 ] /「-」/「。」 /「_」/「~」。

このコードは再度送信されます。 これにより、ユーザーの承認後にリダイレクトとして返される応答が攻撃者によって傍受される可能性がある脆弱性が排除されます。
現在のリクエストのコードベリファイアをクリアテキストで送信することもできます (これでは意味がありません。これは SHA256 をサポートしていないシステムにのみ適しています)。または、SHA256 アルゴリズムを使用してハッシュを作成し、BASE64Url でエンコードする必要があります (異なるものになります)。 Base64 から XNUMX つのテーブル文字分)、行末文字 = を削除します。

次に、承認後にリダイレクトとして返される応答を受信するために、ローカル マシンで http のリッスンを開始する必要があります。

管理タスクは特別なサーバーで実行され、複数の管理者が同時にスクリプトを実行する可能性を排除できないため、現在のユーザーのポートがランダムに選択されますが、事前定義されたポートを指定しました。 API コンソールでも信頼できるものとして追加する必要があります。

access_type=オフライン これは、ユーザーがブラウザーを操作しなくても、アプリケーションが有効期限切れのトークンを独自に更新できることを意味します。
response_type = code コードがどのように返されるかの形式を設定します (ユーザーがブラウザからスクリプトにコードをコピーしたときの古い認証メソッドへの参照)。
スコープ アクセスの範囲と種類を示します。 これらはスペースまたは %20 (URL エンコーディングに従って) で区切る必要があります。 アクセス領域とタイプのリストは、次のとおりです。 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 とは異なり、受信したデータを使用可能な形式で返しず、リクエストのステータスを表示します。

次に、スクリプトはユーザーの姓名を入力するように求め、ログインと電子メールを生成します。

リクエスト

次のリクエストは次のとおりです。まず、新しいログインを作成するか現在のログインを有効にするかを決定するために、同じログインを持つユーザーがすでに存在するかどうかを確認する必要があります。

スイッチを使用して、すべてのリクエストを選択付きの XNUMX つの関数の形式で実装することにしました。

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 です。 なぜならトークンの有効期限が切れていないことを確認し、トークンが発行されてから XNUMX 時間後に更新する必要があるため、アクセス トークンを返す別の関数のリクエストを指定しました。 最初のアクセス トークンを受信するときに、同じコード部分がスクリプトの先頭にあります。

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 経由で行われ、手順とログインに関する一般情報が、電話番号とともに採用部門から提供された個人メールに送信されます。 代わりに、お金を節約して秘密の電報チャットにパスワードを送信することもできます。これも XNUMX 番目の要素と見なされます (MacBook は例外です)。

最後まで読んでいただきありがとうございます。 記事の書き方を改善するための提案を喜んで拝見させていただきます。また、スクリプトを書くときに見つかるエラーが少なくなることを願っています =)

テーマ別に役立つリンク、または単に質問に回答するリンクのリスト:

• モバイルおよびデスクトップ アプリ向けの OAuth 2.0
• Web サーバー アプリケーションでの 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