Aplicação Web que autentica utilizadores: Configuração de código

Aplica-se a: Locatários de trabalho Locatários externos (saiba mais)

Este artigo descreve como configurar o código para uma aplicação web que faz login de utilizadores.

Bibliotecas da Microsoft que suportam aplicações Web

As seguintes bibliotecas da Microsoft são usadas para proteger um aplicativo Web (e uma API Web):

Linguagem / estrutura	Projeto sobre GitHub	Pacote	Como obter começar	Iniciar sessão de utilizadores	Aceder a APIs Web	Geralmente disponível (GA) ou Prévizualização pública1
.NET	MSAL.NET	Microsoft.Identity.Client	—			Assembleia Geral
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	2	2	Assembleia Geral
ASP.NET Núcleo	Microsoft.Identity.Web	Microsoft.Identity.Web	Início rápido			Assembleia Geral
Java	MSAL4J	MSAL4J	Início rápido			Assembleia Geral
Primavera	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Tutoriais			Assembleia Geral
Node.js	Nó MSAL	msal-node	Início rápido			Assembleia Geral
Python	MSAL Python	MSAL	—			Assembleia Geral
Python	identidade	identidade	Início rápido			--

⁽¹⁾Os Termos de Licença Universal para Serviços Online aplicam-se às bibliotecas na versão de visualização pública.

⁽²⁾ A biblioteca Microsoft.IdentityModel apenas valida tokens - não pode solicitar ID ou tokens de acesso.

Selecione o separador que corresponde à plataforma em que está interessado:

ASP.NET Núcleo

Trechos de código neste artigo e os seguintes são extraídos do tutorial incremental do aplicativo Web ASP.NET Core, capítulo 1.

Consulte este tutorial para obter detalhes completos da implementação.

ASP.NET

Trechos de código neste artigo e os seguintes são extraídos do exemplo de aplicativo Web ASP.NET.

Talvez você queira consultar este exemplo para obter detalhes completos da implementação.

Java

Trechos de código deste artigo e dos seguintes são extraídos do exemplo aplicação Web Java chamando o Microsoft Graph no MSAL Java.

Talvez você queira consultar este exemplo para obter detalhes completos da implementação.

Node.js

Trechos de código neste artigo e os seguintes são extraídos do Node.js aplicativo Web assinando usuários no exemplo no nó MSAL.

Talvez você queira consultar este exemplo para obter detalhes completos da implementação.

Píton

Trechos de código neste artigo e nos seguintes são extraídos do exemplo de chamada do Microsoft Graph usando o pacote de identidade (um wrapper em torno do MSAL Python).

Talvez você queira consultar este exemplo para obter detalhes completos da implementação.

Arquivos de configuração

Os aplicativos Web que entram em usuários usando a plataforma de identidade da Microsoft são configurados por meio de arquivos de configuração. Esses arquivos devem especificar os seguintes valores:

• A instância de nuvem se você quiser que seu aplicativo seja executado em nuvens nacionais, por exemplo. As diferentes opções incluem:
  • https://login.microsoftonline.com/ para a nuvem pública do Azure
  • https://login.microsoftonline.us/ para o Azure US government
  • https://login.microsoftonline.de/ para Microsoft Entra Alemanha
  • https://login.partner.microsoftonline.cn/common para Microsoft Entra China operado pela 21Vianet
• O público no ID do locatário. As opções variam dependendo se seu aplicativo é locatário único ou multilocatário.
  • O GUID do inquilino obtido do portal do Azure para autenticar utilizadores na sua organização. Você também pode usar um nome de domínio.
  • organizations para iniciar sessão de utilizadores em qualquer conta de trabalho ou escolar
  • common para que os utilizadores iniciem sessão com qualquer conta laboral, escolar ou pessoal da Microsoft
  • consumers para iniciar sessão apenas em utilizadores com uma conta pessoal Microsoft
• A ID do cliente para seu aplicativo, conforme copiada do portal do Azure

Você também pode ver referências à autoridade, uma concatenação dos valores de instância e ID do locatário.

ASP.NET Núcleo

No ASP.NET Core, essas configurações estão localizadas no arquivo appsettings.json , na seção "Microsoft Entra ID".

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id here]",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath": "/signout-oidc"
  }
}

No ASP.NET Core, outro arquivo (properties\launchSettings.json) contém a URL (applicationUrl) e a porta TLS/SSL (sslPort) para seu aplicativo e vários perfis.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:3110/",
      "sslPort": 44321
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "webApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:3110/"
    }
  }
}

No portal do Azure, os URIs de redirecionamento registrados na página Autenticação do seu aplicativo precisam corresponder a essas URLs. Para os dois arquivos de configuração anteriores, eles seriam https://localhost:44321/signin-oidc. A razão é que applicationUrl é http://localhost:3110, mas sslPort é especificado (44321). CallbackPath é /signin-oidc, tal como definido em appsettings.json.

Da mesma forma, o URI de saída seria definido como https://localhost:44321/signout-oidc.

Nota

SignedOutCallbackPath deve ser definido como o portal ou a aplicação para evitar conflitos ao manipular o evento.

ASP.NET

Em ASP.NET, o aplicativo é configurado através do arquivo appsettings.json , linhas 12 a 15.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",
    "ClientId": "[Enter the Client Id here]",
  }
}

No portal do Azure, os URIs de resposta registrados na página Autenticação do seu aplicativo precisam corresponder a essas URLs. Ou seja, deveriam ser https://localhost:44326/.

Java

Em Java, a configuração está localizada no arquivo application.properties localizado em src/main/resources.

aad.clientId=Enter_the_Application_Id_here
aad.authority=https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/
aad.secretKey=Enter_the_Client_Secret_Here
aad.redirectUriSignin=http://localhost:8080/msal4jsample/secure/aad
aad.redirectUriGraph=http://localhost:8080/msal4jsample/graph/me

No portal do Azure, os URIs de resposta registrados na página Autenticação do seu aplicativo precisam corresponder às redirectUri instâncias definidas pelo aplicativo. Ou seja, devem ser http://localhost:8080/msal4jsample/secure/aad e http://localhost:8080/msal4jsample/graph/me.

Node.js

Aqui, os parâmetros de configuração residem em .env.dev como variáveis de ambiente:

CLOUD_INSTANCE="Enter_the_Cloud_Instance_Id_Here" # cloud instance string should end with a trailing slash
TENANT_ID="Enter_the_Tenant_Info_Here"
CLIENT_ID="Enter_the_Application_Id_Here"
CLIENT_SECRET="Enter_the_Client_Secret_Here"

REDIRECT_URI="http://localhost:3000/auth/redirect"
POST_LOGOUT_REDIRECT_URI="http://localhost:3000"

GRAPH_API_ENDPOINT="Enter_the_Graph_Endpoint_Here" # graph api endpoint string should end with a trailing slash

EXPRESS_SESSION_SECRET="Enter_the_Express_Session_Secret_Here"

Esses parâmetros são usados para criar um objeto de configuração no arquivo authConfig.js, que eventualmente será usado para inicializar o MSAL Node.

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

require('dotenv').config({ path: '.env.dev' });

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID, // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
        authority: process.env.CLOUD_INSTANCE + process.env.TENANT_ID, // Full directory URL, in the form of https://login.microsoftonline.com/<tenant>
        clientSecret: process.env.CLIENT_SECRET // Client secret generated from the app registration in Azure portal
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: 3,
        }
    }
}

const REDIRECT_URI = process.env.REDIRECT_URI;
const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI;
const GRAPH_ME_ENDPOINT = process.env.GRAPH_API_ENDPOINT + "v1.0/me";

module.exports = {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI,
    GRAPH_ME_ENDPOINT
};

No portal do Azure, os URIs de resposta registrados na página Autenticação do seu aplicativo precisam corresponder às instâncias de redirectUri que o aplicativo define (http://localhost:3000/auth/redirect).

Para simplificar, neste artigo, o segredo do cliente é armazenado no arquivo de configuração. Na aplicação de produção, considere o uso de um cofre de chaves ou de uma variável de ambiente. Uma opção ainda melhor é usar um certificado.

Píton

Os parâmetros de configuração são definidos em .env como variáveis de ambiente:

# Note: If you are using Azure App Service, go to your app's Configuration,
# and then set the following values into your app's "Application settings".

CLIENT_ID=<client id>
CLIENT_SECRET=<client secret>

# Expects a full authority URL such as "https://login.microsoftonline.com/TENANT_GUID"
# or "https://login.microsoftonline.com/contoso.onmicrosoft.com".
# Alternatively, leave it undefined if you are building a multi-tenant app in world-wide cloud
#AUTHORITY=<authority url>

Essas variáveis de ambiente são referenciadas em app_config.py:

import os

# Application (client) ID of app registration
CLIENT_ID = os.getenv("CLIENT_ID")
# Application's generated client secret: never check this into source control!
CLIENT_SECRET = os.getenv("CLIENT_SECRET")

# You can configure your authority via environment variable
# Defaults to a multi-tenant app in world-wide cloud
AUTHORITY = os.getenv("AUTHORITY", "https://login.microsoftonline.com/common")

REDIRECT_PATH = "/getAToken"  # Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

# You can find more Microsoft Graph API endpoints from Graph Explorer
# https://developer.microsoft.com/en-us/graph/graph-explorer
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  # This resource requires no admin consent

# You can find the proper permission names from this document
# https://docs.microsoft.com/en-us/graph/permissions-reference
SCOPE = ["User.ReadBasic.All"]

# Tells the Flask-session extension to store sessions in the filesystem
SESSION_TYPE = "filesystem"
# Using the file system will not work in most production systems,
# it's better to use a database-backed session store instead.

O arquivo .env nunca deve ser verificado no controle do código-fonte, pois contém segredos. O exemplo de início rápido inclui um arquivo .gitignore que impede o check-in do arquivo .env .

# Environments
.env

Código de inicialização

As diferenças de código de inicialização dependem da plataforma. Para ASP.NET Core e ASP.NET, o login de usuários é delegado ao middleware OpenID Connect. O modelo ASP.NET ou ASP.NET Core gera aplicativos Web para o ponto de extremidade do Azure AD v1.0. Alguma configuração é necessária para adaptá-los à plataforma de identidade da Microsoft.

ASP.NET Núcleo

Em aplicações web do ASP.NET Core (e APIs da web), a aplicação é protegida porque há um atributo Authorize nos controladores ou nas ações do controlador. Este atributo verifica se o usuário está autenticado. Antes do lançamento do .NET 6, a inicialização do código estava no arquivo Startup.cs . Novos projetos ASP.NET Core com .NET 6 não contêm mais um arquivo Startup.cs . Em seu lugar está o arquivo Program.cs . O restante deste tutorial pertence ao .NET 5 ou inferior.

Nota

Se quiser começar diretamente com os novos modelos ASP.NET Core para a plataforma de identidade Microsoft, que aproveitam o Microsoft.Identity.Web, você pode baixar um pacote NuGet de visualização contendo modelos de projeto para .NET 5.0. Em seguida, uma vez instalada, poderá diretamente instanciar aplicações web ASP.NET Core (MVC ou Blazor). Consulte Modelos de projeto de aplicativo Web Microsoft.Identity.Web para obter detalhes. Esta é a abordagem mais simples, pois fará todos os seguintes passos por si.

Se você preferir iniciar seu projeto com o projeto Web padrão atual do ASP.NET Core no Visual Studio ou usando dotnet new mvc --auth SingleOrg ou dotnet new webapp --auth SingleOrg, você verá um código como o seguinte:

 services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
         .AddAzureAD(options => Configuration.Bind("AzureAd", options));

Esse código usa o pacote NuGet herdado Microsoft.AspNetCore.Authentication.AzureAD.UI que é usado para criar um aplicativo Azure Ative Directory v1.0. Este artigo explica como criar um aplicativo Microsoft identity platform v2.0 que substitui esse código.

1. Adicione os pacotes NuGet Microsoft.Identity.Web e Microsoft.Identity.Web.UI ao seu projeto. Remova o Microsoft.AspNetCore.Authentication.AzureAD.UI pacote NuGet se ele estiver presente.

2. Atualize o código em ConfigureServices para que utilize os métodos AddMicrosoftIdentityWebApp e AddMicrosoftIdentityUI.

   public class Startup
   {
    ...
    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
     services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
            .AddMicrosoftIdentityWebApp(Configuration, "AzureAd");
   
     services.AddRazorPages().AddMvcOptions(options =>
     {
      var policy = new AuthorizationPolicyBuilder()
                    .RequireAuthenticatedUser()
                    .Build();
      options.Filters.Add(new AuthorizeFilter(policy));
     }).AddMicrosoftIdentityUI();
   

3. No método Configure em Startup.cs, habilite a autenticação com uma chamada para app.UseAuthentication(); e app.MapControllers();.

   // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   {
    // more code here
    app.UseAuthentication();
    app.UseAuthorization();
   
    app.MapRazorPages();
    app.MapControllers();
    // more code here
   }
   

Nesse código:

• O AddMicrosoftIdentityWebApp método de extensão é definido em Microsoft.Identity.Web, que;

  • Configura opções para ler o arquivo de configuração (aqui na seção "Microsoft Entra ID")
  • Configura as opções do OpenID Connect para que a autoridade seja a plataforma de identidade da Microsoft.
  • Valida o emissor do token.
  • Garante que as declarações correspondentes ao nome sejam mapeadas a partir da preferred_username declaração no token de ID.

• Além do objeto de configuração, você pode especificar o nome da seção de configuração ao chamar AddMicrosoftIdentityWebApp. Por padrão, é AzureAd.

• AddMicrosoftIdentityWebApp tem outros parâmetros para cenários avançados. Por exemplo, rastrear eventos de middleware OpenID Connect pode ajudá-lo a solucionar problemas do seu aplicativo Web se a autenticação não funcionar. Definir o parâmetro subscribeToOpenIdConnectMiddlewareDiagnosticsEvents opcional como true mostrará como as informações são processadas pelo conjunto de middleware ASP.NET Core à medida que progridem da resposta HTTP para a identidade do usuário no HttpContext.User.

• O AddMicrosoftIdentityUI método de extensão é definido em Microsoft.Identity.Web.UI. Ele fornece um controlador padrão para lidar com entrada e saída.

Para obter mais informações sobre como o Microsoft.Identity.Web permite que você crie aplicativos Web, consulte Aplicativos Web em microsoft-identity-web.

ASP.NET

O código relacionado à autenticação em um aplicativo Web ASP.NET e APIs da Web está localizado no arquivo App_Start/Startup.Auth.cs .

 public void ConfigureAuth(IAppBuilder app)
 {
  app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

  OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
  factory.Build();
  app.AddMicrosoftIdentityWebApi(factory);
 }

Java

O exemplo Java usa a estrutura Spring. O aplicativo é protegido porque você implementa um filtro, que interceta cada resposta HTTP. No início rápido para aplicativos Web Java, esse filtro está AuthFilter em src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

O filtro processa o fluxo de código de autorização do OAuth 2.0 e verifica se o usuário está autenticado (isAuthenticated() método). Se o utilizador não estiver autenticado, calcula a URL dos pontos finais de autorização do Microsoft Entra e redireciona o navegador para este URI.

Quando a resposta chega, contendo o código de autorização, ela adquire o token usando MSAL Java. Quando ele finalmente recebe o token do ponto de extremidade do token (no URI de redirecionamento), o usuário está conectado.

Para obter detalhes, consulte o doFilter() método em AuthFilter.java.

Nota

O código do doFilter() é escrito em uma ordem ligeiramente diferente, mas o fluxo é o descrito.

Para obter detalhes sobre o fluxo de código de autorização que esse método dispara, consulte a plataforma de identidade da Microsoft e o fluxo de código de autorização do OAuth 2.0.

Node.js

O exemplo de Node usa o framework Express. MSAL é inicializado no manipulador de rota de autenticação :

var express = require('express');

const authProvider = require('../auth/AuthProvider');
const { REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

const router = express.Router();

router.get('/signin', authProvider.login({
    scopes: [],
    redirectUri: REDIRECT_URI,
    successRedirect: '/'

Píton

O exemplo Python é construído com o framework Flask, embora outros frameworks como o Django também possam ser usados. O aplicativo Flask é inicializado com a configuração do aplicativo na parte superior do app.py:

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

Em seguida, o código constrói um auth objeto usando o pacote de identidade.

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

Próximo passo

ASP.NET Núcleo

Inicie e termine sessão.

ASP.NET

Inicie e termine sessão.

Java

Inicie e termine sessão.

Node.js

Inicie e termine sessão.

Píton

Inicie e termine sessão.