Explorer et utiliser l'API Graph pour AzureAD
Microsoft GraphAPI est un outil puissant à avoir. Non seulement pouvons-nous l'utiliser pour créer des outils pour automatiser nos charges de travail, mais nous pouvons également accéder à de nouvelles fonctions plus tôt.
Dans cet article, nous allons découvrir comment explorer et utiliser Microsoft GraphAPI pour Azure AD.
Sommaire
Conditions préalables
Vous devez remplir quelques conditions préalables avant de commencer. Avant de commencer avec les étapes décrites dans cet article, assurez-vous de rencontrer ou d'avoir les éléments suivants:
- Un enregistrement d'application dans AzureAD avec les autorisations GraphAPI suivantes:
- Directory.Read.All
- Directory.ReadWrite.All
- ID d'application (client-id) et client-secret pour l'enregistrement d'application ci-dessus
- Votre nom de locataire
- Un ordinateur exécutant PowerShell version 5.1 ou supérieure
Avec cela à l'écart, apprenons à explorer GraphAPI.
Lire la documentation
Microsoft GraphAPI est bien documenté et le meilleur point de départ pour découvrir comment utiliser une nouvelle fonction est de commencer dans la documentation de référence de l'API Microsoft Graph.
Cela spécifie comment utiliser une fonction spécifique et quelles autorisations vous devez utiliser. Il existe actuellement deux versions de GraphAPI: v1.0 et l'API bêta. Ils peuvent sembler identiques au premier abord, mais l'API bêta contient de nombreuses nouvelles fonctions qui ne sont pas encore publiées. Sachez également que les fonctions de l'API bêta sont susceptibles d'être modifiées à tout moment.
Autorisations
Les autorisations sont un élément important de l'exploration et de l'utilisation des autorisations de l'API Graph. Heureusement, toutes les autorisations dont vous avez besoin pour effectuer une certaine action sont spécifiées dans la documentation de référence de cette fonction.
La capture d'écran suivante montre l'autorisation nécessaire pour utiliser le getDirectoryObject une fonction. Et parce que vous y accéderez en tant qu'application, vous avez besoin du Directory.ReadAll autorisation.
Maintenant que vous avez les bases, commençons par demander un jeton d'accès, un secret temporaire que nous utiliserons pour accéder à l'API Microsoft Graph.
Demande d'un jeton d'accès
Le jeton d'accès est un secret que vous pouvez demander avec notre identifiant client et notre secret client. C'est ce jeton que vous devez dans les requêtes vers GraphAPI.
Pour demander un jeton d'accès, vous devez vous autoriser par rapport au point de terminaison oauth2 du locataire en publiant votre ID d'application et votre secret d'application.
Modifiez le script suivant, en remplaçant AppId, AppSecret et le nom du locataire, et exécutez-le dans PowerShell pour demander un jeton d'accès:
Add-Type -AssemblyName System.Web
$AppId = 'CHANGEME'
$AppSecret = 'CHANGEME'
$Scope = "https://graph.microsoft.com/.default"
$TenantName = "CHANGEME.onmicrosoft.com"
$Url = "https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token"
$Body = @{
client_id = $AppId
client_secret = $AppSecret
scope = $Scope
grant_type = 'client_credentials'
}
$PostSplat = @{
ContentType = 'application/x-www-form-urlencoded'
Method = 'POST'
Body = $Body
Uri = $Url
}
# Request the token!
$Request = Invoke-RestMethod @PostSplat
Maintenant, si vous regardez le $Request variable, vous pouvez voir qu'il contient notre jeton d'accès, ainsi que le type et le délai d'expiration.
PS51> $Request
token_type expires_in ext_expires_in access_token
---------- ---------- -------------- ------------
Bearer 3599 3599 eyJ...............
le expire dans est en quelques secondes, ce qui signifie que vous devez demander un nouveau jeton dans l'heure ou il cessera de fonctionner.
Enregistrons le jeton d'accès dans une variable pour une utilisation future, puis commençons à faire des requêtes vers le GraphApi:
PS51> $AccessToken = $Request.access_token
Votre première demande GraphAPI
Il est temps pour votre première demande de graphique! Les requêtes les plus simples pour commencer sont les requêtes qui utilisent HTTP GET. Les commandes GET sont uniquement destinées à récupérer des informations, vous n'avez donc pas à vous soucier de tout gâcher.
Nous commencerons par une simple demande listant les domaines liés à notre locataire. Et n'oubliez pas: lisez la documentation. Toutes les informations sur l'utilisation des fonctions GraphAPI se trouvent dans la documentation.
Vous avez peut-être remarqué dans la documentation du Liste des domaines commande que vous pouvez l'appeler en utilisant HTTP GET — la méthode par défaut lors de l'utilisation Invoke-RestMethod:
Avec ces informations, vous pouvez commencer à construire la demande. Pour cela, nous devons créer un En-tête d'autorisation qui contient «porteur
$Headers = @{
Authorization = "Bearer $AccessToken"
}
$Uri = "https://graph.microsoft.com/v1.0/domains"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Vous avez maintenant la liste des domaines dans le $Result variable, mais en essayant de sortir la valeur de la $Result entraînera ceci:
PS51> $Result
@odata.context value
-------------- -----
{@{authenticationType=Managed; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Le résultat de la requête se trouve généralement dans le valeur propriété du résultat. Vous pouvez obtenir le résultat complet en affichant simplement cette propriété à la place:
PS51> $Result.value
authenticationType : Managed
availabilityStatus :
id : contoso.com
isAdminManaged : True
isDefault : True
isInitial : False
isRoot : True
isVerified : True
supportedServices : {Email, Intune}
state :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
authenticationType : Managed
availabilityStatus :
id : contoso.onmicrosoft.com
isAdminManaged : True
isDefault : False
isInitial : True
isRoot : True
isVerified : True
supportedServices : {Email, OfficeCommunicationsOnline}
state :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
Maintenant que vous avez appris les bases de l'obtention d'informations avec GraphAPI, il est temps d'apprendre à utiliser les filtres.
Utilisation de filtres
C'est formidable de pouvoir récupérer toutes les données disponibles. Et même si cela peut fonctionner, il est terriblement inefficace. Une bonne pratique consiste à ne demander que les données dont vous avez besoin. Pour y parvenir dans GraphAPI, nous pouvons utiliser des filtres.
Un bon candidat pour essayer des filtres est de récupérer les utilisateurs. Ils ont beaucoup de noms d'attributs communs à Active Directory sur site, et vous en avez généralement au moins quelques-uns.
L'URI pour récupérer tous les utilisateurs est * https: //graph.microsoft.com/v1.0/users*, mais nous voulons filtrer cette demande. Vous pouvez le faire en ajoutant le $ filter =
Un filtre (généralement) se compose d'un opérateur de propriété et d'une valeur comme celle-ci:
property operator 'value'
Si vous voulez maintenant récupérer tous les utilisateurs avec le prénom "John", l'URI suivant doit être utilisé:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
Donc, si vous souhaitez utiliser PowerShell pour effectuer cette demande, le code devrait ressembler à ceci:
$Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Notez le backtick avant $filter– c'est pour échapper au signe dollar – sinon PowerShell l'aurait interprété comme une variable.
Jetez un œil à la propriété value et vous verrez tous les utilisateurs avec un nom donné de «John» dans Azure Active Directory:
PS51> $Result.value
businessPhones : {5554012}
displayName : John Doe
givenName : John
jobTitle :
mail : jdoe@contoso.com
mobilePhone :
officeLocation :
preferredLanguage : en
surname : Doe
userPrincipalName : jdoe@contoso.com
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
‘EQ’ n’est pas le seul opérateur, vous n’avez pas (ne), match, contains, moins / supérieur à (lt / gt), et bien plus encore. Bien que hors de la portée de cet article, plus d'informations sur les opérateurs sont disponibles dans la documentation. Une documentation plus complète sur les différentes propriétés de filtre est également disponible dans la documentation des propriétés de chaque type d'objet.
Création d'un utilisateur
Maintenant que vous avez les bases, exécutons une opération d'écriture et créons un utilisateur. Pour cela, vous devez savoir comment construire les données et où les publier. Vous pouvez voir un exemple sur la façon d'effectuer cela en allant dans la documentation de l'API Microsoft Graph et en regardant «Créer un utilisateur»:
Vous pouvez voir que vous devez envoyer les données sous forme de demande POST et que le type de contenu doit être application / json. Vous pouvez également voir une représentation JSON des données. L'objectif ici est de créer un objet PowerShell qui crée ce JSON lorsque ConvertTo-Json est utilisé dessus.
Essayons-le:
$Body = (PSCustomObject)@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "jane.doe@automativity.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
Fonctionnement $Body | ConvertTo-Json entraînera un JSON similaire à celui affiché dans la documentation. Il ne reste plus qu'à le convertir en JSON et le POSTER en URI GraphAPI avec le bon type de contenu:
$Body = (PSCustomObject)@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "jane.doe@contoso.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
$BodyJson = $Body | ConvertTo-Json
$Uri = "https://graph.microsoft.com/v1.0/users"
Invoke-RestMethod -Uri $Uri -Headers $Headers -Method POST -ContentType application/json -Body $BodyJson
Si vous allez maintenant dans notre console Azure Active Directory et jetez un œil, vous trouverez l'utilisateur nouvellement créé:
Vous avez maintenant créé votre premier utilisateur à l'aide de GraphAPI!
Conclusion
Microsoft GraphAPI est un outil puissant et vous permettra d'automatiser encore plus votre environnement. Et pas seulement en ce qui concerne Azure Active Directory, mais également pour la majorité des services SaaS proposés par Microsoft.
Compte tenu également du mouvement «sans serveur» utilisant Azure Functions ou AWS Lambda dans un événement, il est possible de créer des fonctions minimalistes et événementielles pour automatiser autant que possible dans votre environnement. Le tout sans avoir besoin d'inclure de grandes bibliothèques dans vos fonctions.
