Entrada e saída do aplicativo de página única - Microsoft identity platform

Artigo
05/14/2024

Antes que você possa obter tokens para acessar APIs em seu aplicativo, você precisa de um contexto de usuário autenticado. Para autenticar um usuário, você pode usar uma janela pop-up e/ou um método de entrada de redirecionamento.

Se o seu aplicativo tiver acesso a um contexto de usuário autenticado ou token de ID, você poderá ignorar a etapa de entrada e adquirir tokens diretamente. Para obter detalhes, confira Logon único (SSO) com dica de usuário.

Escolher entre uma experiência de pop-up ou de redirecionamento

A escolha entre uma experiência de pop-up ou redirecionamento depende do fluxo do aplicativo.

Use uma janela pop-up se você não quiser que os usuários se afastem da página principal do aplicativo durante a autenticação. Como o redirecionamento da autenticação ocorre em uma janela pop-up, o estado do aplicativo principal é preservado.
Use um redirecionamento se os usuários tiverem restrições ou políticas de navegador em que as janelas pop-up estão desabilitadas. Por exemplo, há problemas conhecidos relacionados a janelas pop-up no Internet Explorer.

const config = {
  auth: {
    clientId: "your_app_id",
    redirectUri: "your_app_redirect_uri", //defaults to application start page
    postLogoutRedirectUri: "your_app_logout_redirect_uri",
  },
};

const loginRequest = {
  scopes: ["User.ReadWrite"],
};

let accountId = "";

const myMsal = new PublicClientApplication(config);

myMsal
  .loginPopup(loginRequest)
  .then(function (loginResponse) {
    accountId = loginResponse.account.homeAccountId;
    // Display signed-in user content, call API, etc.
  })
  .catch(function (error) {
    //login failure
    console.log(error);
  });

Para invocar uma experiência de entrada para uma rota específica, importe @angular/router e adicione MsalGuard à definição de rota.

// In app-routing.module.ts
import { NgModule } from "@angular/core";
import { Routes, RouterModule } from "@angular/router";
import { ProfileComponent } from "./profile/profile.component";
import { MsalGuard } from "@azure/msal-angular";
import { HomeComponent } from "./home/home.component";

const routes: Routes = [
  {
    path: "profile",
    component: ProfileComponent,
    canActivate: [MsalGuard],
  },
  {
    path: "",
    component: HomeComponent,
  },
];

@NgModule({
  imports: [RouterModule.forRoot(routes, { useHash: false })],
  exports: [RouterModule],
})
export class AppRoutingModule {}

Para habilitar uma experiência de janela pop-up, defina a configuração interactionType como InteractionType.Popup em MsalGuardConfiguration. Você também pode passar os escopos que exigem consentimento.

// In app.module.ts
import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalModule } from "@azure/msal-angular";

@NgModule({
  imports: [
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "your_app_id",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Popup, // MsalGuard Configuration
        authRequest: {
          scopes: ["User.Read"],
        },
      },
      null
    ),
  ],
})
export class AppModule {}

Para invocar uma experiência de entrada quando um usuário ainda não estiver conectado, use a função MsalAuthenticationTemplate de @azure/msal-react. O wrapper do React da MSAL protege componentes específicos encapsulando-os no componente MsalAuthenticationTemplate.

import { InteractionType } from "@azure/msal-browser";
import { MsalAuthenticationTemplate, useMsal } from "@azure/msal-react";

function WelcomeUser() {
  const { accounts } = useMsal();
  const username = accounts[0].username;

  return <p>Welcome, {username}</p>;
}

// Remember that MsalProvider must be rendered somewhere higher up in the component tree
function App() {
  return (
    <MsalAuthenticationTemplate interactionType={InteractionType.Popup}>
      <p>This will only render if a user is not signed-in.</p>
      <WelcomeUser />
    </MsalAuthenticationTemplate>
  );
}

Para invocar uma experiência de entrada específica com base na interação do usuário (por exemplo, seleção de botão), use a função AuthenticatedTemplate e/ou UnauthenticatedTemplate de @azure/msal-react.

import {
  useMsal,
  AuthenticatedTemplate,
  UnauthenticatedTemplate,
} from "@azure/msal-react";

function signInClickHandler(instance) {
  instance.loginPopup();
}

// SignInButton Component returns a button that invokes a popup sign in when clicked
function SignInButton() {
  // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider
  const { instance } = useMsal();

  return <button onClick={() => signInClickHandler(instance)}>Sign In</button>;
}

function WelcomeUser() {
  const { accounts } = useMsal();
  const username = accounts[0].username;

  return <p>Welcome, {username}</p>;
}

// Remember that MsalProvider must be rendered somewhere higher up in the component tree
function App() {
  return (
    <>
      <AuthenticatedTemplate>
        <p>This will only render if a user is signed-in.</p>
        <WelcomeUser />
      </AuthenticatedTemplate>
      <UnauthenticatedTemplate>
        <p>This will only render if a user is not signed-in.</p>
        <SignInButton />
      </UnauthenticatedTemplate>
    </>
  );
}

const config = {
  auth: {
    clientId: "your_app_id",
    redirectUri: "your_app_redirect_uri", //defaults to application start page
    postLogoutRedirectUri: "your_app_logout_redirect_uri",
  },
};

const loginRequest = {
  scopes: ["User.ReadWrite"],
};

let accountId = "";

const myMsal = new PublicClientApplication(config);

function handleResponse(response) {
  if (response !== null) {
    accountId = response.account.homeAccountId;
    // Display signed-in user content, call API, etc.
  } else {
    // In case multiple accounts exist, you can select
    const currentAccounts = myMsal.getAllAccounts();

    if (currentAccounts.length === 0) {
      // no accounts signed-in, attempt to sign a user in
      myMsal.loginRedirect(loginRequest);
    } else if (currentAccounts.length > 1) {
      // Add choose account code here
    } else if (currentAccounts.length === 1) {
      accountId = currentAccounts[0].homeAccountId;
    }
  }
}

myMsal.handleRedirectPromise().then(handleResponse);

Para habilitar uma experiência de redirecionamento, defina a configuração interactionType como InteractionType.Redirect em MsalGuardConfiguration e, em seguida, inicialize MsalRedirectComponent para lidar com redirecionamentos.

// In app.module.ts
import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalModule, MsalRedirectComponent } from "@azure/msal-angular";

@NgModule({
  imports: [
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Redirect, // Msal Guard Configuration
        authRequest: {
          scopes: ["user.read"],
        },
      },
      null
    ),
  ],
  bootstrap: [AppComponent, MsalRedirectComponent],
})
export class AppModule {}

Para invocar uma experiência de entrada quando um usuário não estiver conectado, use a função MsalAuthenticationTemplate de @azure/msal-react.

import { InteractionType } from "@azure/msal-browser";
import { MsalAuthenticationTemplate, useMsal } from "@azure/msal-react";

function WelcomeUser() {
  const { accounts } = useMsal();
  const username = accounts[0].username;

  return <p>Welcome, {username}</p>;
}

// Remember that MsalProvider must be rendered somewhere higher up in the component tree
function App() {
  return (
    <MsalAuthenticationTemplate interactionType={InteractionType.Redirect}>
      <p>This will only render if a user is not signed-in.</p>
      <WelcomeUser />
    </MsalAuthenticationTemplate>
  );
}

import {
  useMsal,
  AuthenticatedTemplate,
  UnauthenticatedTemplate,
} from "@azure/msal-react";

function signInClickHandler(instance) {
  instance.loginRedirect();
}

// SignInButton Component returns a button that invokes a popup login when clicked
function SignInButton() {
  // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider
  const { instance } = useMsal();

  return <button onClick={() => signInClickHandler(instance)}>Sign In</button>;
}

function WelcomeUser() {
  const { accounts } = useMsal();
  const username = accounts[0].username;

  return <p>Welcome, {username}</p>;
}

// Remember that MsalProvider must be rendered somewhere higher up in the component tree
function App() {
  return (
    <>
      <AuthenticatedTemplate>
        <p>This will only render if a user is signed-in.</p>
        <WelcomeUser />
      </AuthenticatedTemplate>
      <UnauthenticatedTemplate>
        <p>This will only render if a user is not signed-in.</p>
        <SignInButton />
      </UnauthenticatedTemplate>
    </>
  );
}

Comportamento de saída em navegadores

Para garantir a saída segura de um ou mais aplicativos, os seguintes métodos são recomendados:

Em dispositivos compartilhados, os usuários devem usar o modo privado/anônimo de um navegador e fechar todas as janelas do navegador antes de se afastarem do dispositivo.
Em dispositivos que não são compartilhados, os usuários devem usar uma tela de bloqueio do sistema operacional para bloquear ou sair de toda a sessão do sistema operacional no dispositivo. A Microsoft usa sua página de saída para lembrar os usuários dessas melhores práticas de privacidade e segurança.

Para obter mais informações, confira as melhores práticas de privacidade na Internet da Microsoft.

Se um usuário optar por não sair usando as recomendações, os seguintes métodos também servem para habilitar a funcionalidade de saída:

Logoff do Front Channel do OpenID Connect da Microsoft para saída federada. Você pode usar esta opção quando um aplicativo compartilha um estado de entrada com um novo aplicativo, mas gerencia seus próprios tokens/cookies de sessão. Há algumas limitações para esta implementação em que o conteúdo é bloqueado, por exemplo, quando os navegadores bloqueiam cookies de terceiros.
Janela pop-up e/ou redirecionamento para saída do aplicativo local. Os métodos de pop-up e redirecionamento encerram a sessão do usuário no ponto de extremidade e no aplicativo local. Porém, esses métodos podem não limpar imediatamente a sessão para outros aplicativos federados se a comunicação de front-channel estiver bloqueada.

Sair com uma janela pop-up

A MSAL.js v2 e superior fornece um método logoutPopup que limpa o cache no armazenamento do navegador e abre uma janela pop-up para a página de saída do Microsoft Entra. Após a saída, o redirecionamento usa como padrão a página inicial de entrada e a janela pop-up é fechada.

Para a experiência após a saída, você pode definir o postLogoutRedirectUri para redirecionamento do usuário para um URI específico. Esse URI deve ser registrado como um URI de redirecionamento no registro do aplicativo. Você também pode configurar logoutPopup para redirecionar a janela principal para uma página diferente, como a página inicial ou a página de entrada, passando mainWindowRedirectUri como parte da solicitação.

const config = {
  auth: {
    clientId: "your_app_id",
    redirectUri: "your_app_redirect_uri", // defaults to application start page
    postLogoutRedirectUri: "your_app_logout_redirect_uri",
  },
};

const myMsal = new PublicClientApplication(config);

// you can select which account application should sign out
const logoutRequest = {
  account: myMsal.getAccountByHomeId(homeAccountId),
  mainWindowRedirectUri: "your_app_main_window_redirect_uri",
};

await myMsal.logoutPopup(logoutRequest);

// In app.module.ts
@NgModule({
    imports: [
        MsalModule.forRoot( new PublicClientApplication({
            auth: {
                clientId: 'your_app_id',
                postLogoutRedirectUri: 'your_app_logout_redirect_uri'
            }
        }), null, null)
    ]
})

// In app.component.ts
logout() {
    this.authService.logoutPopup({
        mainWindowRedirectUri: "/"
    });
}

import {
  useMsal,
  AuthenticatedTemplate,
  UnauthenticatedTemplate,
} from "@azure/msal-react";

function signOutClickHandler(instance) {
  const logoutRequest = {
    account: instance.getAccountByHomeId(homeAccountId),
    mainWindowRedirectUri: "your_app_main_window_redirect_uri",
    postLogoutRedirectUri: "your_app_logout_redirect_uri",
  };
  instance.logoutPopup(logoutRequest);
}

// SignOutButton component returns a button that invokes a pop-up sign out when clicked
function SignOutButton() {
  // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider
  const { instance } = useMsal();

  return (
    <button onClick={() => signOutClickHandler(instance)}>Sign Out</button>
  );
}

// Remember that MsalProvider must be rendered somewhere higher up in the component tree
function App() {
  return (
    <>
      <AuthenticatedTemplate>
        <p>This will only render if a user is signed-in.</p>
        <SignOutButton />
      </AuthenticatedTemplate>
      <UnauthenticatedTemplate>
        <p>This will only render if a user is not signed-in.</p>
      </UnauthenticatedTemplate>
    </>
  );
}

Sair com um redirecionamento

A MSAL.js fornece um método logout na v1 e um método logoutRedirect na v2 que limpa o cache no armazenamento do navegador e redireciona para a página de saída do Microsoft Entra. Após a saída, o redirecionamento é o padrão para a página inicial de entrada.

Como o lembrete da Microsoft sobre as melhores práticas de privacidade da Internet sobre como usar um navegador privado e uma tela de bloqueio não é mostrado neste método, talvez você queira descrever as práticas recomendadas e lembrar os usuários de fechar todas as janelas do navegador.

const config = {
  auth: {
    clientId: "your_app_id",
    redirectUri: "your_app_redirect_uri", //defaults to application start page
    postLogoutRedirectUri: "your_app_logout_redirect_uri",
  },
};

const myMsal = new PublicClientApplication(config);

// you can select which account application should sign out
const logoutRequest = {
  account: myMsal.getAccountByHomeId(homeAccountId),
};

myMsal.logoutRedirect(logoutRequest);

// In app.module.ts
@NgModule({
    imports: [
        MsalModule.forRoot( new PublicClientApplication({
            auth: {
                clientId: 'your_app_id',
                postLogoutRedirectUri: 'your_app_logout_redirect_uri'
            }
        }), null, null)
    ]
})

// In app.component.ts
logout() {
    this.authService.logoutRedirect();
}

import {
  useMsal,
  AuthenticatedTemplate,
  UnauthenticatedTemplate,
} from "@azure/msal-react";

function signOutClickHandler(instance) {
  const logoutRequest = {
    account: instance.getAccountByHomeId(homeAccountId),
    postLogoutRedirectUri: "your_app_logout_redirect_uri",
  };
  instance.logoutRedirect(logoutRequest);
}

// SignOutButton Component returns a button that invokes a redirect logout when clicked
function SignOutButton() {
  // useMsal hook will return the PublicClientApplication instance you provided to MsalProvider
  const { instance } = useMsal();

  return (
    <button onClick={() => signOutClickHandler(instance)}>Sign Out</button>
  );
}

// Remember that MsalProvider must be rendered somewhere higher up in the component tree
function App() {
  return (
    <>
      <AuthenticatedTemplate>
        <p>This will only render if a user is signed-in.</p>
        <SignOutButton />
      </AuthenticatedTemplate>
      <UnauthenticatedTemplate>
        <p>This will only render if a user is not signed-in.</p>
      </UnauthenticatedTemplate>
    </>
  );
}

Próximas etapas

Vá para o próximo artigo neste cenário, Adquirir um token para o aplicativo.

Compartilhar via

Escolher entre uma experiência de pop-up ou de redirecionamento

Comportamento de saída em navegadores

Sair com uma janela pop-up

Sair com um redirecionamento

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Aplicativo de página única: entrada e saída

Escolher entre uma experiência de pop-up ou de redirecionamento

Entrar com uma janela pop-up

Entrar com um redirecionamento

Comportamento de saída em navegadores

Sair com uma janela pop-up

Sair com um redirecionamento

Próximas etapas

Comentários

Recursos adicionais