Início Rápido: Conectar usuários e chamar a API do Microsoft Graph de um aplicativo web do ASP.NET
Neste início rápido, você baixará e executará um exemplo de código que demonstra um aplicativo web ASP.NET que pode conectar usuários com contas do Microsoft Entra.
Confira Como o exemplo funciona para ver uma ilustração.
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Visual Studio 2022
- .NET Framework 4.7.2+
Registrar e baixar o aplicativo
Dica
As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.
Você tem duas opções para começar a criar o seu aplicativo: configuração automática ou manual.
Configuração automática
Se você quiser configurar automaticamente o seu aplicativo e baixar o exemplo de código, siga estas etapas:
- Entre na experiência de início rápido do centro de administração do Microsoft Entra como, pelo menos, um Administrador de Aplicativo de Nuvem.
- Insira um nome para seu aplicativo e selecione Registrar.
- Siga as instruções para baixar e configurar automaticamente o novo aplicativo com apenas um clique.
Configuração manual
Se você quiser configurar manualmente o seu aplicativo e o exemplo de código, use os procedimentos a seguir.
Etapa 1: Registre seu aplicativo
- Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
- Se você tiver acesso a vários locatários, use o ícone de Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
- Navegue até Identidade>Aplicativos>Registros de aplicativos e selecione Novo registro.
- Em Nome, insira um nome para o seu aplicativo. Por exemplo, insira ASPNET-Quickstart. Os usuários do seu aplicativo verão esse nome e você pode alterá-lo mais tarde.
- Defina o tipo de URI de Redirecionamento como Web e valor como
https://localhost:44368/
. - Selecione Registrar.
- Em Gerenciar, selecione Autenticação.
- Na seção Concessão implícita e fluxos híbridos, selecione Tokens de ID.
- Clique em Salvar.
Etapa 2: Baixe o projeto
Baixar o exemplo de código do ASP.NET
Dica
Para evitar erros causados por limitações de comprimento do caminho no Windows, é recomendável extrair os arquivos em um diretório próximo à raiz da unidade.
Etapa 3: Executar o projeto
Extraia o arquivo. zip em uma pasta local próxima à pasta raiz. Por exemplo, extraia em C:\Azure-Samples.
É recomendável extrair os arquivos em um diretório próximo à raiz da unidade para evitar erros causados por limitações de comprimento do caminho no Windows.
Abra a solução no Visual Studio (AppModelv2-WebApp-OpenIDConnect-DotNet.sln).
Dependendo da versão do Visual Studio, pode ser necessário clicar com o botão direito do mouse no projeto AppModelv2-WebApp-OpenIDConnect-DotNet e selecionar Restaurar os pacotes do NuGet.
Abra o Console do Gerenciador de Pacotes selecionando Exibir>Outras Janelas>Console do Gerenciador de Pacotes. Em seguida, execute
Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r
.Edite appsettings.json e substitua os parâmetros
ClientId
,Tenant
eredirectUri
por:"ClientId" :"Enter_the_Application_Id_here" /> "TenantId": "Enter_the_Tenant_Info_Here" /> "RedirectUri" :"https://localhost:44368/" />
Neste código:
Enter_the_Application_Id_here
é a ID do aplicativo (cliente) do registro do aplicativo que você criou anteriormente. Localize a ID do aplicativo (cliente) na página Visão Geral do aplicativo em Registros de aplicativo no centro de administração do Microsoft Entra.Enter_the_Tenant_Info_Here
é uma das seguintes opções:- Se o seu aplicativo dá suporte a Somente minha organização, substitua esse valor pela ID do diretório (locatário) ou pelo nome do locatário (por exemplo,
contoso.onmicrosoft.com
). Localize a ID do diretório (locatário) na página Visão Geral do aplicativo em Registros de aplicativo no centro de administração do Microsoft Entra. - Se o aplicativo der suporte para Contas em qualquer diretório organizacional, substitua esse valor por
organizations
. - Se o aplicativo der suporte a Todos os usuários de contas Microsoft, substitua esse valor por
common
.
- Se o seu aplicativo dá suporte a Somente minha organização, substitua esse valor pela ID do diretório (locatário) ou pelo nome do locatário (por exemplo,
redirectUri
é o URI de redirecionamento que você inseriu anteriormente em Registros de aplicativo no centro de administração do Microsoft Entra.
Mais informações
Esta seção apresenta uma visão geral do código necessário para a entrada de usuários. Essa visão geral pode ser útil para entender como o código funciona, quais são os argumentos principais e como adicionar credenciais a um aplicativo ASP.NET existente.
Como o exemplo funciona
Pacotes do NuGet de middleware OWIN
Você pode configurar o pipeline de autenticação com a autenticação baseada em cookies usando o OpenID Connect no ASP.NET com pacotes de middleware OWIN. Você pode instalar esses pacotes executando os seguintes comandos no Console do Gerenciador de Pacotes no Visual Studio:
Install-Package Microsoft.Identity.Web.Owin
Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Owin.Security.Cookies
Classe de inicialização do OWIN
O middleware OWIN usa uma classe de inicialização que é executada quando o processo de hospedagem é iniciado. Neste guia de início rápido, o arquivo startup.cs está na pasta raiz. O seguinte código mostra os parâmetros usados neste guia de início rápido:
public void Configuration(IAppBuilder app)
{
app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
app.UseCookieAuthentication(new CookieAuthenticationOptions());
OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
app.AddMicrosoftIdentityWebApp(factory);
factory.Services
.Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44368/"; })
.AddMicrosoftGraph()
.AddInMemoryTokenCaches();
factory.Build();
}
Where | Descrição |
---|---|
ClientId |
A ID do aplicativo registrado no portal do Azure. |
Authority |
O ponto de extremidade do STS (serviço de token de segurança) para o usuário se autenticar. Geralmente, ele é https://login.microsoftonline.com/{tenant}/v2.0 para a nuvem pública. Nessa URL, {tenant} é o nome do seu locatário, da ID do locatário ou de common para uma referência ao ponto de extremidade comum. (O ponto de extremidade comum é usado para aplicativos multilocatários.) |
RedirectUri |
A URL para a qual os usuários são enviados após a autenticação na plataforma de identidade da Microsoft. |
PostLogoutRedirectUri |
A URL para a qual os usuários são enviados após saírem. |
Scope |
A lista de escopos que estão sendo solicitados, separados por espaços. |
ResponseType |
A solicitação da resposta da autenticação contém um código de autorização e um token de ID. |
TokenValidationParameters |
Uma lista de parâmetros para validação de token. Nesse caso, ValidateIssuer é definido como false para indicar que ele pode aceitar entradas de todos os tipos de conta corporativa ou de estudante ou pessoal. |
Notifications |
Uma lista de delegados que podem ser executados em mensagens OpenIdConnect . |
Desafio de autenticação
Você pode forçar um usuário a entrar solicitando um desafio de autenticação em seu controlador:
public void SignIn()
{
if (!Request.IsAuthenticated)
{
HttpContext.GetOwinContext().Authentication.Challenge(
new AuthenticationProperties{ RedirectUri = "/" },
OpenIdConnectAuthenticationDefaults.AuthenticationType);
}
}
Dica
Solicitar um desafio de autenticação usando esse método é opcional. Normalmente, você o usaria quando quisesse que uma exibição fosse acessível de usuários autenticados e não autenticados. Como alternativa, você pode proteger os controladores usando o método descrito na próxima seção.
Atributo para proteger um controlador ou ações do controlador
Você pode proteger um controlador ou ações do controlador usando o atributo [Authorize]
. Esse atributo restringe o acesso ao controlador ou às ações permitindo que apenas usuários autenticados acessem as ações no controlador. Um desafio de autenticação ocorrerá automaticamente quando um usuário não autenticado tentar acessar uma das ações ou controladores decorados pelo atributo [Authorize]
.
Chamar o Microsoft Graph pelo controlador
Você pode chamar o Microsoft Graph pelo controlador obtendo a instância do GraphServiceClient usando o método de extensão GetGraphServiceClient
no controlador, como no código a seguir:
try
{
var me = await this.GetGraphServiceClient().Me.GetAsync();
ViewBag.Username = me.DisplayName;
}
catch (ServiceException graphEx) when (graphEx.InnerException is MicrosoftIdentityWebChallengeUserException)
{
HttpContext.GetOwinContext().Authentication.Challenge(OpenIdConnectAuthenticationDefaults.AuthenticationType);
return View();
}
Ajuda e suporte
Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.
Próximas etapas
Para obter um guia passo a passo completo sobre a criação de aplicativos e novos recursos, incluindo uma explicação completa deste guia de início rápido, experimente o tutorial do ASP.NET.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de