Compilar aplicativos PHP com o Microsoft Graph e autenticação somente de aplicativo

Artigo
Developer (Iniciante)
19 minutos para concluir

Este tutorial ensina como criar um aplicativo de console PHP que usa a API do Microsoft Graph para acessar dados usando a autenticação somente de aplicativo. A autenticação somente de aplicativo é uma boa opção para serviços em segundo plano ou aplicativos que precisam acessar dados para todos os usuários em uma organização.

Observação

Para saber como usar o Microsoft Graph para acessar dados em nome de um usuário, consulte este tutorial de autenticação do usuário (delegada).

Neste tutorial, você vai:

Listar usuários

Dica

Como alternativa para seguir este tutorial, você pode baixar ou clonar o repositório do GitHub e seguir as instruções no LEIAME para registrar um aplicativo e configurar o projeto.

Pré-requisitos

Antes de iniciar este tutorial, você deve ter o PHP e o Composer instalados em seu computador de desenvolvimento.

Você também deve ter uma conta corporativa ou de estudante da Microsoft com a função de Administrador global. Se você não tiver um locatário Microsoft 365, poderá se qualificar para um por meio do Programa para desenvolvedores Microsoft 365; para obter detalhes, consulte Perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de um mês ou comprar um plano do Microsoft 365.

Observação

Este tutorial foi escrito com PHP versão 8.1.5 e Composer versão 2.3.5. As etapas neste guia podem funcionar com outras versões, mas isso não foi testado.

Registrar o aplicativo no portal

18 minutos restantes

Neste exercício, você registrará um novo aplicativo no Azure Active Directory para habilitar a autenticação somente de aplicativo. Você pode registrar um aplicativo usando o Centro de administração do Microsoft Entra ou usando o SDK do PowerShell para Microsoft Graph.

Registrar aplicativo para autenticação somente de aplicativo

Nesta seção, você registrará um aplicativo que dá suporte à autenticação somente de aplicativo usando fluxo de credenciais do cliente.

Centro de administração do Microsoft Entra
PowerShell

Abra um navegador e navegue até o Centro de administração do Microsoft Entra e faça logon usando uma conta de Administrador global.
Selecione Microsoft Entra ID no painel de navegação esquerdo, expanda Identidade, expanda Aplicativos e, em seguida, selecione Registros de aplicativo.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo, Graph App-Only Auth Tutorial.
Defina Tipos de conta com suporte para Contas somente neste diretório organizacional.
Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Visão Geral do aplicativo, copie o valor da ID do aplicativo (cliente) e da ID do diretório (locatário) e salve-os. Você precisará desses valores na próxima etapa.
Selecione Permissões de API em Gerenciar.
Remova a permissão padrão User.Read em Permissões configuradas selecionando as reticências (...) em sua linha e selecionando Remover permissão.
Selecione Adicionar uma permissão e, em seguida, Microsoft Graph.
Selecione Permissões de aplicativos.
Selecione User.Read.All e, em seguida, selecione Adicionar permissões.
Selecione Conceder consentimento do administrador para... e, em seguida, selecione Sim para dar consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e, em seguida, selecione Novo segredo do cliente.
Insira uma descrição, escolha uma duração e selecione Adicionar.
Copie o segredo da coluna Valor. Você precisará dele nas próximas etapas.

Importante

Este segredo do cliente nunca é mostrado novamente, portanto, certifique-se de copiá-lo agora.

Para usar o PowerShell, você precisará do SDK do PowerShell para Microsoft Graph. Se você não o tiver, consulte Instalar o SDK do PowerShell para Microsoft Graph para obter instruções de instalação.

Crie um novo arquivo chamado RegisterAppForAppOnlyAuth.ps1 e adicione o código a seguir.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$true,
  HelpMessage="The application permission scopes to configure on the app registration")]
  [String[]]
  $GraphScopes,

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

$graphAppId = "00000003-0000-0000-c000-000000000000"

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All AppRoleAssignment.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop
$authTenant = $context.TenantId

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience "AzureADMyOrg" -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
$appServicePrincipal = New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
  -ErrorVariable SPError
if ($SPError)
{
  Write-Host -ForegroundColor Red "A service principal for the app could not be created."
  Write-Host -ForegroundColor Red $SPError
  Exit
}

Write-Host -ForegroundColor Cyan "Service principal created"

# Lookup available Graph application permissions
$graphServicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $graphAppId + "'") -ErrorAction Stop
$graphAppPermissions = $graphServicePrincipal.AppRoles

$resourceAccess = @()

foreach($scope in $GraphScopes)
{
  $permission = $graphAppPermissions | Where-Object { $_.Value -eq $scope }
  if ($permission)
  {
    $resourceAccess += @{ Id =  $permission.Id; Type = "Role"}
  }
  else
  {
    Write-Host -ForegroundColor Red "Invalid scope:" $scope
    Exit
  }
}

# Add the permissions to required resource access
Update-MgApplication -ApplicationId $appRegistration.Id -RequiredResourceAccess `
 @{ ResourceAppId = $graphAppId; ResourceAccess = $resourceAccess } -ErrorAction Stop
Write-Host -ForegroundColor Cyan "Added application permissions to app registration"

# Add admin consent
foreach ($appRole in $resourceAccess)
{
  New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $appServicePrincipal.Id `
   -PrincipalId $appServicePrincipal.Id -ResourceId $graphServicePrincipal.Id `
   -AppRoleId $appRole.Id -ErrorAction SilentlyContinue -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "Admin consent for one of the requested scopes could not be added."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }
}
Write-Host -ForegroundColor Cyan "Added admin consent"

# Add a client secret
$clientSecret = Add-MgApplicationPassword -ApplicationId $appRegistration.Id -PasswordCredential `
 @{ DisplayName = "Added by PowerShell" } -ErrorAction Stop

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Tenant ID: "
Write-Host -ForegroundColor Yellow $authTenant
Write-Host -ForegroundColor Cyan -NoNewline "Client secret: "
Write-Host -ForegroundColor Yellow $clientSecret.SecretText
Write-Host -ForegroundColor Cyan -NoNewline "Secret expires: "
Write-Host -ForegroundColor Yellow $clientSecret.EndDateTime

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Salve o arquivo.
Abra o PowerShell e altere o diretório atual para o local RegisterAppForAppOnlyAuth.ps1.

Execute o seguinte comando:

.\RegisterAppForAppOnlyAuth.ps1 -AppName "Graph App-Only Auth Tutorial" -GraphScopes "User.Read.All"

Siga a solicitação para abrir https://microsoft.com/devicelogin em um navegador, insira o código fornecido e conclua o processo de autenticação.

Copie os valores ID do cliente, ID de locatário e Segredo do cliente da saída do script. Você precisará desses valores na próxima etapa.

SUCCESS
Client ID: ae2386e6-799e-4f75-b191-855d7e691c75
Tenant ID: 5927c10a-91bd-4408-9c70-c50bce922b71
Client secret: ...
Secret expires: 10/28/2024 5:01:45 PM

Observação

Observe que, ao contrário das etapas ao se registrar para autenticação de usuário, nesta seção você configurou permissões do Microsoft Graph no registro do aplicativo. Isso ocorre porque a autenticação somente de aplicativo usa o fluxo de credenciais do cliente, o que exige que as permissões sejam configuradas no registro do aplicativo. Consulte O escopo .default para obter detalhes.

Criar um aplicativo de console PHP

15 minutos restantes

Comece inicializando um novo projeto do Composer. Abra a CLI (interface de linha de comando) em um diretório no qual você deseja criar o projeto. Execute o seguinte comando:

composer init

Responda às solicitações. Você pode aceitar os padrões para a maioria das perguntas, mas responder n ao seguinte:

Would you like to define your dependencies (require) interactively [yes]? n
Would you like to define your dev dependencies (require-dev) interactively [yes]? n
Add PSR-4 autoload mapping? Maps namespace "Microsoft\Graphapponlytutorial" to the entered relative path. [src/, n to skip]: n

Instalar dependências

Antes de prosseguir, adicione algumas dependências adicionais que você usará posteriormente.

SDK do Microsoft Graph para PHP para fazer chamadas para o Microsoft Graph.
vlucas/phpdotenv para ler variáveis de ambiente a partir de arquivos .env.

Execute o seguinte comando na CLI para instalar as dependências.

composer require microsoft/microsoft-graph vlucas/phpdotenv

Carregar configurações do aplicativo

Nesta seção, você adicionará os detalhes do registro do aplicativo ao projeto.

Crie um arquivo no diretório raiz do projeto chamado .env e adicione o código a seguir.

CLIENT_ID=YOUR_CLIENT_ID_HERE
CLIENT_SECRET=YOUR_CLIENT_SECRET_HERE_IF_USING_APP_ONLY
TENANT_ID=YOUR_TENANT_ID_HERE_IF_USING_APP_ONLY

Atualize os valores de acordo com a tabela a seguir.

Configuração Valor

CLIENT_ID A ID do cliente do registro do aplicativo

CLIENT_SECRET O segredo do cliente do registro do aplicativo

TENANT_ID A ID do locatário da sua organização

Importante

Se você estiver usando controle do código-fonte, como git, agora seria um bom momento para excluir o arquivo .env do controle do código-fonte para evitar o vazamento acidental da ID do aplicativo.

Configuração	Valor
`CLIENT_ID`	A ID do cliente do registro do aplicativo
`CLIENT_SECRET`	O segredo do cliente do registro do aplicativo
`TENANT_ID`	A ID do locatário da sua organização

Design do aplicativo

Nesta seção, você criará um menu simples baseado em console.

Crie um arquivo no diretório raiz do projeto chamado main.php. Adicione as marcas PHP de abertura e fechamento.
```
<?php
?>
```

Adicione o código a seguir entre as marcas PHP.

// Enable loading of Composer dependencies
require_once realpath(__DIR__ . '/vendor/autoload.php');
require_once 'GraphHelper.php';

print('PHP Graph Tutorial'.PHP_EOL.PHP_EOL);

// Load .env file
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['CLIENT_ID', 'CLIENT_SECRET', 'TENANT_ID']);

initializeGraph();

$choice = -1;

while ($choice != 0) {
    echo('Please choose one of the following options:'.PHP_EOL);
    echo('0. Exit'.PHP_EOL);
    echo('1. Display access token'.PHP_EOL);
    echo('2. List users'.PHP_EOL);
    echo('3. Make a Graph call'.PHP_EOL);

    $choice = (int)readline('');

    switch ($choice) {
        case 1:
            displayAccessToken();
            break;
        case 2:
            listUsers();
            break;
        case 3:
            makeGraphCall();
            break;
        case 0:
        default:
            print('Goodbye...'.PHP_EOL);
    }
}

Adicione os métodos de espaço reservado a seguir no final do arquivo antes da marca PHP de fechamento. Você os implementará em etapas posteriores.

function initializeGraph(): void {
    // TODO
}

function displayAccessToken(): void {
    // TODO
}

function listUsers(): void {
    // TODO
}

function makeGraphCall(): void {
    // TODO
}

Isso implementa um menu básico e lê a escolha do usuário na linha de comando.

Adicionar autenticação somente de aplicativo

10 minutos restantes

Nesta seção, você adicionará a autenticação somente de aplicativo ao aplicativo. Isso é obrigatório para obter o token de acesso OAuth necessário para chamar o Microsoft Graph.

Configurar o cliente do Graph para autenticação somente de aplicativo

Nesta seção, você usará a classe PhpLeagueAuthenticationProvider para solicitar um token de acesso usando o fluxo de credenciais do cliente.

Crie um novo arquivo no diretório raiz do projeto chamado GraphHelper.php. Adicione o código a seguir.
```
<?php
class GraphHelper {
}
?>
```

Adicione as instruções using seguir dentro das marcas PHP.

use Microsoft\Graph\Core\Authentication\GraphPhpLeagueAccessTokenProvider;
use Microsoft\Graph\Generated\Models;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetQueryParameters;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Kiota\Authentication\Oauth\ClientCredentialContext;

Adicione o seguinte código à classe GraphHelper.

private static string $clientId = '';
private static string $clientSecret = '';
private static string $tenantId = '';
private static ClientCredentialContext $tokenContext;
private static GraphServiceClient $appClient;

public static function initializeGraphForAppOnlyAuth(): void {
    GraphHelper::$clientId = $_ENV['CLIENT_ID'];
    GraphHelper::$clientSecret = $_ENV['CLIENT_SECRET'];
    GraphHelper::$tenantId = $_ENV['TENANT_ID'];

    GraphHelper::$tokenContext = new ClientCredentialContext(
        GraphHelper::$tenantId,
        GraphHelper::$clientId,
        GraphHelper::$clientSecret);

    GraphHelper::$appClient = new GraphServiceClient(
        GraphHelper::$tokenContext, ['https://graph.microsoft.com/.default']);
}

Substitua a função initializeGraph vazia em main.php pelo seguinte.

function initializeGraph(): void {
    GraphHelper::initializeGraphForAppOnlyAuth();
}

Esse código carrega informações do arquivo .env e inicializa duas propriedades, um objeto ClientCredentialContext e um objeto GraphServiceClient. O objeto ClientCredentialContext será usado para autenticar solicitações e o objeto GraphServiceClient será usado para fazer chamadas para o Microsoft Graph.

Testar o fluxo de credenciais do cliente

Em seguida, adicione o código para obter um token de acesso do GraphHelper.

Adicione a função a seguir à classe GraphHelper.

public static function getAppOnlyToken(): string {
    // Create an access token provider to get the token
    $tokenProvider = new GraphPhpLeagueAccessTokenProvider(GraphHelper::$tokenContext);
    return $tokenProvider
        ->getAuthorizationTokenAsync('https://graph.microsoft.com')
        ->wait();
}

Substitua a função displayAccessToken vazia em main.php pelo seguinte.

function displayAccessToken(): void {
    try {
        $token = GraphHelper::getAppOnlyToken();
        print('App-only token: '.$token.PHP_EOL.PHP_EOL);
    } catch (Exception $e) {
        print('Error getting access token: '.$e->getMessage().PHP_EOL.PHP_EOL);
    }
}

Compile e execute o aplicativo. Insira 1 quando for solicitada uma opção. O aplicativo exibe o token de acesso obtido usando as informações de autenticação configuradas anteriormente nas variáveis de ambiente.
```
$ php main.php

PHP Graph Tutorial

Please choose one of the following options:
0. Exit
1. Display access token
2. List users
3. Make a Graph call
1
App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
```
Dica

Para fins de validação e depuração somente, você pode decodificar tokens de acesso somente de aplicativo usando o analisador de token online da Microsoft em https://jwt.ms. Isso pode ser útil se você encontrar erros de token ao chamar o Microsoft Graph. Por exemplo, verificando se a declaração role no token contém os escopos de permissão do Microsoft Graph esperados.

Listar usuários

7 minutos restantes

Nesta seção, você adicionará a capacidade de listar todos os usuários em seu Azure Active Directory usando a autenticação somente de aplicativo.

Adicione o seguinte código à classe GraphHelper.

public static function getUsers(): Models\UserCollectionResponse {
    $configuration = new UsersRequestBuilderGetRequestConfiguration();
    $configuration->queryParameters = new UsersRequestBuilderGetQueryParameters();
    // Only request specific properties
    $configuration->queryParameters->select = ['displayName','id','mail'];
    // Sort by display name
    $configuration->queryParameters->orderby = ['displayName'];
    // Get at most 25 results
    $configuration->queryParameters->top = 25;

    return GraphHelper::$appClient->users()->get($configuration)->wait();
}

Substitua a função listUsers vazia em main.php pelo seguinte.

function listUsers(): void {
    try {
        $users = GraphHelper::getUsers();

        // Output each user's details
        foreach ($users->getValue() as $user) {
            print('User: '.$user->getDisplayName().PHP_EOL);
            print('  ID: '.$user->getId().PHP_EOL);
            $email = $user->getMail();
            $email = isset($email) ? $email : 'NO EMAIL';
            print('  Email: '.$email.PHP_EOL);
        }

        $nextLink = $users->getOdataNextLink();
        $moreAvailable = isset($nextLink) && $nextLink != '' ? 'True' : 'False';
        print(PHP_EOL.'More users available? '.$moreAvailable.PHP_EOL.PHP_EOL);
    } catch (Exception $e) {
        print(PHP_EOL.'Error getting users: '.$e->getMessage().PHP_EOL.PHP_EOL);
    }
}

Execute o aplicativo, entre e escolha a opção 2 para listar usuários.

Please choose one of the following options:
0. Exit
1. Display access token
2. List users
3. Make a Graph call
2
User: Adele Vance
  ID: 05fb57bf-2653-4396-846d-2f210a91d9cf
  Email: AdeleV@contoso.com
User: Alex Wilber
  ID: a36fe267-a437-4d24-b39e-7344774d606c
  Email: AlexW@contoso.com
User: Allan Deyoung
  ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0
  Email: AllanD@contoso.com
User: Bianca Pisani
  ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49
  Email: NO EMAIL
User: Brian Johnson (TAILSPIN)
  ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4
  Email: BrianJ@contoso.com

...

More users available? true

Código explicado

Considere o código na função getUsers.

Ele obtém uma coleção de usuários.
Ele usa queryParameters->select para solicitar propriedades específicas
Ele usa queryParameters->top para limitar o número de usuários retornados
Ele usa queryParameters->orderby para classificar a resposta

Opcional: adicionar o seu próprio código

5 minutos restantes

Nesta seção, você adicionará seus próprios recursos do Microsoft Graph ao aplicativo. Isso pode ser um snippet de código da documentação do Microsoft Graph ou do Explorador do Graph ou código que você criou. Esta seção é opcional.

Atualizar o aplicativo

Adicione o seguinte código à classe GraphHelper.

public static function makeGraphCall(): void {
    // INSERT YOUR CODE HERE
}

Substitua a função makeGraphCall vazia em main.php pelo seguinte.

function makeGraphCall(): void {
    try {
        GraphHelper::makeGraphCall();
    } catch (Exception $e) {
        print(PHP_EOL.'Error making Graph call'.PHP_EOL.PHP_EOL);
    }
}

Escolher uma API

Encontre uma API do Microsoft Graph que você gostaria de experimentar. Por exemplo, a API Criar evento. Você pode usar um dos exemplos na documentação da API ou criar sua própria solicitação de API.

Configurar as permissões

Verifique a seção Permissões da documentação de referência da API escolhida para ver quais métodos de autenticação têm suporte. Algumas APIs não oferecem suporte somente a aplicativos ou a contas Microsoft pessoais, por exemplo.

Para chamar uma API com autenticação de usuário (se a API der suporte à autenticação de usuário (delegada)), consulte o tutorial autenticação de usuário (delegada).
Para chamar uma API com autenticação somente de aplicativo (se a API der suporte a ela), adicione o escopo de permissão necessário no centro de administração do Azure AD.

Adicionar seu código

Adicione seu código à função makeGraphCall em GraphHelper.php.

Compartilhar via

Compilar aplicativos PHP com o Microsoft Graph e autenticação somente de aplicativo

Pré-requisitos

Registrar o aplicativo no portal

Registrar aplicativo para autenticação somente de aplicativo

Criar um aplicativo de console PHP

Instalar dependências

Carregar configurações do aplicativo

Design do aplicativo

Adicionar autenticação somente de aplicativo

Configurar o cliente do Graph para autenticação somente de aplicativo

Testar o fluxo de credenciais do cliente

Listar usuários

Código explicado

Opcional: adicionar o seu próprio código

Atualizar o aplicativo

Escolher uma API

Configurar as permissões

Adicionar seu código

Parabéns!

Exemplos de PHP