Tutorial: Criar um aplicativo de página única do React e prepará-lo para autenticação

Aplica-se a: locatários da força de trabalho Locatários externos (saiba mais)

Neste tutorial, você criará um aplicativo de página única (SPA) React e o preparará para autenticação usando a plataforma de identidade da Microsoft. Este tutorial demonstra como criar um SPA React usando npm, criar arquivos necessários para autenticação e autorização e adicionar os detalhes do locatário ao código-fonte. O aplicativo pode ser usado para funcionários em um locatário de força de trabalho ou para clientes que usam um locatário externo.

Neste tutorial, você:

• Criar um novo projeto React
• Instalar pacotes necessários para autenticação
• Crie sua estrutura de arquivos e adicione código ao arquivo do servidor
• Adicione os detalhes do locatário ao arquivo de configuração de autenticação

Pré-requisitos

• Habitação para trabalhadores. Você pode usar seu de diretório padrão ou configurar um novo locatário.
• Registe uma nova aplicação no centro de administração do Microsoft Entra com a seguinte configuração. Para obter mais informações, consulte Registrar um aplicativo.
  • Nome: identity-client-spa
  • Tipos de conta suportados: Contas apenas neste diretório organizacional (Locatário único).
  • Configuração da plataforma: Aplicação de página única (SPA).
  • Redirecionar URI: http://localhost:3000/.

Inquilino externo

• Um inquilino externo. Para criar um, escolha um dos seguintes métodos:
  • (Recomendado) Use o extensão de ID Externa do Microsoft Entra para configurar um locatário externo diretamente no Visual Studio Code.
  • Crie um novo inquilino externo no centro de administração do Microsoft Entra.
• Registe uma nova aplicação no centro de administração do Microsoft Entra com a seguinte configuração. Para obter mais informações, consulte Registrar um aplicativo.
  • Nome: identity-client-spa
  • pt-PT: Tipos de contas suportados: Contas apenas neste diretório organizacional (Inquilino único).
  • Configuração da plataforma: Aplicação de página única (SPA).
  • Redirecionar URI: http://localhost:3000/.
• Associe seu aplicativo a um fluxo de usuário no centro de administração do Microsoft Entra. Para obter mais informações, consulte Criar fluxos de usuário de inscrição de autoatendimento para aplicativos em locatários externos e Adicionar seu aplicativo ao fluxo de usuário.

• Node.js.
• Visual Studio Code ou outro editor de código.

Criar um novo projeto React

1. Abra o Visual Studio Code, selecione Arquivo>Abrir Pasta.... Navegue até o local para criar seu projeto e selecione-o.

2. Abra um novo terminal selecionando Terminal>Novo Terminal.

3. Execute os seguintes comandos para criar um novo projeto React com o nome reactspalocal, mude para o novo diretório e inicie o projeto React. Um navegador da Web será aberto com o endereço http://localhost:3000/ por padrão. O navegador permanece aberto e renderiza novamente para cada alteração salva.

   npx create-react-app reactspalocal
   cd reactspalocal
   npm start
   

4. Crie pastas e arquivos adicionais para obter a seguinte estrutura de pastas:

   ├─── public
   │   └─── index.html
   └───src
       └─── styles
       │   └─── App.css
       │   └─── index.css
       ├─── utils
       │   └─── claimUtils.js
       ├─── components
       │   └─── DataDisplay.jsx
       │   └─── NavigationBar.jsx
       │   └─── PageLayout.jsx
       └── App.jsx
       └── authConfig.js
       └── index.js
   

---

Instalar pacotes de identidade e Bootstrap

Os pacotes de npm relacionados à identidade devem ser instalados no projeto para habilitar a autenticação do usuário. Para a formatação do projeto, será usado Bootstrap .

1. Na barra Terminal, selecione o ícone + para criar um novo terminal. Uma janela de terminal separada será aberta enquanto o terminal do nó anterior continua a ser executado em segundo plano.

2. Certifique-se de que o diretório correto está selecionado (reactspalocal) e insira o seguinte no terminal para instalar os pacotes msal e bootstrap relevantes.

   npm install @azure/msal-browser @azure/msal-react
   npm install react-bootstrap bootstrap
   

---

Adicione os detalhes do locatário à configuração do MSAL

O arquivo authConfig.js contém as definições de configuração para o fluxo de autenticação e é usado para configurar MSAL.js com as configurações necessárias para autenticação.

1. Na pasta src, abra authConfig.js e adicione o seguinte trecho de código:

   
    import { LogLevel } from '@azure/msal-browser';
   
    /**
    * Configuration object to be passed to MSAL instance on creation. 
    * For a full list of MSAL.js configuration parameters, visit:
    * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md 
    */
   
    export const msalConfig = {
        auth: {
            clientId: 'Enter_the_Application_Id_Here', // This is the ONLY mandatory field that you need to supply.
            authority: 'https://login.microsoftonline.com/Enter_the_Tenant_Info_Here', // Replace the placeholder with your tenant info
            redirectUri: 'http://localhost:3000/redirect', // Points to window.location.origin. You must register this URI on Microsoft Entra admin center/App Registration.
            postLogoutRedirectUri: '/', // Indicates the page to navigate after logout.
            navigateToLoginRequestUrl: false, // If "true", will navigate back to the original request location before processing the auth code response.
        },
        cache: {
            cacheLocation: 'sessionStorage', // Configures cache location. "sessionStorage" is more secure, but "localStorage" gives you SSO between tabs.
            storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
        },
        system: {
            loggerOptions: {
                loggerCallback: (level, message, containsPii) => {
                    if (containsPii) {
                        return;
                    }
                    switch (level) {
                        case LogLevel.Error:
                            console.error(message);
                            return;
                        case LogLevel.Info:
                            console.info(message);
                            return;
                        case LogLevel.Verbose:
                            console.debug(message);
                            return;
                        case LogLevel.Warning:
                            console.warn(message);
                            return;
                        default:
                            return;
                    }
                },
            },
        },
    };
   
    /**
    * Scopes you add here will be prompted for user consent during sign-in.
    * By default, MSAL.js will add OIDC scopes (openid, profile, email) to any login request.
    * For more information about OIDC scopes, visit: 
    * https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
    */
    export const loginRequest = {
        scopes: [],
    };
   
    /**
    * An optional silentRequest object can be used to achieve silent SSO
    * between applications by providing a "login_hint" property.
    */
    // export const silentRequest = {
    //     scopes: ["openid", "profile"],
    //     loginHint: "example@domain.net"
    // };
   

2. Substitua os seguintes valores pelos valores do centro de administração do Microsoft Entra.

   • clientId - O identificador do aplicativo, também conhecido como cliente. Substitua Enter_the_Application_Id_Here pelo valor do ID de Aplicação (cliente) do que foi registado anteriormente na página de resumo da aplicação registada.
   • authority - Este é composto por duas partes:
     • O de instância é o ponto de extremidade do provedor de nuvem. Consulte os diferentes pontos finais disponíveis em Nuvens nacionais.
     • O ID do Locatário é o identificador do locatário onde a aplicação está registada. Substitua Enter_the_Tenant_Info_Here pelo valor do ID do Directory (locatário) que foi anotado anteriormente na página de visão geral do aplicativo registado.

3. Salve o arquivo.

Inquilino externo

1. Na pasta src, abra authConfig.js e adicione o seguinte trecho de código:

   import { LogLevel } from '@azure/msal-browser';
   
   /**
    * Configuration object to be passed to MSAL instance on creation.
    * For a full list of MSAL.js configuration parameters, visit:
    * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md 
    */
   
   export const msalConfig = {
       auth: {
           clientId: 'Enter_the_Application_Id_Here', // This is the ONLY mandatory field that you need to supply.
           authority: 'https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/', // Replace the placeholder with your tenant subdomain 
           redirectUri: '/', // Points to window.location.origin. You must register this URI on Azure Portal/App Registration.
           postLogoutRedirectUri: '/', // Indicates the page to navigate after logout.
           navigateToLoginRequestUrl: false, // If "true", will navigate back to the original request location before processing the auth code response.
       },
       cache: {
           cacheLocation: 'sessionStorage', // Configures cache location. "sessionStorage" is more secure, but "localStorage" gives you SSO between tabs.
           storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
       },
       system: {
           loggerOptions: {
               loggerCallback: (level, message, containsPii) => {
                   if (containsPii) {
                       return;
                   }
                   switch (level) {
                       case LogLevel.Error:
                           console.error(message);
                           return;
                       case LogLevel.Info:
                           console.info(message);
                           return;
                       case LogLevel.Verbose:
                           console.debug(message);
                           return;
                       case LogLevel.Warning:
                           console.warn(message);
                           return;
                       default:
                           return;
                   }
               },
           },
       },
   };
   
   /**
    * Scopes you add here will be prompted for user consent during sign-in.
    * By default, MSAL.js will add OIDC scopes (openid, profile, email) to any login request.
    * For more information about OIDC scopes, visit:
    * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
    */
   export const loginRequest = {
       scopes: [],
   };
   
   /**
    * An optional silentRequest object can be used to achieve silent SSO
    * between applications by providing a "login_hint" property.
    */
   // export const silentRequest = {
   //     scopes: ["openid", "profile"],
   //     loginHint: "example@domain.net"
   // };
   

2. Substitua os seguintes valores pelos valores do centro de administração do Entra:

   • Enter_the_Application_Id_Here e substitua-o pela ID do aplicativo (cliente) no centro de administração do Microsoft Entra.
   • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do inquilino for contoso.onmicrosoft.com, use contoso. Se não tiver o nome do locatário, saiba como consultar os detalhes do locatário.

3. Salve o arquivo.

Usar domínio de URL personalizado (opcional)

Aplica-se a: Os locatários do Workforce Inquilinos externos (saber mais)

Use um domínio personalizado para marcar totalmente a URL de autenticação. Do ponto de vista do usuário, os usuários permanecem no seu domínio durante o processo de autenticação, em vez de serem redirecionados para ciamlogin.com nome de domínio.

Use as seguintes etapas para usar um domínio personalizado:

1. Use as etapas em Habilitar domínios de URL personalizados para aplicativos em locatários externos para habilitar um domínio de URL personalizado para o seu locatário externo.

2. No arquivo authConfig.js, localize o objeto auth e, em seguida:

   1. Atualize o valor da propriedade authority para https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Substitua Enter_the_Custom_Domain_Here pelo seu domínio de URL personalizado e Enter_the_Tenant_ID_Here pelo seu ID de inquilino. Se não tiver o seu ID de inquilino, saiba como ler os detalhes do seu inquilino.
   2. Adicione a propriedade knownAuthorities com um valor [Insira_o_Domínio_Personalizado_Aqui].

Depois de fazer as alterações no arquivo authConfig.js, se o domínio de URL personalizado estiver login.contoso.come o ID do locatário for aaaabbbb-0000-cccc-1111-dddd2222eeee, o arquivo deverá ser semelhante ao seguinte trecho:

//...
const msalConfig = {
    auth: {
        authority: process.env.AUTHORITY || 'https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee', 
        knownAuthorities: ["login.contoso.com"],
        //Other properties
    },
    //...
};

Adicionar o provedor de autenticação

Os pacotes msal são usados para fornecer autenticação no aplicativo. O pacote msal-browser é usado para manipular o fluxo de autenticação e o pacote msal-react é usado para integrar msal-browser com o React. addEventCallback é usado para escutar eventos que ocorrem durante o processo de autenticação, como quando um usuário efetua login com êxito. O método setActiveAccount é usado para definir a conta ativa para o aplicativo, que é usado para determinar quais informações do usuário devem ser exibidas.

1. Na pasta src, abra index.js e substitua o conteúdo do arquivo pelo seguinte trecho de código para usar os pacotes msal e o estilo de bootstrap:

   import React from 'react';
   import { createRoot } from 'react-dom/client';
   import App from './App';
   import { PublicClientApplication, EventType } from '@azure/msal-browser';
   import { msalConfig } from './authConfig';
   
   import 'bootstrap/dist/css/bootstrap.min.css';
   import './styles/index.css';
   
   /**
   * MSAL should be instantiated outside of the component tree to prevent it from being re-instantiated on re-renders.
   * For more, visit: https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-react/docs/getting-started.md
   */
   const msalInstance = new PublicClientApplication(msalConfig);
   
   // Default to using the first account if no account is active on page load
   if (!msalInstance.getActiveAccount() && msalInstance.getAllAccounts().length > 0) {
       // Account selection logic is app dependent. Adjust as needed for different use cases.
       msalInstance.setActiveAccount(msalInstance.getActiveAccount()[0]);
   }
   
   // Listen for sign-in event and set active account
   msalInstance.addEventCallback((event) => {
       if (event.eventType === EventType.LOGIN_SUCCESS && event.payload.account) {
           const account = event.payload.account;
           msalInstance.setActiveAccount(account);
       }
   });
   
   const root = createRoot(document.getElementById('root'));
   root.render(
       <App instance={msalInstance}/>
   );
   

2. Salve o arquivo.

Para saber mais sobre esses pacotes, consulte a documentação em msal-browser e msal-react.

Adicionar o componente principal do aplicativo

Todas as partes do aplicativo que exigem autenticação devem ser encapsuladas no componente MsalProvider. Você define uma variável instance que utiliza o gancho useMsal para obter a instância PublicClientApplication e depois passá-la para MsalProvider. O componente MsalProvider disponibiliza a instância PublicClientApplication em todo o aplicativo por meio da API de contexto do React. Todos os componentes abaixo de MsalProvider terão acesso à instância PublicClientApplication através do contexto, assim como todos os hooks e componentes fornecidos por msal-react.

1. Na pasta src, abra App.jsx e substitua o conteúdo do arquivo pelo seguinte trecho de código:

   import { MsalProvider, AuthenticatedTemplate, useMsal, UnauthenticatedTemplate } from '@azure/msal-react';
   import { Container, Button } from 'react-bootstrap';
   import { PageLayout } from './components/PageLayout';
   import { IdTokenData } from './components/DataDisplay';
   import { loginRequest } from './authConfig';
   
   import './styles/App.css';
   
   /**
   * Most applications will need to conditionally render certain components based on whether a user is signed in or not. 
   * msal-react provides 2 easy ways to do this. AuthenticatedTemplate and UnauthenticatedTemplate components will 
   * only render their children if a user is authenticated or unauthenticated, respectively. For more, visit:
   * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-react/docs/getting-started.md
   */
   const MainContent = () => {
       /**
       * useMsal is hook that returns the PublicClientApplication instance,
       * that tells you what msal is currently doing. For more, visit:
       * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-react/docs/hooks.md
       */
       const { instance } = useMsal();
       const activeAccount = instance.getActiveAccount();
   
       const handleRedirect = () => {
           instance
               .loginRedirect({
                   ...loginRequest,
                   prompt: 'create',
               })
               .catch((error) => console.log(error));
       };
       return (
           <div className="App">
               <AuthenticatedTemplate>
                   {activeAccount ? (
                       <Container>
                           <IdTokenData idTokenClaims={activeAccount.idTokenClaims} />
                       </Container>
                   ) : null}
               </AuthenticatedTemplate>
               <UnauthenticatedTemplate>
                   <Button className="signInButton" onClick={handleRedirect} variant="primary">
                       Sign up
                   </Button>
               </UnauthenticatedTemplate>
           </div>
       );
   };
   
   
   /**
   * msal-react is built on the React context API and all parts of your app that require authentication must be 
   * wrapped in the MsalProvider component. You will first need to initialize an instance of PublicClientApplication 
   * then pass this to MsalProvider as a prop. All components underneath MsalProvider will have access to the 
   * PublicClientApplication instance via context as well as all hooks and components provided by msal-react. For more, visit:
   * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-react/docs/getting-started.md
   */
   const App = ({ instance }) => {
       return (
           <MsalProvider instance={instance}>
               <PageLayout>
                   <MainContent />
               </PageLayout>
           </MsalProvider>
       );
   };
   
   export default App;
   

2. Salve o arquivo.

Próximos passos

Tutorial: Criar componentes para entrar e sair em um aplicativo de página única do Rereact