Aplicativo Web que registra usuários: Configuração de código

Artigo
08/06/2024

Este artigo descreve como configurar o código para um aplicativo Web que registra usuários.

Bibliotecas Microsoft com suporte a aplicativos Web

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

Idioma / estrutura	Projeto em GitHub	Pacote	Introdução iniciado	Conectar usuários	Acessar APIs da Web	Geralmente disponíveis (GA) ou Visualização pública¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Início rápido			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Início rápido			GA
Java	MSAL4J	msal4j	Início rápido			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Tutorial			GA
Node.js	Nó MSAL	msal-node	Início rápido			GA
Python	MSAL Python	msal				GA
Python	identidade	identidade	Início rápido			--

⁽¹⁾ Os Termos de Licença Universal para Serviços Online se aplicam a bibliotecas em Visualização Pública.

⁽²⁾ Somente a biblioteca Microsoft.IdentityModelvalida os tokens; ela não pode solicitar ID ou acessar os tokens.

Selecione a guia que corresponde à plataforma em que você está interessado:

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

Se desejar, consulte esse tutorial para obter detalhes completos sobre a implementação.

Arquivos de configuração

Os aplicativos Web que registram 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 nuvem pública Azure
- https://login.microsoftonline.us/ para governo dos EUA do Azure
- https://login.microsoftonline.de/ para o Microsoft Entra Alemanha
- https://login.partner.microsoftonline.cn/common para o Microsoft Entra China operado pela 21Vianet
O público na ID do locatário. As opções variam dependendo de seu aplicativo ser locatário único ou multilocatário.
- O GUID de locatário obtido do portal do Azure para conectar usuários em sua organização. Você também pode usar um nome de domínio.
- organizations para conectar usuários em qualquer conta corporativa ou de estudante
- common para conectar usuários com qualquer conta corporativa ou de estudante ou Microsoft conta pessoal
- consumers para conectar usuários com apenas uma conta pessoal Microsoft
A ID do cliente para seu aplicativo, conforme copiado do portal do Azure

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

No ASP.NET Core, essas configurações estão 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"
  }
}

Em ASP.NET Core, outro arquivo (properties\launchSettings.jsem) 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 que você registra na página de autenticação para seu aplicativo precisam corresponder a essas URLs. Para os dois arquivos de configuração anteriores, eles seriam https://localhost:44321/signin-oidc. O motivo é que applicationUrl é http://localhost:3110, mas sslPort é especificado (44321). CallbackPath é /signin-oidc, conforme definido em appsettings.json.

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

Observação

SignedOutCallbackPath deve ser definido como portal ou aplicativo para evitar conflitos ao manipular o evento.

Em ASP.NET, o aplicativo é configurado por meio 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 que você registra na página de autenticação para seu aplicativo precisam corresponder a essas URLs. Ou seja, eles devem ser https://localhost:44326/.

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 que você registra na página de autenticação para seu aplicativo precisam corresponder às redirectUriinstâncias definidas pelo aplicativo. Ou seja, eles devem ser http://localhost:8080/msal4jsample/secure/aad e http://localhost:8080/msal4jsample/graph/me.

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 será usado para inicializar o nó da MSAL:

/*
 * 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 que você registra na página de autenticação para 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. No aplicativo de produção, considere usar um cofre de chaves ou uma variável de ambiente. Uma opção ainda melhor é usar um certificado.

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. A amostra de início rápido inclui um arquivo .gitignore que impede que o arquivo .env seja verificado.

# Environments
.env

Código de inicialização

As diferenças no código de inicialização dependem da plataforma. Para ASP.NET Core e ASP.NET, o registro de usuários é delegados para o middleware OpenID Connect. O modelo ASP.NET ou ASP.NET Core gera aplicativos Web para o ponto de extremidade do Azure AD v1.0. Algumas configurações são necessárias para adaptá-los à plataforma Microsoft Identity.

Aplicativo Web em ASP.NET Core (e APIs Web), o aplicativo é protegido porque você tem um Authorize atributo nos controladores ou nas ações do controlador. Esse atributo verifica se o usuário está autenticado. Antes do lançamento do .NET 6, a inicialização do código ficava no arquivo Startup.cs. Novos projetos do ASP.NET Core com o .NET 6 não mais contêm um arquivo Startup.cs. O arquivo Program.cs está tomando seu lugar. O restante deste tutorial pertence ao .NET 5 ou inferior.

Observação

Se você quiser começar diretamente com os novos modelos ASP.NET Core para plataforma de identidade da Microsoft, que utilizam o Microsoft.Identity.Web, você pode baixar um pacote NuGet de visualização contendo modelos de projeto para .NET 5.0. Depois, uma vez instalado, você pode instanciar diretamente aplicativo Web em ASP.NET Core (MVC ou Blazor). Consulte modelos de aplicativo Web Microsoft.Identity.Web para mais detalhes. Essa é a abordagem mais simples, pois fará todas as etapas abaixo para você.

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

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

Esse código usa o pacote NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI herdado que é usado para criar um aplicativo do Azure Active Directory v1.0. Este artigo explica como criar um aplicativo v2.0 da plataforma de identidade da Microsoft que substitui esse código.

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

Atualize o código no ConfigureServices para que ele use 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();

No Configure método 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
}

Neste código:

O método de extensão AddMicrosoftIdentityWebApp é 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, ele é AzureAd.
AddMicrosoftIdentityWebApp tem outros parâmetros para cenários avançados. Por exemplo, rastrear eventos de middleware do OpenID Connect pode ajudá-lo a solucionar problemas de seu aplicativo Web se a autenticação não funcionar. Definir o parâmetro opcional subscribeToOpenIdConnectMiddlewareDiagnosticsEvents para true mostrará como as informações são processadas pelo conjunto de middleware ASP.NET Core à medida que ele progride da resposta HTTP para a identidade do usuário em HttpContext.User.
O AddMicrosoftIdentityUI método de extensão é definido em Microsoft.Identity.Web.UI. Ele fornece um controlador padrão para manipular a entrada e saída.

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

O código relacionado à autenticação em um aplicativo Web em ASP.NET e APIs 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);
 }

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

O filtro processa o fluxo do código de autorização OAuth 2.0 e verifica se o usuário é autenticado (isAuthenticated() método). Se o usuário não estiver autenticado, ele calculará a URL dos pontos de extremidade de autorização do Microsoft Entra e redirecionará o navegador para esse 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 é conectado.

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

Observação

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

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

Amostra de nó da estrutura Expresso. A MSAL é inicializada no manipulador de rotas 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: '/'

A amostra do Python é compilada com a estrutura Flask, embora outras estruturas como o Django também possam ser usadas. 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óxima etapa

Entrar e sair.

Compartilhar via

Aplicativo Web que registra usuários: Configuração de código

Bibliotecas Microsoft com suporte a aplicativos Web

Arquivos de configuração

Código de inicialização

Próxima etapa

Comentários

Recursos adicionais