Início Rápido: Adquirir um token e chamar a API do Microsoft Graph de um aplicativo de console usando a identidade do aplicativoQuickstart: Acquire a token and call Microsoft Graph API from a console app using app's identity

Neste início rápido, você aprenderá a escrever um aplicativo .NET Core que pode obter um token de acesso usando a identidade do aplicativo e, em seguida, chamar a API do Microsoft Graph para exibir uma lista de usuários no diretório.In this quickstart, you'll learn how to write a .NET Core application that can get an access token using the app's own identity and then call the Microsoft Graph API to display a list of users in the directory. Esse cenário é útil para situações em que o trabalho autônomo e sem periféricos, ou um serviço de janela, precisa ser executado com uma identidade do aplicativo em vez de uma identidade de usuário.This scenario is useful for situations where headless, unattended job or a windows service needs to run with an application identity, instead of a user's identity.

Mostra como o aplicativo de exemplo gerado por este início rápido funciona

Pré-requisitosPrerequisites

Este início rápido requer o .NET Core 2.2.This quickstart requires .NET Core 2.2.

Registrar e baixar o aplicativo de início rápidoRegister and download your quickstart app

Você tem duas opções para iniciar o aplicativo de início rápido:You have two options to start your quickstart application:

Opção 1: Registrar e configurar o aplicativo automaticamente e, em seguida, baixar seu exemplo de códigoOption 1: Register and auto configure your app and then download your code sample

  1. Acesse o novo painel do portal do Azure – Registros de aplicativo.Go to the new Azure portal - App registrations pane.
  2. Insira um nome para seu aplicativo e selecione Registrar.Enter a name for your application and select Register.
  3. Siga as instruções para baixar e configurar automaticamente o novo aplicativo com apenas um clique.Follow the instructions to download and automatically configure your new application with just one click.

Opção 2: Registrar e configurar manualmente o aplicativo e o exemplo de códigoOption 2: Register and manually configure your application and code sample

Etapa 1: Registre seu aplicativoStep 1: Register your application

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução manualmente, siga estas etapas:To register your application and add the app's registration information to your solution manually, follow these steps:

  1. Entre no portal do Azure usando uma conta corporativa ou de estudante ou uma conta pessoal da Microsoft.Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.
  2. Se sua conta fornecer acesso a mais de um locatário, selecione sua conta no canto superior direito e defina sua sessão do portal para o locatário desejado do Azure AD.If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the desired Azure AD tenant.
  3. Navegue até a página Registros de aplicativo da plataforma de identidade da Microsoft para desenvolvedores.Navigate to the Microsoft identity platform for developers App registrations page.
  4. Selecione Novo registro.Select New registration.
  5. Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo.When the Register an application page appears, enter your application's registration information.
  6. Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo, por exemplo, Daemon-console, e selecione Registrar para criar o aplicativo.In the Name section, enter a meaningful application name that will be displayed to users of the app, for example Daemon-console, then select Register to create the application.
  7. Após o registro, selecione o menu Certificados e segredos.Once registered, select the Certificates & secrets menu.
  8. Em Segredos do cliente, selecione + Novo segredo do cliente.Under Client secrets, select + New client secret. Dê a ele um nome e selecione Adicionar.Give it a name and select Add. Copie o segredo em um local seguro.Copy the secret on a safe location. Você precisará dele em seu código.You will need it to use in your code.
  9. Agora, selecione o menu Permissões de API, selecione o botão + Adicionar uma permissão e selecione Microsoft Graph.Now, select the API Permissions menu, select + Add a permission button, select Microsoft Graph.
  10. Selecione Permissões de aplicativo.Select Application permissions.
  11. No nó Usuário, selecione User.Read.All e selecione Adicionar permissõesUnder User node, select User.Read.All, then select Add permissions

Baixar e configurar seu aplicativo de início rápidoDownload and configure your quickstart app

Etapa 1: Configurar seu aplicativo no portal do AzureStep 1: Configure your application in Azure portal

Para o exemplo de código deste início rápido funcionar, você precisará criar um segredo do cliente e adicionar a permissão de aplicativo User.Read.All da API do Graph.For the code sample for this quickstart to work, you need to create a client secret, and add Graph API's User.Read.All application permission.

Já configurado Seu aplicativo já está configurado com esses atributos.Already configured Your application is configured with these attributes.

Etapa 2: Baixar seu projeto do Visual StudioStep 2: Download your Visual Studio project

Baixar o projeto do Visual StudioDownload the Visual Studio project

Etapa 3: Configurar o projeto do Visual StudioStep 3: Configure your Visual Studio project

  1. Extraia o arquivo zip para uma pasta local mais próxima da raiz do disco, por exemplo, C:\Azure-Samples.Extract the zip file to a local folder close to the root of the disk, for example, C:\Azure-Samples.

  2. Abra a solução no Visual Studio – daemon-console.sln (opcional).Open the solution in Visual Studio - daemon-console.sln (optional).

  3. Edite appsettings.json e substitua os valores dos campos ClientId, Tenant e ClientSecret pelo seguinte:Edit appsettings.json and replace the values of the fields ClientId, Tenant and ClientSecret with the following:

    "Tenant": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "ClientSecret": "Enter_the_Client_Secret_Here"
    

    Observação

    Este guia de início rápido oferece suporte a Enter_the_Supported_Account_Info_Here.This quickstart supports Enter_the_Supported_Account_Info_Here.

    Em que:Where:

    • Enter_the_Application_Id_Here - é a ID do aplicativo (cliente) que você registrou.Enter_the_Application_Id_Here - is the Application (client) ID for the application you registered.
    • Enter_the_Tenant_Id_Here – substitua esse valor pela ID do locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com)Enter_the_Tenant_Id_Here - replace this value with the Tenant Id or Tenant name (for example, contoso.microsoft.com)
    • Enter_the_Client_Secret_Here – substitua esse valor pelo segredo do cliente criado na etapa 1.Enter_the_Client_Secret_Here - replace this value with the client secret created on step 1.

    Dica

    Para encontrar os valores de ID do aplicativo (cliente) , ID de diretório (locatário) , acesse a página Visão Geral do aplicativo no portal do Azure.To find the values of Application (client) ID, Directory (tenant) ID, go to the app's Overview page in the Azure portal. Para gerar uma nova chave, acesse a página Certificados e segredos.To generate a new key, go to Certificates & secrets page.

Se você tentar executar o aplicativo neste ponto, receberá o erro HTTP 403 – Proibido: Insufficient privileges to complete the operation.If you try to run the application at this point, you'll receive HTTP 403 - Forbidden error: Insufficient privileges to complete the operation. Isso acontece porque qualquer permissão somente do aplicativo exige o consentimento do administrador, ou seja, um administrador global do seu diretório precisa dar consentimento ao seu aplicativo.This happens because any app-only permission requires Admin consent, which means that a global administrator of your directory must give consent to your application. Selecione uma das opções abaixo, dependendo de sua função:Select one of the options below depending on your role:

Administrator de locatário globalGlobal tenant administrator

Se você for um administrador de locatário global, acesse a página Permissões de API no Registro de Aplicativo do Portal do Azure (versão prévia) e selecione Dar consentimento de administrador para {nome do locatário} (em que {nome do locatário} é o nome do seu diretório).If you are a global tenant administrator, go to API Permissions page in the Azure Portal's Application Registration (Preview) and select Grant admin consent for {Tenant Name} (Where {Tenant Name} is the name of your directory).

Se você for um administrador global, acesse a página Permissões de API, selecione Dar consentimento de administrador para Insira_o_nome_do_locatário_aquiIf you are a global administrator, go to API Permissions page select Grant admin consent for Enter_the_Tenant_Name_Here

Usuário padrãoStandard user

Se você for usuário padrão do seu locatário, precisará pedir que o administrador global dê consentimento do administrador para seu aplicativo.If you're a standard user of your tenant, then you need to ask a global administrator to grant admin consent for your application. Para fazer isso, dê a seguinte URL ao administrador:To do this, give the following URL to your administrator:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

Em que:Where:

  • Enter_the_Tenant_Id_Here – substitua esse valor pela ID do locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com)Enter_the_Tenant_Id_Here - replace this value with the Tenant Id or Tenant name (for example, contoso.microsoft.com)
  • Enter_the_Application_Id_Here - é a ID do aplicativo (cliente) que você registrou.Enter_the_Application_Id_Here - is the Application (client) ID for the application you registered.

Observação

Você pode ver o erro 'AADSTS50011: nenhum endereço de resposta está registrado para o aplicativo' após dar o consentimento ao aplicativo usando a URL anterior.You may see the error 'AADSTS50011: No reply address is registered for the application' after granting consent to the app using the preceding URL. Isso ocorre porque esse aplicativo e a URL não têm um URI de redirecionamento; ignore o erro.This happen because this application and the URL do not have a redirect URI - please ignore the error.

Etapa 5: Executar o aplicativoStep 5: Run the application

Se você estiver usando o Visual Studio, pressione F5 para executar o aplicativo. Caso contrário, execute o aplicativo por meio do prompt de comando ou console:If you're using Visual Studio, press F5 to run the application, otherwise, run the application via command prompt or console:

cd {ProjectFolder}\daemon-console
dotnet run

Em que:Where:

  • {ProjectFolder} é a pasta onde você extraiu o arquivo zip.{ProjectFolder} is the folder where you extracted the zip file. Exemplo C:\Azure-Samples\active-directory-dotnetcore-daemon-v2Example C:\Azure-Samples\active-directory-dotnetcore-daemon-v2

Você deverá ver uma lista de usuários em seu diretório do Azure AD como resultado.You should see a list of users in your Azure AD directory as result.

Importante

Este aplicativo de início rápido usa um segredo do cliente para se identificar como cliente confidencial.This quickstart application uses a client secret to identify itself as confidential client. Como o segredo do cliente é adicionado como texto sem formatação a seus arquivos de projeto, por motivos de segurança, é recomendável que você use um certificado, em vez de um segredo do cliente, antes de considerar o aplicativo como aplicativo de produção.Because the client secret is added as a plain-text to your project files, for security reasons, it is recommended that you use a certificate instead of a client secret before considering the application as production application. Para obter mais informações sobre como usar um certificado, confira estas instruções no repositório do GitHub para este exemplo.For more information on how to use a certificate, see these instructions in the GitHub repository for this sample.

Mais informaçõesMore information

MSAL.NETMSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca usada para conectar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft.MSAL (Microsoft.Identity.Client) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. Conforme descrito, este início rápido solicita tokens usando a identidade do próprio aplicativo, em vez de permissões delegadas.As described, this quickstart requests tokens by using the application own identity instead of delegated permissions. O fluxo de autenticação usado nesse caso é conhecido como fluxo OAuth de credenciais do cliente .The authentication flow used in this case is known as client credentials oauth flow. Para saber mais sobre como usar MSAL.NET com fluxo de credenciais de cliente, confira este artigo.For more information on how to use MSAL.NET with client credentials flow, see this article.

Você pode instalar o MSAL.NET executando o comando abaixo no Console do Gerenciador de Pacotes do Visual Studio:You can install MSAL.NET by running the following command in Visual Studio's Package Manager Console:

Install-Package Microsoft.Identity.Client -Pre

Como alternativa, se você não estiver usando o Visual Studio, poderá executar o seguinte comando para adicionar MSAL ao seu projeto:Alternatively, if you are not using Visual Studio, you can run the following command to add MSAL to your project:

dotnet add package Microsoft.Identity.Client

Inicialização da MSALMSAL initialization

Você pode adicionar a referência da MSAL adicionando o seguinte código:You can add the reference for MSAL by adding the following code:

using Microsoft.Identity.Client;

Em seguida, inicialize a MSAL usando o seguinte código:Then, initialize MSAL using the following code:

IConfidentialClientApplication app;
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithClientSecret(config.ClientSecret)
                                          .WithAuthority(new Uri(config.Authority))
                                          .Build();
);
Em que:Where:
config.ClientSecret É o segredo do cliente criado para o aplicativo no portal do Azure.Is the client secret created for the application in Azure Portal.
config.ClientId É a ID do aplicativo (cliente) relativa ao aplicativo registrado no portal do Azure.Is the Application (client) ID for the application registered in the Azure portal. Você pode encontrar esse valor na página Visão Geral do aplicativo no portal do Azure.You can find this value in the app's Overview page in the Azure portal.
config.Authority (Opcional) O ponto de extremidade do STS para o usuário autenticar.(Optional) The STS endpoint for user to authenticate. Normalmente, https://login.microsoftonline.com/{tenant} para a nuvem pública, em que {tenant} é o nome do seu locatário ou ID do seu locatário.Usually https://login.microsoftonline.com/{tenant} for public cloud, where {tenant} is the name of your tenant or your tenant Id.

Para saber mais, confira a documentação de referência do ConfidentialClientApplicationFor more information, please see the reference documentation for ConfidentialClientApplication

Solicitando tokensRequesting tokens

Para solicitar um token usando a identidade do aplicativo, use o método AcquireTokenForClient:To request a token using app's identity, use AcquireTokenForClient method:

result = await app.AcquireTokenForClient(scopes)
                  .ExecuteAsync();
Em que:Where:
scopes Contém os escopos solicitados.Contains the scopes requested. Para clientes confidenciais, ele deve usar um formato semelhante a {Application ID URI}/.default para indicar que os escopos solicitados são os estaticamente definidos no objeto de aplicativo definido no portal do Azure (no caso do Microsoft Graph, {Application ID URI} aponta para https://graph.microsoft.com).For confidential clients, this should use the format similar to {Application ID URI}/.default to indicate that the scopes being requested are the ones statically defined in the app object set in the Azure Portal (for Microsoft Graph, {Application ID URI} points to https://graph.microsoft.com). Para APIs da Web personalizadas, o {Application ID URI} é definido na seção Expor uma API no Registro de Aplicativo do portal do Azure (versão prévia).For custom Web APIs, {Application ID URI} is defined under Expose an API section in Azure Portal's Application Registration (Preview).

Para saber mais, confira a documentação de referência do AcquireTokenForClientFor more information, please see the reference documentation for AcquireTokenForClient

Ajuda e suporteHelp and support

Se você precisar de Ajuda, quiser relatar um problema ou aprender mais sobre as opções de suporte, consulte o seguinte artigo:If you need help, want to report an issue, or want to learn more about your support options, see the following article:

Próximas etapasNext steps

Saiba mais sobre permissões e consentimento:Learn more about permissions and consent:

Para saber mais sobre o fluxo de autenticação para este cenário, consulte o fluxo de credenciais de cliente Oauth 2.0:To know more about the auth flow for this scenario, see the Oauth 2.0 client credentials flow:

Ajude-nos a melhorar a plataforma de identidade da Microsoft.Help us improve the Microsoft identity platform. Deixe sua opinião respondendo a uma breve pesquisa de duas perguntas.Tell us what you think by completing a short two-question survey.