Microsoft GraphAPI est un outil puissant. Nous pouvons non seulement l'utiliser pour créer des outils pour automatiser nos charges de travail, on peut aussi avoir accès à de nouvelles fonctions avant.
Dans ce billet, Nous apprendrons à explorer et à utiliser Microsoft GraphAPI pour Azure AD.
Conditions préalables
Vous devez remplir certains prérequis avant que nous puissions commencer. Avant de commencer avec les étapes décrites dans ce post, assurez-vous de rencontrer ou d'avoir les éléments suivants:
- Un Enregistrement de l'application dans AzureAD avec les autorisations GraphAPI suivantes:
- Répertoire.Lisez.tout
- Répertoire.Lire.Tout.
- Identifiant. d'application (identifiant. Du client) et secret client pour l'enregistrement de l'application ci-dessus
- Votre nom de locataire
- Un ordinateur avec la version PowerShell 5.1 le supérieur
Avec ça à 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 par le documentation de référence de l'API de Microsoft Graph.
Cela spécifie comment utiliser une fonction spécifique et les autorisations dont vous avez besoin pour l'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 beaucoup de nouvelles fonctionnalités qui n'ont pas encore été publiées. Notez également que les fonctions de l'API bêta sont susceptibles d'être modifiées à tout moment.
Autorisations
Les autorisations sont une partie importante de l'exploration et de l'utilisation des autorisations de l'API Graph; par chance, Toutes les autorisations dont vous avez besoin pour effectuer une certaine action sont spécifiées dans le documentation de référence de cette fonction.
La capture d'écran suivante montre l'autorisation requise pour utiliser le getDirectoryObject fonction. Et comment vous y accéderez en tant qu'application, besoin du Répertoire.Lire Tout Excuse-moi.
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.
Demander un jeton d'accès
Le jeton d'accès est un secret que vous pouvez demander avec notre identification client et notre secret client. C'est le jeton que vous devez dans les requêtes vers GraphAPI.
Pour demander un jeton d'accès, doit être autorisé sur le point de terminaison oauth2 du locataire en publiant son identifiant d'application et son secret d'application.
Modifier le script suivant, remplacement de l'ID d'application, AppSecret y 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"
$Dirección 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 = $Dirección url
}
# Request the token!
$Request = Invoke-RestMethod @PostSplat
Maintenant, si vous jetez un oeil au $Request variable, vous pouvez voir ce que contient notre jeton d'accès, ainsi que le type et la date d'expiration.
PS51> $Request
token_type expires_in ext_expires_in access_token
---------- ---------- -------------- ------------
Bearer 3599 3599 eyJ...............
Les expire dans c'est en quelques secondes, ce qui signifie que vous devez demander un nouveau jeton dans une heure ou il cessera de fonctionner.
Enregistrons le jeton d’accès dans une variable pour une utilisation ultérieure, puis commençons à envoyer des demandes à GraphApi:
PS51> $AccessToken = $Request.access_token
Votre première application 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 fournies à titre d’information uniquement, pour que vous n’ayez pas à vous soucier de gâcher quoi que ce soit.
Nous commencerons par une simple requête qui répertorie les domaines liés à notre locataire. Et rappelez-vous, lire la documentation. Toutes les informations sur l’utilisation des fonctions graphAPI se trouvent dans le Documentation.
Il est possible que vous l’ayez remarqué dans la documentation du Liste des domaines commande que vous pouvez appeler via HTTP GET, la méthode par défaut lorsqu’elle est utilisée Invoke-RestMethod:
Avec ces informations, vous pouvez commencer à générer la demande. Pour ça, 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 générer la valeur de la $Result La variable entraînera cette:
PS51> $Result
@odata.context value
-------------- -----
<https://graph.microsoft.com/v1.0/$metadata#domains> {@{authenticationType=Managed; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Le résultat de la requête est généralement dans le valeur propriété de résultat. Vous pouvez obtenir le résultat complet simplement en générant 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.
Utiliser des filtres
C'est génial de pouvoir récupérer toutes les données disponibles. Et même quand ça peut marcher, c'est terriblement inefficace. Une bonne pratique consiste à demander uniquement les données dont vous avez besoin. Pour y parvenir dans GraphAPI, nous pouvons utiliser des filtres.
Un bon candidat pour tester les filtres recherche utilisateurs. Ils ont de nombreux noms d'attributs communs à Active Directory local et, en général, a au moins certains d'entre eux.
L'URI pour obtenir tous les utilisateurs est *https://graph.microsoft.com/v1.0/users*, mais nous voulons filtrer cette demande. Vous pouvez le faire en ajoutant le $ filtre =
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 souhaitez maintenant rechercher tous les utilisateurs avec le prénom “Jean”, l'URI suivant doit être utilisé:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
Ensuite, si vous souhaitez utiliser PowerShell pour faire 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
Remarquez le backtick plus tôt $filter— Que pour échapper au signe dollar - sinon, PowerShell l'aurait interprété comme une variable.
Jetez un coup d’œil à la propriété value et vous verrez tous les utilisateurs avec un nom donné de “Jean” dans Azure Active Directory:
PS51> $Result.value
businessPhones : {5554012}
displayName : John Doe
givenName : John
jobTitle :
mail : [email protected]
mobilePhone :
officeLocation :
preferredLanguage : en
surname : Doe
userPrincipalName : [email protected]
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
'EQ’ n'est pas le seul opérateur, il n'a pas (ne), coïncider, contient, moins / plus grand que (ll / gt), beaucoup plus. Bien que cela dépasse le cadre de cet article, plus d'informations sur les opérateurs sont disponibles dans le Documentation. De plus, une documentation plus complète sur les différentes propriétés du filtre est disponible dans la propriété. Documentation sur chaque type d'objet.
Créer un utilisateur
Maintenant que vous avez les bases, effectuons une opération d'écriture et créons un utilisateur. Pour ça, vous devez savoir comment construire les données et où les PUBLIER. Vous pouvez voir un exemple de la façon de procéder en consultant la documentation de l'API Microsoft Graph et en consultant “Créer un utilisateur”:
Vous pouvez voir que vous devez envoyer les données en tant que requête POST et que le type de contenu doit être de application / json. Vous pouvez également voir une représentation JSON des données; le but ici est de créer un objet PowerShell qui crée ce JSON lorsque ConvertTo-Json est utilisé dedans.
Essayons:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "[email protected]"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
Pressé $Body | ConvertTo-Json se traduira par un JSON similaire à celui indiqué dans la documentation. Il ne reste plus qu'à le convertir en JSON et à le POSTER sur GraphAPI URI avec le bon type de contenu:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "[email protected]"
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, trouvera l'utilisateur nouvellement créé:
Vous avez déjà créé votre premier utilisateur à l'aide de GraphAPI!
conclusion
Microsoft GraphAPI est un outil puissant et vous permettra d'automatiser davantage votre environnement. Et pas seulement en ce qui concerne Azure Active Directory, mais en plus de la plupart des services SaaS proposés par Microsoft.
En même temps, considérant le mouvement “sans serveur” qui utilise 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.
