Criar aplicativos .NET com o Microsoft Graph e a autenticação somente aplicativo

Artigo
Developer (Iniciante)
19 minutos para concluir

Este tutorial ensina como criar um aplicativo de console .NET que usa o microsoft API do Graph para acessar dados usando autenticação somente aplicativo. A autenticação somente aplicativo é uma boa opção para serviços em segundo plano ou aplicativos que precisam acessar dados para todos os usuários de 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 de usuário (delegado).

Neste tutorial, você vai:

Listar usuários

Dica

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

Pré-requisitos

Antes de iniciar este tutorial, você deve ter o SDK do .NET instalado em seu computador de desenvolvimento.

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

Observação

Este tutorial foi escrito com o SDK do .NET versão 7.0.102. 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 aplicativo. Você pode registrar um aplicativo usando o centro de administração do Azure Active Directory ou usando o SDK do Microsoft Graph PowerShell.

Registrar aplicativo para autenticação somente aplicativo

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

Azure AD centro de administração
PowerShell

Abra um navegador e navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta Administrador global.
Selecione Azure Active Directory na navegação esquerda e selecione Registros de aplicativos em Gerenciar.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo, Graph App-Only Auth Tutorial.
Defina tipos de conta com suporte apenas para contas 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 selecione Sim para fornecer o consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e 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 Microsoft Graph PowerShell. Se você não tiver, consulte Instalar o SDK do Microsoft Graph PowerShell 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 do RegisterAppForAppOnlyAuth.ps1.

Execute o seguinte comando:

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

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

Copie a ID do cliente, a ID do locatário e os valores de 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 do usuário, nesta seção você configurou as permissões do Microsoft Graph no registro do aplicativo. Isso ocorre porque a auth somente 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 .NET

15 minutos restantes

Comece criando um novo projeto de console do .NET usando a CLI do .NET.

Abra sua CLI (interface de linha de comando) em um diretório em que você deseja criar o projeto. Execute o seguinte comando:
```
dotnet new console -o GraphAppOnlyTutorial
```
Depois que o projeto for criado, verifique se ele funciona alterando o diretório atual para o diretório GraphTutorial e executando o comando a seguir na CLI.
```
dotnet run
```
Se funcionar, o aplicativo deverá gerar Hello, World!.

Instalar dependências

Antes de seguir em frente, adicione algumas dependências adicionais que você usará posteriormente.

Pacotes de configuração do .NET para ler a configuração do aplicativo de appsettings.json.
Biblioteca de clientes do Azure Identity para .NET para autenticar o usuário e adquirir tokens de acesso.
Biblioteca de clientes do Microsoft Graph .NET para fazer chamadas para o Microsoft Graph.

Execute os comandos a seguir na CLI para instalar as dependências.

dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
dotnet add package Azure.Identity
dotnet add package Microsoft.Graph

Carregar configurações do aplicativo

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

Crie um arquivo no diretório GraphAppOnlyTutorial chamado appsettings.json e adicione o código a seguir.

{
  "settings": {
    "clientId": "YOUR_CLIENT_ID_HERE",
    "tenantId": "YOUR_TENANT_ID_HERE"
  }
}

Atualize os valores de acordo com a tabela a seguir.

Configuração Valor

clientId A ID do cliente do registro do aplicativo

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

Dica

Opcionalmente, você pode definir esses valores em um arquivo separado chamado appsettings. Development.json.
Adicione o segredo do cliente ao .NET Secret Manager. Em sua interface de linha de comando, altere o diretório para o local de GraphAppOnlyTutorial.csproj e execute os comandos a seguir, substituindo <o segredo> do cliente pelo segredo do cliente.
```
dotnet user-secrets init
dotnet user-secrets set settings:clientSecret <client-secret>
```
Atualize GraphAppOnlyTutorial.csproj para copiar appsettings.json para o diretório de saída. Adicione o código a seguir entre as <Project> linhas e </Project> .
```
<ItemGroup>
  <None Include="appsettings*.json">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
</ItemGroup>
```

Configuração	Valor
`clientId`	A ID do cliente do registro do aplicativo
`tenantId`	A ID do locatário da sua organização.

Crie um arquivo no diretório GraphAppOnlyTutorial chamado Settings.cs e adicione o código a seguir.

using Microsoft.Extensions.Configuration;

public class Settings
{
    public string? ClientId { get; set; }
    public string? ClientSecret { get; set; }
    public string? TenantId { get; set; }

    public static Settings LoadSettings()
    {
        // Load settings
        IConfiguration config = new ConfigurationBuilder()
            // appsettings.json is required
            .AddJsonFile("appsettings.json", optional: false)
            // appsettings.Development.json" is optional, values override appsettings.json
            .AddJsonFile($"appsettings.Development.json", optional: true)
            // User secrets are optional, values override both JSON files
            .AddUserSecrets<Program>()
            .Build();

        return config.GetRequiredSection("Settings").Get<Settings>() ??
            throw new Exception("Could not load app settings. See README for configuration instructions.");
    }
}

Design do aplicativo

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

Abra ./Program.cs e substitua todo o conteúdo pelo código a seguir.

Console.WriteLine(".NET Graph App-only Tutorial\n");

var settings = Settings.LoadSettings();

// Initialize Graph
InitializeGraph(settings);

int choice = -1;

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

    try
    {
        choice = int.Parse(Console.ReadLine() ?? string.Empty);
    }
    catch (System.FormatException)
    {
        // Set to invalid value
        choice = -1;
    }

    switch(choice)
    {
        case 0:
            // Exit the program
            Console.WriteLine("Goodbye...");
            break;
        case 1:
            // Display access token
            await DisplayAccessTokenAsync();
            break;
        case 2:
            // List users
            await ListUsersAsync();
            break;
        case 3:
            // Run any Graph code
            await MakeGraphCallAsync();
            break;
        default:
            Console.WriteLine("Invalid choice! Please try again.");
            break;
    }
}

Adicione os seguintes métodos de espaço reservado no final do arquivo. Você os implementará em etapas posteriores.

void InitializeGraph(Settings settings)
{
    // TODO
}

async Task DisplayAccessTokenAsync()
{
    // TODO
}

async Task ListUsersAsync()
{
    // TODO
}

async Task MakeGraphCallAsync()
{
    // TODO
}

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

Adicionar autenticação somente aplicativo

9 minutos restantes

Nesta seção, você adicionará a autenticação somente aplicativo ao aplicativo. Isso é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph. Nesta etapa, você integrará a biblioteca de clientes do Azure Identity para .NET no aplicativo e configurará a autenticação para a biblioteca de clientes .NET do Microsoft Graph.

A biblioteca de Identidade do Azure fornece várias classes que implementam fluxos de TokenCredential token OAuth2. A biblioteca de clientes do Microsoft Graph usa essas classes para autenticar chamadas para o Microsoft Graph.

Configurar o cliente graph para autenticação somente aplicativo

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

Crie um novo arquivo no diretório GraphTutorial chamado GraphHelper.cs e adicione o código a seguir a esse arquivo.

using Azure.Core;
using Azure.Identity;
using Microsoft.Graph;
using Microsoft.Graph.Models;

class GraphHelper
{
}

Adicione o seguinte código à classe GraphHelper.

// Settings object
private static Settings? _settings;
// App-ony auth token credential
private static ClientSecretCredential? _clientSecretCredential;
// Client configured with app-only authentication
private static GraphServiceClient? _appClient;

public static void InitializeGraphForAppOnlyAuth(Settings settings)
{
    _settings = settings;

    // Ensure settings isn't null
    _ = settings ??
        throw new System.NullReferenceException("Settings cannot be null");

    _settings = settings;

    if (_clientSecretCredential == null)
    {
        _clientSecretCredential = new ClientSecretCredential(
            _settings.TenantId, _settings.ClientId, _settings.ClientSecret);
    }

    if (_appClient == null)
    {
        _appClient = new GraphServiceClient(_clientSecretCredential,
            // Use the default scope, which will request the scopes
            // configured on the app registration
            new[] {"https://graph.microsoft.com/.default"});
    }
}

Substitua a função vazia InitializeGraph no Program.cs pelo seguinte.

void InitializeGraph(Settings settings)
{
    GraphHelper.InitializeGraphForAppOnlyAuth(settings);
}

Esse código declara duas propriedades privadas, um ClientSecretCredential objeto e um GraphServiceClient objeto. A InitializeGraphForAppOnlyAuth função cria uma nova instância de ClientSecretCredential, em seguida, usa essa instância para criar uma nova instância de GraphServiceClient. Sempre que uma chamada de API é feita ao Microsoft Graph por meio do _appClient, ela usa a credencial fornecida para obter um token de acesso.

Testar o ClientSecretCredential

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

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

public static async Task<string> GetAppOnlyTokenAsync()
{
    // Ensure credential isn't null
    _ = _clientSecretCredential ??
        throw new System.NullReferenceException("Graph has not been initialized for app-only auth");

    // Request token with given scopes
    var context = new TokenRequestContext(new[] {"https://graph.microsoft.com/.default"});
    var response = await _clientSecretCredential.GetTokenAsync(context);
    return response.Token;
}

Substitua a função vazia DisplayAccessTokenAsync no Program.cs pelo seguinte.

async Task DisplayAccessTokenAsync()
{
    try
    {
        var appOnlyToken = await GraphHelper.GetAppOnlyTokenAsync();
        Console.WriteLine($"App-only token: {appOnlyToken}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error getting app-only access token: {ex.Message}");
    }
}

Crie e execute o aplicativo. Insira 1 quando solicitado para uma opção. O aplicativo exibe um token de acesso.
```
.NET 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

Somente para fins de validação e depuração, você pode decodificar tokens de acesso somente 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, verificar se a role declaração no token contém os escopos de permissão esperados do Microsoft Graph.

Listar usuários

6 minutos restantes

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

Abra ./GraphHelper.cs e adicione a seguinte função à classe GraphHelper .

public static Task<UserCollectionResponse?> GetUsersAsync()
{
    // Ensure client isn't null
    _ = _appClient ??
        throw new System.NullReferenceException("Graph has not been initialized for app-only auth");

    return _appClient.Users.GetAsync((config) =>
    {
        // Only request specific properties
        config.QueryParameters.Select = new[] { "displayName", "id", "mail" };
        // Get at most 25 results
        config.QueryParameters.Top = 25;
        // Sort by display name
        config.QueryParameters.Orderby = new[] { "displayName" };
    });
}

Substitua a função vazia ListUsersAsync no Program.cs pelo seguinte.

async Task ListUsersAsync()
{
    try
    {
        var userPage = await GraphHelper.GetUsersAsync();

        if (userPage?.Value == null)
        {
            Console.WriteLine("No results returned.");
            return;
        }

        // Output each users's details
        foreach (var user in userPage.Value)
        {
            Console.WriteLine($"User: {user.DisplayName ?? "NO NAME"}");
            Console.WriteLine($"  ID: {user.Id}");
            Console.WriteLine($"  Email: {user.Mail ?? "NO EMAIL"}");
        }

        // If NextPageRequest is not null, there are more users
        // available on the server
        // Access the next page like:
        // var nextPageRequest = new UsersRequestBuilder(userPage.OdataNextLink, _appClient.RequestAdapter);
        // var nextPage = await nextPageRequest.GetAsync();
        var moreAvailable = !string.IsNullOrEmpty(userPage.OdataNextLink);

        Console.WriteLine($"\nMore users available? {moreAvailable}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error getting users: {ex.Message}");
    }
}

Execute o aplicativo 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 GetUsersAsync função.

Ele obtém uma coleção de usuários
Ele usa para solicitar propriedades específicas Select
Ele usa para limitar o número de usuários retornados Top
Ele usa OrderBy para classificar a resposta

Opcional: adicionar seu próprio código

4 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 Graph Explorer ou código que você criou. Esta seção é opcional.

Atualizar o aplicativo

Abra ./GraphHelper.cs e adicione a seguinte função à classe GraphHelper .

// This function serves as a playground for testing Graph snippets
// or other code
public async static Task MakeGraphCallAsync()
{
    // INSERT YOUR CODE HERE
}

Substitua a função vazia MakeGraphCallAsync no Program.cs pelo seguinte.

async Task MakeGraphCallAsync()
{
    await GraphHelper.MakeGraphCallAsync();
}

Escolher uma API

Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar eventos . Você pode usar um dos exemplos na documentação da API ou personalizar um exemplo.

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 dão suporte somente a aplicativos ou contas pessoais da Microsoft, por exemplo.

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

Adicionar seu código

Copie seu código na MakeGraphCallAsync função em GraphHelper.cs. Se você estiver copiando um snippet da documentação ou do Graph Explorer, renomeie o GraphServiceClient para _appClient.

Compartilhar via

Criar aplicativos .NET com o Microsoft Graph e a autenticação somente aplicativo

Pré-requisitos

Registrar o aplicativo no portal

Registrar aplicativo para autenticação somente aplicativo

Criar um aplicativo de console .NET

Instalar dependências

Carregar configurações do aplicativo

Design do aplicativo

Adicionar autenticação somente aplicativo

Configurar o cliente graph para autenticação somente aplicativo

Testar o ClientSecretCredential

Listar usuários

Código explicado

Opcional: adicionar seu próprio código

Atualizar o aplicativo

Escolher uma API

Configurar as permissões

Adicionar seu código

Parabéns!

Exemplos do .NET