Microsoft GraphAPI é uma ferramenta poderosa. Não podemos apenas usá-lo para criar ferramentas para automatizar nossas cargas de trabalho, também podemos ter acesso a novas funções antes.
Neste post, Aprenderemos a explorar e usar o Microsoft GraphAPI para Azure AD.
Pré-requisitos
Você deve atender a alguns pré-requisitos antes de começarmos. Antes de começar com as etapas descritas nesta postagem, certifique-se de conhecer ou ter o seguinte:
- uma Registro de aplicativo no AzureAD com as seguintes permissões GraphAPI:
- Directory.Read.all
- Directory.ReadWrite.All
- Identificação. De aplicação (Eu iria. Do cliente) e o segredo do cliente para o registro do aplicativo acima
- O seu nome de inquilino
- Um computador com versão PowerShell 5.1 o superior
Com isso fora do caminho, vamos aprender a explorar GraphAPI.
Leia a documentação
O Microsoft GraphAPI está bem documentado e o melhor lugar para começar ao descobrir como usar uma nova função é começar no documentação de referência de la API do Microsoft Graph.
Isso especifica como usar uma função específica e quais permissões você precisa para usá-la. Neste momento, existem duas versões do GraphAPI: v1.0 e a API beta. Eles podem parecer idênticos à primeira vista, mas a API beta contém muitos recursos novos que ainda não foram lançados. Observe também que as funções beta da API estão sujeitas a alterações a qualquer momento.
Permissões
As permissões são uma parte importante da exploração e do uso das permissões da API Graph; por sorte, Todas as permissões de que você precisa para executar uma determinada ação são especificadas no documentação de referência dessa função.
A próxima captura de tela mostra a permissão necessária para usar o getDirectoryObject Função. E como você vai acessá-lo como um aplicativo, precisa do Directory.ReadAll Com licença.
Agora que você tem o básico, vamos começar solicitando um token de acesso, um segredo temporário que usaremos para acessar a API do Microsoft Graph.
Solicite um token de acesso
O token de acesso é um segredo que você pode solicitar com nossa identificação de cliente e segredo do cliente. Este é o token que você deve nas solicitações para GraphAPI.
Para solicitar um token de acesso, deve ser autorizado no endpoint oauth2 do locatário, publicando seu ID de aplicativo e segredo de aplicativo.
Edite o seguinte script, substituindo AppId, AppSecret y Tenant name, e execute-o no PowerShell para solicitar um token de acesso:
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
Agora, se você der uma olhada no $Request variável, você pode ver o que nosso token de acesso contém, bem como o tipo e o tempo de expiração.
PS51> $Request
token_type expires_in ext_expires_in access_token
---------- ---------- -------------- ------------
Bearer 3599 3599 eyJ...............
a expira em está em segundos, o que significa que você precisa solicitar um novo token em uma hora ou ele deixará de funcionar.
Vamos salvar o token de acesso em uma variável para uso futuro e, em seguida, começar a fazer solicitações para GraphApi:
PS51> $AccessToken = $Request.access_token
Sua primeira solicitação GraphAPI
É hora de sua primeira solicitação de gráfico!! As solicitações mais simples para começar são as solicitações que usam HTTP GET. Los comandos GET son solo para obtener información, por lo que no debe preocuparse por estropear nada.
Começaremos com uma solicitação simples que lista os domínios vinculados ao nosso locatário. E lembre-se, leia a documentação. Todas as informações sobre como usar as funções GraphAPI podem ser encontradas no documentação.
Você deve ter notado na documentação do Lista de domínios comando que você pode chamar via HTTP GET, o método padrão ao usar Invoke-RestMethod:
Com esta informação, você pode começar a construir o pedido. Para isso, precisamos criar um Cabeçalho de autorização 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 variável, 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
Agora que você aprendeu o básico para obter informações com GraphAPI, é hora de aprender a usar filtros.
Use filtros
É ótimo poder recuperar todos os dados disponíveis. E mesmo quando pode funcionar, é terrivelmente ineficaz. Uma boa prática é solicitar apenas os dados de que você precisa. Para conseguir isso no GraphAPI, podemos usar filtros.
Um bom candidato para testar filtros é pesquisar Comercial. Eles têm muitos nomes de atributos comuns ao Active Directory local e, em geral, tem pelo menos alguns deles.
O URI para obter todos os usuários é *https://graph.microsoft.com/v1.0/users*, mas queremos filtrar este pedido. Você pode fazer isso adicionando o $ filtro =
Um filtro (geralmente) consiste em um operador de propriedade e um valor como este:
property operator 'value'
Se agora você deseja pesquisar todos os usuários com o Primeiro nome “João”, o seguinte URI deve ser usado:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
Então, se você quiser usar o PowerShell para fazer essa solicitação, o código deve ser parecido com este:
$Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Observe o backtick mais cedo $filter—Isso para escapar do cifrão - caso contrário, PowerShell o teria interpretado como uma variável.
Eche un vistazo a la propiedad de valor y verá todos los usuarios con un nombre dado de “João” 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’ não é a única operadora, não tem (nascido), coincidir, contém, menos / maior do que (lt / gt), e muito mais. Embora esteja fora do escopo desta postagem, mais informações sobre as operadoras estão disponíveis no documentação. Além disso, uma documentação mais extensa sobre as diferentes propriedades do filtro está disponível na propriedade. documentação sobre cada tipo de objeto.
Criar um usuário
Agora que você tem o básico, vamos realizar uma operação de gravação e criar um usuário. Para isso, você precisa saber como construir os dados e onde PUBLICÁ-los. Você pode ver um exemplo de como fazer isso acessando a documentação da API do Microsoft Graph e observando “Criar usuário”:
Você pode ver que precisa enviar os dados como uma solicitação POST e que o tipo de conteúdo deve ser de aplicativo / json. Você também pode ver uma representação JSON dos dados; o objetivo aqui é criar um objeto PowerShell que cria esse JSON quando ConvertTo-Json é usado nele.
Vamos tentar:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "[email protected]"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
Com pressa $Body | ConvertTo-Json resultará em um JSON semelhante ao mostrado na documentação. O que resta agora é convertê-lo para JSON e POST-lo para GraphAPI URI com o tipo de conteúdo correto:
$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
Se você agora for para o nosso Azure Active Directory Console e dê uma olhada, irá encontrar o usuário recém-criado:
Você já criou seu primeiro usuário usando GraphAPI!
conclusão
O Microsoft GraphAPI é uma ferramenta poderosa e permitirá que você automatize ainda mais seu ambiente. E não apenas quando se trata do Azure Active Directory, mas além da maioria dos serviços SaaS oferecidos pela Microsoft.
Ao mesmo tempo, considerando el movimiento “sin servidor” que utiliza Azure Functions o AWS Lambda en un evento, é viável criar funções minimalistas e orientadas a eventos para automatizar tanto quanto for viável em seu ambiente. Tudo sem a necessidade de incluir grandes bibliotecas em suas funções.
