🥇Création d'utilisateurs Google à partir de PowerShell via l'API

Bonjour !

Cet article décrira l'implémentation de l'interaction entre PowerShell et l'API Google pour manipuler des utilisateurs de G Suite.

Dans notre organisation, nous utilisons plusieurs services internes et cloud. La plupart du temps, l'authentification se réduit à Google ou Active Directory, entre lesquels nous ne pouvons pas maintenir de réplica ; par conséquent, lors de l'arrivée d'un nouvel employé, il faut créer/activer un compte dans ces deux systèmes. Pour automatiser ce processus, nous avons décidé d'écrire un script qui collecte des informations et les envoie aux deux services.

Autorisation

En établissant les exigences, nous avons décidé d'utiliser de vraies personnes administrateurs pour l'authentification, ce qui simplifie l'analyse des actions lors de modifications massives accidentelles ou intentionnelles.

Pour l'authentification et l'autorisation, l'API Google utilise le protocole OAuth 2.0. Les scénarios d'utilisation et une description plus détaillée peuvent être consultés ici : Utiliser OAuth 2.0 pour accéder aux API Google.

J'ai choisi le scénario utilisé lors de l'authentification dans les applications de bureau. Il existe également une option pour utiliser un compte de service, qui ne nécessite pas d'efforts supplémentaires de la part de l'utilisateur.

L'image ci-dessous est une représentation schématique du scénario choisi à partir de la page Google.

Tout d'abord, nous redirigeons l'utilisateur vers la page d'authentification de son compte Google, en spécifiant les paramètres GET :
- l'identifiant de l'application
- les domaines auxquels l'application nécessite l'accès
- l'adresse vers laquelle l'utilisateur sera redirigé après avoir terminé la procédure
- la méthode par laquelle nous mettrons à jour le token
- le code de vérification
- le format de transmission du code de vérification
Après l'achèvement de l'authentification, l'utilisateur sera redirigé vers la page indiquée dans la première demande, avec une erreur ou un code d'autorisation transmis dans les paramètres GET.
L'application (script) devra récupérer ces paramètres et, en cas de réception du code, effectuer la demande suivante pour obtenir des tokens.
Pour une demande correcte, l'API Google renvoie :
- Un token d'accès, avec lequel nous pouvons effectuer des requêtes.
- La durée de validité de ce token.
- Un token de rafraîchissement, nécessaire pour renouveler le token d'accès.

Tout d'abord, il faut se rendre dans la console Google API : Identifiants — Console Google API, choisissez l'application souhaitée et dans la section Credentials, créez un identifiant OAuth client. Vous devez également indiquer les adresses vers lesquelles la redirection est autorisée (cela peut être fait plus tard dans les propriétés de l'identifiant créé). Dans notre cas, cela comprendra plusieurs enregistrements localhost avec différents ports (voir ci-dessous).

Pour faciliter la lecture de l'algorithme du script, il est possible de placer les premières étapes dans une fonction distincte qui renverra les tokens d'accès et de rafraîchissement pour l'application :

$client_secret = 'Notre Client Secret'
$client_id = 'Notre Client ID'
function Get-GoogleAuthToken {
  if (-not [System.Net.HttpListener]::IsSupported) {
    "HttpListener n'est pas supporté."
    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 "Démarrer le navigateur..."
  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 {
    "Impossible de démarrer l'écouteur."
    exit 1
  }
  while (($code -eq $null)) {
    $context = $listener.GetContext()
    Write-Host "Connexion acceptée" -f 'mag'
    $url = $context.Request.RawUrl
    $code = $url.split('?')[1].split('=')[1].split('&')[0]
    if ($url.split('?')[1].split('=')[0] -eq 'error') {
      Write-Host "Erreur!"$code -f 'red'
      $buffer = [System.Text.Encoding]::UTF8.GetBytes("Erreur!"+$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("Vous pouvez maintenant fermer cet onglet de navigateur.")
    $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

Nous définissons le Client ID et le Client Secret, obtenus dans les propriétés de l'identifiant client OAuth, et le code de vérification qui est une chaîne de 43 à 128 caractères, générée aléatoirement à partir de caractères non réservés : [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~".

Ce code sera ensuite renvoyé. Il élimine la vulnérabilité par laquelle un attaquant pourrait intercepter la réponse retournée par redirection après l'autorisation de l'utilisateur.
Il est possible d'envoyer le code de vérification dans la requête actuelle en clair (ce qui le rend inutile – cela ne convient que pour les systèmes qui ne prennent pas en charge SHA256) ou en créant un hachage selon l'algorithme SHA256, qui doit être encodé en BASE64Url (différent de Base64 par deux symboles) et en supprimant le caractère de fin de ligne : =.

Nous devons ensuite commencer à écouter http sur la machine locale pour recevoir la réponse après authentification, qui sera renvoyée par redirection.

Les tâches administratives sont effectuées sur un serveur spécial, nous ne pouvons pas exclure la possibilité que plusieurs administrateurs exécutent le script simultanément, il choisira donc par défaut un port pour l'utilisateur actuel, mais j'ai spécifié des ports prédéfinis, car ils doivent également être ajoutés comme approuvés dans la console API.

access_type=offline signifie que l'application peut actualiser un token expiré de manière autonome sans interaction de l'utilisateur avec le navigateur,
response_type=code indique le format de retour du code (référence à l'ancien mode d'authentification où l'utilisateur copié-collait le code du navigateur dans le script),
scope indique les zones et le type d'accès. Ils doivent être séparés par des espaces ou (conformément à l'encodage URL). La liste des zones d'accès avec les types peut être vue ici : OAuth 2.0 Scopes for Google APIs.

Après avoir obtenu le code d'autorisation, l'application renverra au navigateur un message de fermeture, arrêtera d'écouter le port et enverra une requête POST pour obtenir un token. Nous y spécifions les id et secret précédemment définis de la console API, l'adresse vers laquelle l'utilisateur sera redirigé et grant_type conformément à la spécification du protocole.

En réponse, nous recevrons un token d'accès, sa durée de vie en secondes et un token de rafraîchissement, à l'aide duquel nous pouvons actualiser le token d'accès.

L'application doit stocker les tokens dans un endroit sûr avec une longue durée de stockage, donc tant que nous n'avons pas révoqué l'accès obtenu, l'application ne recevra pas de token de rafraîchissement. À la fin, j'ai ajouté une requête pour révoquer le token, si l'application a été arrêtée de manière non réussie et que le token de rafraîchissement n'est pas revenu, elle recommencera la procédure (nous avons considéré qu'il était dangereux de stocker les tokens localement sur le terminal, et compliqué de recourir à la cryptographie ou d'ouvrir fréquemment le navigateur).

do {
  $token_result = Get-GoogleAuthToken
  $token = $token_result.access_token
  if ($token_result.refresh_token -eq $null) {
    Write-Host ("La session n'est pas détruite. Révocation du 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
}

Comme vous l'avez déjà remarqué, la révocation du token utilise Invoke-WebRequest. Contrairement à Invoke-RestMethod, il ne renvoie pas les données obtenues dans un format facile à utiliser et montre le statut de la demande.

Ensuite, le script demandera le prénom et le nom de l'utilisateur, générant un identifiant + email.

Requêtes

Les prochaines étapes consisteront à effectuer des requêtes – il est d'abord nécessaire de vérifier si un utilisateur avec cet identifiant existe déjà pour décider de créer un nouveau compte ou d'utiliser l'actuel.

J'ai décidé de réaliser toutes les requêtes sous la forme d'une seule fonction avec une sélection, en utilisant switch:

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

Chaque requête doit inclure un en-tête Authorization, contenant le type de jeton et le jeton d'accès lui-même. Actuellement, le type de jeton est toujours Bearer. Étant donné que nous devons vérifier que le jeton n'est pas expiré et le renouveler après une heure depuis sa délivrance, j'ai indiqué une requête vers une autre fonction, qui renvoie le jeton d'accès. Ce même code se trouve au début du script lors de la récupération du premier jeton d'accès :

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 Expiré. Rénouvellement..."
    $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
}

Vérification de l'existence de l'identifiant :

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

La requête email : $query demandera à l'API de rechercher un utilisateur avec cet email, y compris les alias. Vous pouvez également utiliser un wildcard : =, :, :{PREFIX}*.

Pour récupérer des données, la méthode de requête GET est utilisée ; pour insérer des données (créer un compte ou ajouter un membre à un groupe) – POST ; pour mettre à jour des données existantes – PUT ; pour supprimer un enregistrement (par exemple, un membre d'un groupe) – DELETE.

Le script demandera également un numéro de téléphone (chaîne non validée) et s'il faut être inclus dans le groupe régional de diffusion. Il détermine quelle unité organisationnelle doit être attribuée à l'utilisateur en fonction de l'OU Active Directory sélectionnée et générera un mot de passe :

do {
  $phone = Read-Host "Téléphone au format +7xxxxxxxx"
} while (-not $phone)
do {
    $moscow = Read-Host "Dans le bureau de Moscou ? (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 "Sera créé dans /Team delivery"
    $orgunit = " /Team delivery"
}
$Password =  -join ( 48..57 + 65..90 + 97..122 | Get-Random -Count 12 | % {[char]$_})+"*Ba"

Et ensuite commence les manipulations avec le compte :

$query = @{
  email = $email
  givenName = $firstname
  familyName = $lastname
  password = $password
  phone = $phone
  orgunit = $orgunit
}
if ($GMailExist) {
  Write-Host "Lancement de la modification du compte" -f mag
  (GoogleQuery 'UpdateAccount' $query) | fl
  write-host "N'oubliez pas de vérifier les groupes pour $Username dans Google."
} else {
  Write-Host "Lancement de la création du compte" -f mag
  (GoogleQuery 'CreateAccount' $query) | fl
}
if ($moscow -eq "y"){
  write-host "Ajout au groupe moscowoffice"
  $query = @{
    groupkey = 'moscowoffice@rocketguys.com'
    email = $email
  }
  (GoogleQuery 'AddMember' $query) | fl
}

Les fonctionnalités de mise à jour et de création de compte ont une syntaxe similaire, toutes les informations supplémentaires ne sont pas obligatoires. Dans la section des numéros de téléphone, il faut indiquer un tableau pouvant contenir une ou plusieurs entrées avec le numéro et son type.

Pour éviter une erreur lors de l'ajout d'un utilisateur à un groupe, nous pouvons d'abord vérifier s'il est déjà membre de ce groupe en obtenant la liste des membres du groupe ou la composition de l'utilisateur.

La demande de composition des groupes d'un utilisateur donné ne sera pas récursive et affichera uniquement l'appartenance directe. Inclure un utilisateur dans un groupe parent auquel appartient déjà un groupe enfant dont il fait partie sera un succès.

Conclusion

Il ne reste plus qu'à envoyer à l'utilisateur le mot de passe de son nouveau compte. Nous le faisons par SMS, et nous envoyons les informations générales avec le login à l'adresse email personnelle fournie, ainsi que le numéro de téléphone, par le service de recrutement. En option, pour économiser un peu, nous pouvons envoyer le mot de passe dans un chat secret Telegram, ce qui peut également être considéré comme un deuxième facteur (les MacBooks constitueront une exception).

Merci d'avoir lu jusqu'à la fin. Je serais ravi de recevoir des suggestions pour améliorer le style des articles et je vous souhaite de rencontrer moins d'erreurs lors de la rédaction de scripts =)

Voici une liste de liens qui peuvent être thématiquement utiles ou simplement répondre à certaines questions :

Source : habr.com