Microsoft GraphAPI es una herramienta poderosa. No solo podemos usarlo para crear herramientas para automatizar nuestras cargas de trabajo, además podemos tener acceso a nuevas funciones antes.
En este post, aprenderemos a explorar y utilizar Microsoft GraphAPI para Azure AD.
Prerrequisitos
Debe cumplir con algunos requerimientos previos antes de que podamos comenzar. Antes de comenzar con los pasos descritos en este post, asegúrese de cumplir o tener lo siguiente:
- Un Registro de la aplicación en AzureAD con los siguientes permisos GraphAPI:
- Directorio.Leer.todos
- Directory.ReadWrite.All
- Id. De aplicación (id. De cliente) y secreto de cliente para el registro de la aplicación anterior
- Su nombre de inquilino
- Una computadora con PowerShell versión 5.1 o superior
Con eso fuera del camino, aprendamos a explorar GraphAPI.
Leer la documentación
Microsoft GraphAPI está bien documentado y el mejor lugar para comenzar cuando descubra cómo utilizar una nueva función es comenzar en el documentación de referencia de la API de Microsoft Graph.
Esto especifica cómo utilizar una función específica y qué permisos necesita para usarla. En este momento existen dos versiones de GraphAPI: v1.0 y la API beta. Pueden parecer idénticas al principio, pero la API beta contiene muchas funciones nuevas que aún no se han lanzado. Además tenga en cuenta que las funciones de la API beta están sujetas a cambios en cualquier momento.
Permisos
Los permisos son una parte importante de la exploración y el uso de los permisos de la API Graph; por suerte, todos los permisos que necesita para realizar una determinada acción se especifican en la documentación de referencia de esa función.
La próxima captura de pantalla muestra el permiso necesario para utilizar el getDirectoryObject función. Y como accederá a él como una aplicación, necesita la Directory.ReadAll permiso.
Ahora que tiene los conceptos básicos, comencemos solicitando un token de acceso, un secreto temporal que usaremos para tener acceso a la API de Microsoft Graph.
Solicitar un token de acceso
El token de acceso es un secreto que puede solicitar con nuestra identificación de cliente y secreto de cliente. Este es el token que debe en las solicitudes hacia GraphAPI.
Para solicitar un token de acceso, debe autorizarse contra el punto final oauth2 del inquilino publicando su ID de aplicación y el secreto de la aplicación.
Edite el siguiente script, reemplazando AppId, AppSecret y Tenant name, y ejecútelo en PowerShell para solicitar un token de acceso:
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
Ahora, si echas un vistazo al $Request variable, puede ver que contiene nuestro token de acceso, así como el tipo y el tiempo de vencimiento.
PS51> $Request
token_type expires_in ext_expires_in access_token
---------- ---------- -------------- ------------
Bearer 3599 3599 eyJ...............
los expira en es en segundos, lo que significa que debe solicitar un nuevo token en una hora o dejará de funcionar.
Guardemos el token de acceso en una variable para uso futuro y posteriormente comencemos a hacer solicitudes hacia GraphApi:
PS51> $AccessToken = $Request.access_token
Su primera solicitud GraphAPI
¡Es hora de su primera solicitud de gráfico! Las solicitudes más simples para comenzar son las solicitudes que usan HTTP GET. Los comandos GET son solo para obtener información, por lo que no debe preocuparse por estropear nada.
Comenzaremos con una simple solicitud que enumere los dominios vinculados a nuestro inquilino. Y recuerde, lea la documentación. Toda la información acerca de cómo usar las funciones GraphAPI se encuentra en el documentación.
Es factible que haya notado en la documentación del Lista de dominios comando que puede llamar a través de HTTP GET, el método predeterminado cuando se utiliza Invoke-RestMethod:
Con esta información, puede comenzar a construir la solicitud. Para eso, necesitamos crear un Encabezado de autorización que contiene «Bearer
$Headers = @{
Authorization = "Bearer $AccessToken"
}
$Uri = "https://graph.microsoft.com/v1.0/domains"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Ahora tiene la lista de dominios en el $Result variable, pero tratando de generar el valor de la $Result La variable resultará en esto:
PS51> $Result
@odata.context value
-------------- -----
<https://graph.microsoft.com/v1.0/$metadata#domains> {@{authenticationType=Managed; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
El resultado de la consulta suele estar en el valor propiedad del resultado. Puede obtener el resultado completo simplemente generando esa propiedad en su lugar:
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
Ahora que ha aprendido los conceptos básicos para obtener información con GraphAPI, es hora de aprender a utilizar filtros.
Utilizar filtros
Es genial poder recuperar todos los datos disponibles. Y aún cuando puede funcionar, es terriblemente ineficaz. Una buena práctica es solicitar solo los datos que necesita. Para lograr esto en GraphAPI, podemos utilizar filtros.
Un buen candidato para probar filtros es buscar usuarios. Disponen muchos nombres de atributos comunes a Active Directory local y, por lo general, tiene al menos algunos de ellos.
El URI para obtener todos los usuarios es *https://graph.microsoft.com/v1.0/users*, pero queremos filtrar esta solicitud. Puede hacerlo agregando el $ filtro =
Un filtro (de forma general) consta de un operador de propiedad y un valor como este:
property operator 'value'
Si ahora desea buscar a todos los usuarios con el nombre de pila «John», se debe usar el siguiente URI:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
Entonces, si desea utilizar PowerShell para realizar esta solicitud, el código debería verse así:
$Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Fíjate en la comilla invertida antes $filter—Eso para escapar del signo del dólar — caso contrario, PowerShell lo habría interpretado como una variable.
Eche un vistazo a la propiedad de valor y verá todos los usuarios con un nombre dado de «John» en 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’ no es el único operador, no tiene (ne), coincide, contiene, menor / mayor que (lt / gt), y mucho más. Aunque está fuera del alcance de este post, hay más información disponible sobre los operadores en el documentación. Además hay disponible documentación más extensa sobre las diferentes propiedades del filtro en la propiedad. documentación sobre cada tipo de objeto.
Crear un usuario
Ahora que tiene los conceptos básicos, realicemos una operación de escritura y creemos un usuario. Para eso, necesita saber cómo construir los datos y dónde PUBLICARlos. Puede ver un ejemplo acerca de cómo realizar eso yendo a la documentación de la API de Microsoft Graph y mirando «Crear usuario»:
Puede ver que necesita enviar los datos como una solicitud POST y que el tipo de contenido debe ser de aplicación / json. Además puede ver una representación JSON de los datos; el objetivo aquí es crear un objeto de PowerShell que cree ese JSON cuando ConvertTo-Json se utiliza en él.
Vamos a intentarlo:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "[email protected]"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
Corriendo $Body | ConvertTo-Json dará como consecuencia un JSON semejante al que se muestra en la documentación. Lo que queda ahora es convertirlo a JSON y PUBLICARLO en GraphAPI URI con el tipo de contenido correcto:
$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 ahora va a nuestra Consola de Azure Active Directory y echa un vistazo, encontrará el usuario recién creado:
¡Ya ha creado su primer usuario usando GraphAPI!
Conclusión
Microsoft GraphAPI es una herramienta poderosa y le permitirá automatizar aún más su entorno. Y no solo cuando se trata de Azure Active Directory, sino además de la mayoría de los servicios SaaS que ofrece Microsoft.
Al mismo tiempo, considerando el movimiento «sin servidor» que utiliza Azure Functions o AWS Lambda en un evento, es factible crear funciones minimalistas y controladas por eventos para automatizar tanto como sea factible en su entorno. Todo sin necesitar de incluir grandes bibliotecas en sus funciones.
