יצירת משתמשי Google מ-PowerShell באמצעות API

היי!

מאמר זה יתאר את היישום של אינטראקציה של PowerShell עם Google API כדי לתמרן משתמשי G Suite.

אנו משתמשים במספר שירותי פנים וענן ברחבי הארגון. לרוב, ההרשאה בהם מסתכמת בגוגל או ב-Active Directory, שביניהם לא נוכל לשמור עותק; בהתאם, כאשר עובד חדש עוזב, עליך ליצור/לאפשר חשבון בשתי המערכות הללו. כדי להפוך את התהליך לאוטומטי, החלטנו לכתוב סקריפט שאוסף מידע ושולח אותו לשני השירותים.

הרשאה

בעת עריכת הדרישות, החלטנו להשתמש במנהלים אנושיים אמיתיים לצורך הרשאה; הדבר מפשט את ניתוח הפעולות במקרה של שינויים מסיביים מקריים או מכוונים.

ממשקי API של Google משתמשים בפרוטוקול OAuth 2.0 לצורך אימות והרשאה. מקרי שימוש ותיאורים מפורטים יותר ניתן למצוא כאן: שימוש ב- OAuth 2.0 לגישה לממשקי API של Google.

בחרתי בסקריפט המשמש להרשאה ביישומי שולחן עבודה. ישנה גם אפשרות להשתמש בחשבון שירות, שאינו דורש מהמשתמש תנועות מיותרות.

התמונה למטה היא תיאור סכמטי של התרחיש שנבחר מדף Google.

1. ראשית, אנו שולחים את המשתמש לדף האימות של חשבון Google, תוך ציון פרמטרי GET:
   • מזהה אפליקציה
   • אזורים שהאפליקציה צריכה גישה אליהם
   • הכתובת שאליה יופנה המשתמש לאחר השלמת ההליך
   • הדרך שבה נעדכן את האסימון
   • קוד אבטחה
   • פורמט שידור קוד אימות

2. לאחר השלמת ההרשאה, המשתמש יופנה לדף שצוין בבקשה הראשונה, עם שגיאה או קוד הרשאה שיועבר על ידי פרמטרי GET
3. האפליקציה (סקריפט) תצטרך לקבל את הפרמטרים הללו, ואם יקבל את הקוד, תבקש את הבקשה הבאה לקבלת אסימונים
4. אם הבקשה נכונה, ה-API של Google מחזיר:
   • אסימון גישה שבאמצעותו נוכל להגיש בקשות
   • תקופת התוקף של אסימון זה
   • נדרש רענון אסימון כדי לרענן את אסימון הגישה.

ראשית עליך לעבור למסוף Google API: אישורים - Google API Console, בחר את היישום הרצוי ובקטע אישורים צור מזהה OAuth לקוח. שם (או מאוחר יותר, במאפייני המזהה שנוצר) עליך לציין את הכתובות שאליהן מותר להפנות מחדש. במקרה שלנו, אלו יהיו מספר כניסות של localhost עם יציאות שונות (ראה להלן).

כדי שיהיה נוח יותר לקרוא את אלגוריתם הסקריפט, ניתן להציג את השלבים הראשונים בפונקציה נפרדת שתחזיר את Access ותרענן אסימונים עבור האפליקציה:

$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), או על ידי יצירת hash באמצעות אלגוריתם SHA256, אותו יש לקודד ב-BASE64Url (שונה מ-Base64 על ידי שני תווי טבלה) והסרת סיומות שורת התווים: =.

לאחר מכן, עלינו להתחיל להאזין ל-http במחשב המקומי על מנת לקבל תגובה לאחר הרשאה, שתוחזר כהפניה מחדש.

משימות ניהול מבוצעות על שרת מיוחד, לא נוכל לשלול את האפשרות שמספר מנהלי מערכת יפעילו את הסקריפט בו זמנית, אז זה יבחר אקראית פורט למשתמש הנוכחי, אבל ציינתי פורטים מוגדרים מראש בגלל יש להוסיף אותם גם כאמין במסוף ה-API.

access_type=לא מקוון פירושו שהאפליקציה יכולה לעדכן אסימון שפג תוקפו בעצמו ללא אינטראקציה של המשתמש עם הדפדפן,
response_type=קוד מגדיר את הפורמט של האופן שבו הקוד יוחזר (הפניה לשיטת ההרשאה הישנה, ​​כאשר המשתמש העתיק את הקוד מהדפדפן לסקריפט),
היקף מציין את היקף וסוג הגישה. יש להפריד ביניהם ברווחים או %20 (על פי קידוד כתובת האתר). רשימה של אזורי גישה עם סוגים ניתן לראות כאן: היקפי OAuth 2.0 עבור ממשקי API של Google.

לאחר קבלת קוד ההרשאה, האפליקציה תחזיר הודעה סגורה לדפדפן, תפסיק להאזין בפורט ותשלח בקשת POST לקבלת האסימון. אנו מציינים בו את המזהה והסוד שצוינו קודם לכן מ-API של המסוף, הכתובת אליה יופנה המשתמש ו-grant_type בהתאם למפרט הפרוטוקול.

בתגובה נקבל אסימון Access, תקופת תוקפו בשניות ו-Refresh token שבאמצעותו נוכל לעדכן את אסימון הגישה.

על האפליקציה לאחסן טוקנים במקום מאובטח עם חיי מדף ארוכים, ולכן עד שנבטל את הגישה שהתקבלה, האפליקציה לא תחזיר את אסימון הרענון. בסוף, הוספתי בקשה לביטול האסימון; אם הבקשה לא הושלמה בהצלחה ואסימון הרענון לא הוחזר, הוא יתחיל את ההליך מחדש (חשבנו שזה לא בטוח לאחסן טוקנים מקומית בטרמינל, ואנחנו עושים זאת. לא רוצה לסבך דברים עם קריפטוגרפיה או לפתוח את הדפדפן לעתים קרובות).

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
}

בקשת האימייל:$query תבקש מה-API לחפש משתמש עם האימייל הזה בדיוק, כולל כינויים. אתה יכול גם להשתמש בתו כללי: =, :, :{PREFIX}*.

כדי לקבל נתונים, השתמשו בשיטת בקשת 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
}

לפונקציות לעדכון ויצירת חשבון יש תחביר דומה; לא כל השדות הנוספים נדרשים; בחלק עם מספרי טלפון יש לציין מערך שיכול להכיל עד רשומה אחת עם המספר וסוגו.

על מנת לא לקבל שגיאה בעת הוספת משתמש לקבוצה, נוכל לבדוק תחילה האם הוא כבר חבר בקבוצה זו על ידי קבלת רשימת חברי קבוצה או הרכב מהמשתמש עצמו.

שאילתת החברות בקבוצה של משתמש ספציפי לא תהיה רקורסיבית ותציג רק חברות ישירה. הכללת משתמש בקבוצת אב שכבר יש לה קבוצת ילד שהמשתמש חבר בה תצליח.

מסקנה

כל שנותר הוא לשלוח למשתמש את הסיסמה לחשבון החדש. אנו עושים זאת באמצעות SMS, ושולחים מידע כללי עם הנחיות וכניסה למייל אישי, אשר יחד עם מספר טלפון נמסר ממחלקת הגיוס. כחלופה, אתה יכול לחסוך כסף ולשלוח את הסיסמה שלך לצ'אט טלגרם סודי, שיכול להיחשב גם לגורם השני (מקבוקים יהיו חריגים).

תודה שקראת עד הסוף. אשמח לראות הצעות לשיפור סגנון כתיבת מאמרים ומאחלת לך לתפוס פחות שגיאות בכתיבת סקריפטים =)

רשימת קישורים שעשויים להיות שימושיים מבחינה נושאית או פשוט לענות על שאלות:

• OAuth 2.0 לאפליקציות לנייד ולשולחן העבודה
• שימוש ב-OAuth 2.0 עבור יישומי שרת אינטרנט
• מפתח הוכחה להחלפת קודים על ידי לקוחות ציבוריים של OAuth
• צור אותיות אקראיות עם PowerShell
• טבלה ותיאור של ASCII
• PowerShell: קבלת ערך ה-hash עבור מחרוזת
• קידוד/פענוח Base64Url
• קידוד Base64 לעומת קידוד Base64url
• Invoke-RestMethod ב-PowerShell 5.1
• לא מקבל אסימון רענון למרות ש-access_type לא מקוון בשלב 1
• אודות מפעילי השוואה
• Directory API: חשבונות משתמשים
• חפש משתמשים
• API של ספריות: קבוצות
• טיפול בשגיאות עבור Invoke-RestMethod - Powershell

מקור: www.habr.com