Aplicativo de área de trabalho que chama APIs da Web: configuração de código

Aplica-se a: Inquilinos da força de trabalho (saiba mais)

Este artigo contém instruções para ajudá-lo a configurar o código com as coordenadas do aplicativo.

Pré-requisitos

• Registre um novo aplicativo no centro de administração do Microsoft Entra, configurado para Contas somente neste diretório organizacional. Consulte Registar uma candidatura para obter mais detalhes. Registre os seguintes valores na página Visão geral do aplicativo para uso posterior:
  • ID da aplicação (cliente)
  • ID do diretório (inquilino)

Adicionar um URI de redirecionamento de plataforma

Para especificar o tipo de aplicativo para o registro do aplicativo, siga estas etapas:

1. Em Gerir, selecione Autenticação>Adicionar uma plataforma>Aplicações móveis e de ambiente de trabalho
2. Dependendo do método de autenticação que estiver a utilizar, escolha uma das seguintes opções:
   • Para aplicativos que usam navegadores incorporados, use o valor exato: https://login.microsoftonline.com/common/oauth2/nativeclient
   • Para aplicativos que usam navegadores de sistema, use o valor exato: http://localhost
   • Objective-C ou aplicativos Swift para macOS: msauth.<your.app.bundle.id>://auth.
   • Aplicações Node.js do Electron: msal{Your_Application/Client_Id}://auth

Observação

Para aplicativos do Web Authentication Manager (WAM), nenhum URI de redirecionamento é necessário no MSAL.

Habilitar o fluxo público de clientes

Para distinguir o fluxo de código de dispositivo, a autenticação integrada do Windows e um nome de usuário e uma senha de um aplicativo cliente confidencial usando um fluxo de credenciais de cliente usado em aplicativos daemon, nenhum dos quais requer um URI de redirecionamento, configure-o como um aplicativo cliente público. Para conseguir esta configuração

Para identificar seu aplicativo como um cliente público, siga estas etapas:

1. Em Gerir, selecione Autenticação.

2. Em Configurações avançadas, para Permitir fluxos de clientes públicos, selecione Sim.

3. Selecione Guardar para guardar as alterações.

Bibliotecas da Microsoft que suportam aplicações de ambiente de trabalho

As seguintes bibliotecas da Microsoft suportam aplicações de ambiente de trabalho:

Linguagem / estrutura	Projeto em GitHub	Pacote	Como obter começar	Iniciar sessão de utilizadores	Aceder a APIs Web	Geralmente disponível (GA) ou Pré-visualização pública1
Elétron	MSAL Node.js	msal-node	—	A biblioteca pode solicitar tokens de identificação para o início de sessão do usuário.		Pré-visualização pública
Java	MSAL4J	MSAL4J	—	A biblioteca pode solicitar tokens de identificação para o início de sessão do usuário.		disponibilidade geral
macOS (Swift/OBJ-C)	MSAL para iOS e macOS	MSAL	Tutoriais	A biblioteca pode solicitar tokens de identificação para o início de sessão do usuário.		disponibilidade geral
UWP	MSAL.NET	Microsoft.Identity.Client	Tutoriais	A biblioteca pode solicitar tokens de identificação para o início de sessão do usuário.		disponibilidade geral
WPF	MSAL.NET	Microsoft.Identity.Client	Tutoriais	A biblioteca pode solicitar tokens de identificação para o início de sessão do usuário.		disponibilidade geral

¹Os Termos de Licença Universal para Serviços Online aplicam-se às bibliotecas em Pré-visualização Pública.

Aplicação cliente pública

Do ponto de vista do código, as aplicações de ambiente de trabalho são aplicações cliente públicas. A configuração será um pouco diferente dependendo se você usa autenticação interativa ou não.

.NET

Você precisará criar e manipular MSAL.NET IPublicClientApplication.

Exclusivamente por código

O código a seguir instancia uma aplicação cliente pública e efetua login dos utilizadores na nuvem pública do Microsoft Azure com uma conta de trabalho ou escolar, ou uma conta pessoal da Microsoft.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

Se você pretende usar autenticação interativa ou fluxo de código de dispositivo, como visto anteriormente, use o .WithRedirectUri modificador.

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithDefaultRedirectUri()
        .Build();

Utilizar os ficheiros de configuração

O código a seguir instancia um aplicativo cliente público a partir de um objeto de configuração, que pode ser preenchido programaticamente ou lido a partir de um arquivo de configuração.

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
        .WithDefaultRedirectUri()
        .Build();

Configuração mais elaborada

Você pode elaborar a construção do aplicativo adicionando vários modificadores. Por exemplo, se você quiser que seu aplicativo seja um aplicativo multilocatário em uma nuvem nacional, como o governo dos EUA mostrado aqui, você pode escrever:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithDefaultRedirectUri()
        .WithAadAuthority(AzureCloudInstance.AzureUsGovernment,
                         AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

MSAL.NET também contém um modificador para os Serviços de Federação do Active Directory 2019:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

Finalmente, se você quiser adquirir tokens para um locatário B2C do Azure Ative Directory (Azure AD), especifique seu locatário conforme mostrado no seguinte trecho de código:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

Mais informações

Para saber mais sobre como configurar um aplicativo de área de trabalho MSAL.NET:

• Para obter uma lista de todos os modificadores disponíveis no PublicClientApplicationBuilder, consulte a documentação de referência PublicClientApplicationBuilder.
• Para obter uma descrição de todas as opções expostas no PublicClientApplicationOptions, consulte PublicClientApplicationOptions na documentação de referência.

Exemplo completo com opções de configuração

Imagine um aplicativo de console .NET que tenha o seguinte appsettings.json arquivo de configuração:

{
  "Authentication": {
    "AzureCloudInstance": "AzurePublic",
    "AadAuthorityAudience": "AzureAdMultipleOrgs",
    "ClientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
  },

  "WebAPI": {
    "MicrosoftGraphBaseEndpoint": "https://graph.microsoft.com"
  }
}

Você tem pouco código para ler neste ficheiro, utilizando o framework de configuração fornecido pela .NET.

public class SampleConfiguration
{
 /// <summary>
 /// Authentication options
 /// </summary>
 public PublicClientApplicationOptions PublicClientApplicationOptions { get; set; }

 /// <summary>
 /// Base URL for Microsoft Graph (it varies depending on whether the application runs
 /// in Microsoft Azure public clouds or national or sovereign clouds)
 /// </summary>
 public string MicrosoftGraphBaseEndpoint { get; set; }

 /// <summary>
 /// Reads the configuration from a JSON file
 /// </summary>
 /// <param name="path">Path to the configuration json file</param>
 /// <returns>SampleConfiguration as read from the json file</returns>
 public static SampleConfiguration ReadFromJsonFile(string path)
 {
  // .NET configuration
  IConfigurationRoot Configuration;
  var builder = new ConfigurationBuilder()
                    .SetBasePath(Directory.GetCurrentDirectory())
                    .AddJsonFile(path);
  Configuration = builder.Build();

  // Read the auth and graph endpoint configuration
  SampleConfiguration config = new SampleConfiguration()
  {
   PublicClientApplicationOptions = new PublicClientApplicationOptions()
  };
  Configuration.Bind("Authentication", config.PublicClientApplicationOptions);
  config.MicrosoftGraphBaseEndpoint =
  Configuration.GetValue<string>("WebAPI:MicrosoftGraphBaseEndpoint");
  return config;
 }
}

Agora, para criar seu aplicativo, escreva o seguinte código:

SampleConfiguration config = SampleConfiguration.ReadFromJsonFile("appsettings.json");
var app = PublicClientApplicationBuilder.CreateWithApplicationOptions(config.PublicClientApplicationOptions)
           .WithDefaultRedirectUri()
           .Build();

Antes da chamada para o .Build() método, você pode substituir sua configuração por chamadas para .WithXXX métodos, como visto anteriormente.

Java

Aqui está a classe usada em exemplos de desenvolvimento Java MSAL para configurar os exemplos: TestData.

PublicClientApplication pca = PublicClientApplication.builder(CLIENT_ID)
        .authority(AUTHORITY)
        .build();

MacOS

O código a seguir instancia uma aplicação cliente pública e efetua login dos utilizadores na nuvem pública do Microsoft Azure com uma conta de trabalho ou escolar, ou uma conta pessoal da Microsoft.

Configuração rápida

Objectivo-C:

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

Rápido

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

Configuração mais elaborada

Você pode elaborar a construção do aplicativo adicionando vários modificadores. Por exemplo, se você quiser que seu aplicativo seja um aplicativo multilocatário em uma nuvem nacional, como o governo dos EUA mostrado aqui, você pode escrever:

Objectivo-C:

MSALAADAuthority *aadAuthority =
                [[MSALAADAuthority alloc] initWithCloudInstance:MSALAzureUsGovernmentCloudInstance
                                                   audienceType:MSALAzureADMultipleOrgsAudience
                                                      rawTenant:nil
                                                          error:nil];

MSALPublicClientApplicationConfig *config =
                [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"
                                                                redirectUri:@"<your-redirect-uri-here>"
                                                                  authority:aadAuthority];

NSError *applicationError = nil;
MSALPublicClientApplication *application =
                [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&applicationError];

Rápido

let authority = try? MSALAADAuthority(cloudInstance: .usGovernmentCloudInstance, audienceType: .azureADMultipleOrgsAudience, rawTenant: nil)

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>", redirectUri: "<your-redirect-uri-here>", authority: authority)
if let application = try? MSALPublicClientApplication(configuration: config) { /* Use application */}

Node.js

Os parâmetros de configuração podem ser carregados de várias fontes, como um arquivo JavaScript ou de variáveis de ambiente. Abaixo, um arquivo de authConfig.js é usado.

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

const { LogLevel } = require("@azure/msal-node");

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL.js configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const AAD_ENDPOINT_HOST = "Enter_the_Cloud_Instance_Id_Here"; // include the trailing slash

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: `${AAD_ENDPOINT_HOST}Enter_the_Tenant_Info_Here`,
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: LogLevel.Verbose,
        },
    },
};

/**
 * Add here the endpoints and scopes when obtaining an access token for protected web APIs. For more information, see:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/resources-and-scopes.md
 */
const GRAPH_ENDPOINT_HOST = "Enter_the_Graph_Endpoint_Here"; // include the trailing slash

const protectedResources = {
    graphMe: {
        endpoint: `${GRAPH_ENDPOINT_HOST}v1.0/me`,
        scopes: ["User.Read"],
    }
};


module.exports = {
    msalConfig: msalConfig,
    protectedResources: protectedResources,
};

Importe o objeto de configuração de authConfig.js arquivo. O nó MSAL pode ser inicializado minimamente da seguinte forma. Consulte as opções de configuração disponíveis.

const { PublicClientApplication } = require('@azure/msal-node');
const { msalConfig } = require('./authConfig')

/**
* Initialize a public client application. For more information, visit:
* https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-public-client-application.md
*/
clientApplication = new PublicClientApplication(msalConfig);

Píton

config = json.load(open(sys.argv[1]))

app = msal.PublicClientApplication(
    config["client_id"], authority=config["authority"],
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
    )

Próximos passos

Passe para o próximo artigo neste cenário, Adquirir um token para a aplicação de ambiente de trabalho.