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

Artigo
08/01/2024

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

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 / framework	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ública 1}
.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-nó	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 aplicam-se às bibliotecas na Pré-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:

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.

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
A audiência no ID do locatário. As opções variam dependendo se seu aplicativo é locatário único ou multilocatário.
- O GUID do locatário obtido do portal do Azure para entrar em usuários em sua organização. Você também pode usar um nome de domínio.
- organizations Para iniciar sessão de utilizadores em qualquer conta escolar ou profissional
- common para iniciar sessão em utilizadores com qualquer conta escolar ou profissional ou conta pessoal da Microsoft
- consumers para iniciar sessão em utilizadores apenas 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 da instância e valores de ID do locatário.

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 definir como portal ou o aplicativo para evitar conflitos durante a manipulação do evento.

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/.

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.

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 em authConfig.js arquivo, que eventualmente será usado para inicializar o nó 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 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. No aplicativo de produção, considere o uso de 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. 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.

Em ASP.NET aplicativos Web principais (e APIs da Web), o aplicativo é protegido porque você tem um Authorize atributo 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 instalado, você pode instanciar diretamente ASP.NET aplicativos Web 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.

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.

Atualize o código para ConfigureServices que ele use os AddMicrosoftIdentityWebApp métodos 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 método em Startup.cs, habilite a Configure 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.

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);
 }

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 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 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.

O exemplo de nó usa a estrutura 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: '/'

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

Inicie e termine sessão.

Partilhar via

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

Bibliotecas da Microsoft que suportam aplicações Web

Arquivos de configuração

Código de inicialização

Próximo passo

Comentários

Recursos adicionais