Início Rápido: Conectar usuários em aplicativos de página única JavaScript - Microsoft identity platform

Artigo
04/09/2024

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um SPA (aplicativo de página única) JavaScript pode conectar usuários e chamar o Microsoft Graph. O exemplo de código também demonstra como obter um token de acesso para chamar a API do Microsoft Graph ou qualquer API Web.

Confira Como o exemplo funciona para ver uma ilustração.

Pré-requisitos

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Node.js
Visual Studio Code (para editar arquivos de projeto)

Registrar e baixar o aplicativo de início rápido

Para iniciar seu aplicativo de início rápido, use qualquer uma das opções a seguir.

Opção 1 (Expresso): Registrar e configurar o aplicativo automaticamente e, em seguida, baixar seu exemplo de código

Entre no portal do Azure: Registros de aplicativo experiência de início rápido.
Insira um nome para seu aplicativo.
Em Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft.
Selecione Registrar.
Siga as instruções para baixar e configurar automaticamente o novo aplicativo.

Opção 2 (Manual): Registrar e configurar manualmente o aplicativo e o exemplo de código

Etapa 1: Registre seu aplicativo

Entre no portal do Azure.
Se você tem acesso a vários locatários, use o filtro ícone Configurações no menu superior para selecionar o locatário no qual deseja registrar um aplicativo.
Procure e selecione Identidade.
Em Gerenciar, selecione Registros de aplicativo>Novo registro.
Insira um Nome para seu aplicativo. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Em Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft.
Selecione Registrar. Na página Visão geral do aplicativo, anote o valor de ID do aplicativo (cliente) para uso posterior.
Este início rápido requer que o fluxo de concessão implícita seja ativado. Em Gerenciar, selecione Autenticação.
Em Configurações da Plataforma>Adicionar uma plataforma. Selecione Web.
Defina o valor do URI de Redirecionamento como http://localhost:3000/.
Selecione Tokens de Acesso e Tokens de ID em Concessão implícita e fluxos híbridos.
Selecione Configurar.

Etapa 1: Configurar seu aplicativo no portal do Azure

Para que o exemplo de código deste guia de início rápido funcione, adicione um URI de Redirecionamento igual a http://localhost:3000/ e habilite Concessão implícita.

Fazer essas alterações para mim

Já configurado Esses atributos já estão configurados no seu aplicativo.

Etapa 2: Baixe o projeto

Para executar o projeto com um servidor Web usando Node.js, baixe os arquivos de projeto de núcleo.

Executar o projeto com um servidor Web usando o Node.js

Baixe o exemplo de código

Etapa 3: Configurar o aplicativo JavaScript

Na pasta JavaScriptSPA, edite authConfig.js e defina os valores clientID, authority e redirectUri em msalConfig.


 // Config object to be passed to Msal on creation
 const msalConfig = {
   auth: {
     clientId: "Enter_the_Application_Id_Here",
     authority: "Enter_the_Cloud_Instance_Id_Here/Enter_the_Tenant_Info_Here",
     redirectUri: "Enter_the_Redirect_Uri_Here",
   },
   cache: {
     cacheLocation: "sessionStorage", // This configures where your cache will be stored
     storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
   }
 };

Observação

Enter_the_Supported_Account_Info_Here

Em que:

Enter_the_Application_Id_Here é a ID do aplicativo (cliente) que você registrou.

Para encontrar o valor da ID do Aplicativo (cliente) , acesse a página Visão Geral do aplicativo no portal do Azure.
Enter_the_Cloud_Instance_Id_Here é a instância da nuvem do Azure. Para a nuvem principal ou global do Azure, basta inserir https://login.microsoftonline.com/ . Para nuvens nacionais (por exemplo, China), confira Nuvens nacionais.
Enter_the_Tenant_info_here é definido como uma das seguintes opções:
- Se o seu aplicativo for compatível com as contas neste diretório organizacional, substitua esse valor pela ID do locatário ou Nome do locatário (por exemplo, contoso.microsoft.com).
Para encontrar o valor da ID do Aplicativo (locatário) , acesse a página Visão Geral do registro do aplicativo no portal do Azure.
- Se o aplicativo tem suporte para contas em qualquer diretório organizacional, substitua esse valor por organizations.
- Se o seu aplicativo tem suporte para contas em qualquer diretório organizacional e contas pessoais Microsoft, substitua esse valor por common. Para restringir o suporte a contas pessoais da Microsoft, substitua esse valor por consumers.
Para encontrar o valor dos Tipos de conta com suporte, acesse a página Visão Geral do registro de aplicativo no portal do Azure.
Enter_the_Redirect_Uri_Here é http://localhost:3000/.

Etapa 3: seu aplicativo está configurado e pronto para ser executado

Configuramos seu projeto com os valores das propriedades do seu aplicativo.

Em seguida, ainda na mesma pasta, edite o arquivo graphConfig.js para definir o graphMeEndpoint e o graphMeEndpoint para o objeto apiConfig.

  // Add here the endpoints for MS Graph API services you would like to use.
  const graphConfig = {
    graphMeEndpoint: "Enter_the_Graph_Endpoint_Here/v1.0/me",
    graphMailEndpoint: "Enter_the_Graph_Endpoint_Here/v1.0/me/messages"
  };

  // Add here scopes for access token to be used at MS Graph API endpoints.
  const tokenRequest = {
      scopes: ["Mail.Read"]
  };

Em que:

<Insira_o_Ponto_de_Extremidade_do_Graph_Aqui> é o ponto de extremidade no qual as chamadas à API serão feitas. Para o serviço principal ou global da API do Microsoft Graph, basta inserir https://graph.microsoft.com/. Para obter mais informações, confira Implantação em uma nuvem nacional

Etapa 4: Executar o projeto

Execute o projeto com um servidor Web usando o Node.js:

Para iniciar o servidor, execute o seguinte comando no diretório do projeto:
```
npm install
npm start
```
Abra um navegador da Web e vá para http://localhost:3000/.
Selecione Entrar para iniciar a conexão e chame a API do Microsoft Graph.

Depois que o navegador carregar o aplicativo, selecione Entrar. Na primeira vez em que entrar, será solicitado que você forneça seu consentimento para permitir que o aplicativo acesse seu perfil e faça logon. Depois que você se conectar com êxito, as informações do seu perfil de usuário deverão ser exibidas na página.

Mais informações

Como o exemplo funciona

msal.js

A biblioteca MSAL conecta usuários e solicita os tokens que são usados para acessar uma API protegida pela plataforma de identidade da Microsoft. O arquivo index.html do início rápido contém uma referência à biblioteca:

<script type="text/javascript" src="https://alcdn.msftauth.net/lib/1.2.1/js/msal.js" integrity="sha384-9TV1245fz+BaI+VvCjMYL0YDMElLBwNS84v3mY57pXNOt6xcUYch2QLImaTahcOP" crossorigin="anonymous"></script>

É possível substituir a versão anterior pela mais recente em versões MSAL.js.

Como alternativa, se tiver instalado o Node.js, você poderá baixar a versão mais recente por meio do npm (Gerenciador de Pacotes do Node.js):

npm install msal

Inicialização da MSAL

O código de início rápido também mostra como inicializar a biblioteca MSAL:

  // Config object to be passed to Msal on creation
  const msalConfig = {
    auth: {
      clientId: "00001111-aaaa-2222-bbbb-3333cccc4444", // this is a fake id
      authority: "https://login.microsoftonline.com/common",
      redirectUri: "http://localhost:3000/",
    },
    cache: {
      cacheLocation: "sessionStorage", // This configures where your cache will be stored
      storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
    }
  };

const myMSALObj = new Msal.UserAgentApplication(msalConfig);

Where	Descrição
`clientId`	A ID do aplicativo que está registrado no portal do Azure.
`authority`	(Opcional) A URL da autoridade que dá suporte aos tipos de conta, conforme descrito na seção de configuração. A autoridade padrão é `https://login.microsoftonline.com/common`.
`redirectUri`	O URI de reposta/redirecionamento configurado do registro de aplicativo. Nesse caso, `http://localhost:3000/`.
`cacheLocation`	(Opcional) Define o armazenamento do navegador para o estado de autenticação. O padrão é sessionStorage.
`storeAuthStateInCookie`	(Opcional) A biblioteca que armazena o estado de solicitação da autenticação exigido para validação dos fluxos de autenticação nos cookies do navegador. Esse cookie é definido para os navegadores IE e Microsoft Edge reduzirem determinados problemas conhecidos.

Para saber mais sobre opções configuráveis disponíveis, confira Inicializar aplicativos cliente.

O snippet de código a seguir mostra como realizar a conexão de usuários:

// Add scopes for the id token to be used at Microsoft identity platform endpoints.
const loginRequest = {
    scopes: ["openid", "profile", "User.Read"],
};

myMSALObj.loginPopup(loginRequest)
    .then((loginResponse) => {
    //Login Success callback code here
}).catch(function (error) {
    console.log(error);
});

Where	Descrição
`scopes`	(Opcional) Contém os escopos que estão sendo solicitados para o consentimento do usuário no momento da conexão. Por exemplo, `[ "user.read" ]` para o Microsoft Graph ou `[ "<Application ID URL>/scope" ]` para as APIs Web personalizadas (ou seja, `api://<Application ID>/access_as_user`).

Como alternativa, talvez você queira usar o método loginRedirect para redirecionar a página atual para a página de entrada, em vez de uma janela pop-up.

Solicitar tokens

A MSAL usa três métodos para adquirir tokens: acquireTokenRedirect, acquireTokenPopup e acquireTokenSilent

Obter um token de usuário no modo silencioso

O método acquireTokenSilent manipula as aquisições e a renovação de tokens sem nenhuma interação do usuário. Após o método loginRedirect ou loginPopup ser executado pela primeira vez, acquireTokenSilent é o método normalmente usado para obter tokens usados para acessar recursos protegidos nas próximas chamadas. As chamadas para solicitar ou renovar tokens são feitas no modo silencioso.


const tokenRequest = {
    scopes: ["Mail.Read"]
};

myMSALObj.acquireTokenSilent(tokenRequest)
    .then((tokenResponse) => {
        // Callback code here
        console.log(tokenResponse.accessToken);
    }).catch((error) => {
        console.log(error);
    });

Where	Descrição
`scopes`	Contém os escopos solicitados para retorno no token de acesso da API. Por exemplo, `[ "mail.read" ]` para o Microsoft Graph ou `[ "<Application ID URL>/scope" ]` para as APIs Web personalizadas (ou seja, `api://<Application ID>/access_as_user`).

Obter um token de usuário interativamente

Há situações em que você força os usuários a interagir com a plataforma de identidade da Microsoft. Por exemplo:

Os usuários podem precisar reinserir as credenciais porque a senha expirou.
Seu aplicativo está solicitando acesso a escopos de recursos adicionais com os quais o usuário precisa concordar.
A autenticação de dois fatores é necessária.

O padrão usual recomendado para a maioria dos aplicativos é chamar acquireTokenSilent primeiro, depois capturar a exceção e, em seguida, chamar acquireTokenPopup (ou acquireTokenRedirect) para iniciar uma solicitação interativa.

Chamar o acquireTokenPopup resulta em uma janela pop-up para entrada. (Ou acquireTokenRedirect resulta no redirecionamento dos usuários para a plataforma de identidade da Microsoft). Nessa janela, os usuários precisam interagir confirmando suas credenciais, dando consentimento ao recurso necessário ou concluindo a autenticação de dois fatores.

// Add here scopes for access token to be used at MS Graph API endpoints.
const tokenRequest = {
    scopes: ["Mail.Read"]
};

myMSALObj.acquireTokenPopup(requestObj)
    .then((tokenResponse) => {
        // Callback code here
        console.log(tokenResponse.accessToken);
    }).catch((error) => {
        console.log(error);
    });