Aplicativo de página única: adquirir um token para chamar uma API

Aplica-se a: Inquilinos da força de trabalho Inquilinos externos (saiba mais)

O padrão para aquisição de tokens para APIs com a MSAL.js é primeiro tentar fazer uma solicitação de token silenciosa usando o método acquireTokenSilent. Quando esse método é chamado, a biblioteca primeiro verifica o cache no armazenamento do navegador para verificar se há um token de acesso não expirado e o retorna. Se nenhum token de acesso for encontrado, ou o token de acesso encontrado expirou, ele tentará usar o token de atualização para obter um novo token de acesso. Se o tempo de vida de 24 horas do token de atualização também expirou, o MSAL.js abrirá um iframe oculto para solicitar silenciosamente um novo código de autorização usando a sessão ativa existente com o Microsoft Entra ID (se houver), que será trocado por um novo conjunto de tokens (tokens de atualização e acesso).

Para obter mais informações sobre a sessão de SSO (logon único) e os valores de tempo de vida do token no Microsoft Entra ID, confira Tempos de vida do token. Para obter mais informações sobre a política de pesquisa de cache do MSAL.js, consulte Adquirir um token de acesso.

As solicitações de token silencioso para o Microsoft Entra ID podem falhar por motivos como uma alteração de senha ou políticas de Acesso Condicional atualizadas. Mais frequentemente, as falhas são devido ao tempo de vida de 24 horas do token de atualização expirar e o navegador bloqueando cookies de terceiros, o que impede o uso de iframes ocultos para continuar a autenticar o usuário. Nesses casos, você deve invocar um dos métodos interativos (que podem solicitar ao usuário) para adquirir tokens:

• Janela pop-up usando acquireTokenPopup
• Redirecionamento usando acquireTokenRedirect

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

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

• Caso você não deseje que os usuários saiam da página principal do aplicativo durante a autenticação, recomendamos o método de pop-up. Como o redirecionamento da autenticação ocorre em uma janela pop-up, o estado do aplicativo principal é preservado.
• Se os usuários tiverem restrições de navegador ou políticas nas quais as janelas pop-up estejam desabilitadas, você poderá usar o método de redirecionamento. Use o método de redirecionamento com o navegador Internet Explorer, pois há problemas conhecidos com as janelas pop-up no Internet Explorer.

Você poderá definir os escopos de API que deseja incluir no token de acesso quando ele criar a solicitação de token de acesso. Todos os escopos solicitados podem não ser concedidos no token de acesso. Isso depende do consentimento do usuário.

Adquirir um token com uma janela pop-up

Reagir

O seguinte código combina o padrão descrito anteriormente com os métodos para uma experiência de pop-up:

import {
  InteractionRequiredAuthError,
  InteractionStatus,
} from "@azure/msal-browser";
import { AuthenticatedTemplate, useMsal } from "@azure/msal-react";

function ProtectedComponent() {
  const { instance, inProgress, accounts } = useMsal();
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    if (!apiData && inProgress === InteractionStatus.None) {
      const accessTokenRequest = {
        scopes: ["user.read"],
        account: accounts[0],
      };
      instance
        .acquireTokenSilent(accessTokenRequest)
        .then((accessTokenResponse) => {
          // Acquire token silent success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken).then((response) => {
            setApiData(response);
          });
        })
        .catch((error) => {
          if (error instanceof InteractionRequiredAuthError) {
            instance
              .acquireTokenPopup(accessTokenRequest)
              .then(function (accessTokenResponse) {
                // Acquire token interactive success
                let accessToken = accessTokenResponse.accessToken;
                // Call your API with token
                callApi(accessToken).then((response) => {
                  setApiData(response);
                });
              })
              .catch(function (error) {
                // Acquire token interactive failure
                console.log(error);
              });
          }
          console.log(error);
        });
    }
  }, [instance, accounts, inProgress, apiData]);

  return <p>Return your protected content here: {apiData}</p>;
}

function App() {
  return (
    <AuthenticatedTemplate>
      <ProtectedComponent />
    </AuthenticatedTemplate>
  );
}

Como alternativa, se você precisar adquirir um token fora de um componente do React, poderá chamar acquireTokenSilent, mas não deverá retornar para a interação se ela falhar. Todas as interações deverá ocorrer sob o componente MsalProvider na árvore de componentes.

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

// Use the same publicClientApplication instance provided to MsalProvider
publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure
    console.log(error);
  });

JavaScript (MSAL.js)

O seguinte código combina o padrão descrito anteriormente com os métodos para uma experiência de pop-up:

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure, and send an interactive request
    if (error instanceof InteractionRequiredAuthError) {
      publicClientApplication
        .acquireTokenPopup(accessTokenRequest)
        .then(function (accessTokenResponse) {
          // Acquire token interactive success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken);
        })
        .catch(function (error) {
          // Acquire token interactive failure
          console.log(error);
        });
    }
    console.log(error);
  });

Angular (MSAL.js)

O wrapper da MSAL Angular fornece o interceptador HTTP, que automaticamente adquirirá tokens de acesso silenciosamente e os anexará às solicitações HTTP nas APIs.

Especifique os escopos para as APIs na opção de configuração protectedResourceMap. MsalInterceptor solicita esses escopos especificados ao adquirir os tokens automaticamente.

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

@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    // ...
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Popup,
        authRequest: {
          scopes: ["user.read"],
        },
      },
      {
        interactionType: InteractionType.Popup,
        protectedResourceMap: new Map([
          ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ]),
      }
    ),
  ],
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MsalInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Para o êxito e a falha da aquisição de token silenciosa, o MSAL Angular fornece eventos que você poderá assinar. Também é importante se lembrar de cancelar a assinatura.

import { MsalBroadcastService } from '@azure/msal-angular';
import { EventMessage, EventType } from '@azure/msal-browser';

import { filter, Subject, takeUntil } from 'rxjs';

// In app.component.ts
export class AppComponent implements OnInit {
  private readonly _destroying$ = new Subject<void>();

  constructor(private broadcastService: MsalBroadcastService) { }

  ngOnInit() {
    this.broadcastService.msalSubject$
    .pipe(
      filter((msg: EventMessage) => msg.eventType === EventType.ACQUIRE_TOKEN_SUCCESS),
      takeUntil(this._destroying$)
    )
    .subscribe((result: EventMessage) => {
      // Do something with event payload here
    });
  }

  ngOnDestroy(): void {
    this._destroying$.next(undefined);
    this._destroying$.complete();
  }
}

Como alternativa, você pode adquirir tokens explicitamente usando os métodos de aquisição de token, conforme descrito na biblioteca principal da MSAL.js.

Adquirir um token com um redirecionamento

Reagir

Se acquireTokenSilent falhar, faça fallback para acquireTokenRedirect. Esse método inicia um redirecionamento de quadro completo, e a resposta será tratada quando for retornada ao aplicativo. Quando esse componente é renderizado depois de retornado do redirecionamento, acquireTokenSilent deverá ter êxito, pois os tokens serão extraídos do cache.

import {
  InteractionRequiredAuthError,
  InteractionStatus,
} from "@azure/msal-browser";
import { AuthenticatedTemplate, useMsal } from "@azure/msal-react";

function ProtectedComponent() {
  const { instance, inProgress, accounts } = useMsal();
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    const accessTokenRequest = {
      scopes: ["user.read"],
      account: accounts[0],
    };
    if (!apiData && inProgress === InteractionStatus.None) {
      instance
        .acquireTokenSilent(accessTokenRequest)
        .then((accessTokenResponse) => {
          // Acquire token silent success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken).then((response) => {
            setApiData(response);
          });
        })
        .catch((error) => {
          if (error instanceof InteractionRequiredAuthError) {
            instance.acquireTokenRedirect(accessTokenRequest);
          }
          console.log(error);
        });
    }
  }, [instance, accounts, inProgress, apiData]);

  return <p>Return your protected content here: {apiData}</p>;
}

function App() {
  return (
    <AuthenticatedTemplate>
      <ProtectedComponent />
    </AuthenticatedTemplate>
  );
}

Como alternativa, se você precisar adquirir um token fora de um componente do React, poderá chamar acquireTokenSilent, mas não deverá retornar para a interação se ela falhar. Todas as interações deverá ocorrer sob o componente MsalProvider na árvore de componentes.

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

// Use the same publicClientApplication instance provided to MsalProvider
publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure
    console.log(error);
  });

JavaScript (MSAL.js)

O padrão a seguir é o mesmo descrito anteriormente, mas mostrado com um método de redirecionamento para adquirir tokens de maneira interativa. Você precisa chamar e aguardar a handleRedirectPromise após o carregamento da página.

const redirectResponse = await publicClientApplication.handleRedirectPromise();
if (redirectResponse !== null) {
  // Acquire token silent success
  let accessToken = redirectResponse.accessToken;
  // Call your API with token
  callApi(accessToken);
} else {
  // MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
  const account = publicClientApplication.getAllAccounts()[0];

  const accessTokenRequest = {
    scopes: ["user.read"],
    account: account,
  };

  publicClientApplication
    .acquireTokenSilent(accessTokenRequest)
    .then(function (accessTokenResponse) {
      // Acquire token silent success
      // Call API with token
      let accessToken = accessTokenResponse.accessToken;
      // Call your API with token
      callApi(accessToken);
    })
    .catch(function (error) {
      //Acquire token silent failure, and send an interactive request
      console.log(error);
      if (error instanceof InteractionRequiredAuthError) {
        publicClientApplication.acquireTokenRedirect(accessTokenRequest);
      }
    });
}

Solicitar declarações opcionais

Você pode usar declarações opcionais para as seguintes finalidades:

• Inclua declarações extras em tokens para seu aplicativo.
• Altere o comportamento de determinadas declarações que o Microsoft Entra ID retorna em tokens.
• Adicione e acesse as declarações personalizadas para o aplicativo.

Para solicitar declarações opcionais no IdToken, você pode enviar um objeto de declarações em cadeias de caracteres para o campo claimsRequest da classe AuthenticationParameters.ts.

var claims = {
  optionalClaims: {
    idToken: [
      {
        name: "auth_time",
        essential: true,
      },
    ],
  },
};

var request = {
  scopes: ["user.read"],
  claimsRequest: JSON.stringify(claims),
};

myMSALObj.acquireTokenPopup(request);

Para saber mais, confira Declarações opcionais.

Angular (MSAL.js)

Esse código é o mesmo descrito anteriormente, com a exceção de que recomendamos inicializar o MsalRedirectComponent para tratar os redirecionamentos. As configurações do MsalInterceptor também podem ser alteradas para usar redirecionamentos.

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

@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    // ...
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Redirect,
        authRequest: {
          scopes: ["user.read"],
        },
      },
      {
        interactionType: InteractionType.Redirect,
        protectedResourceMap: new Map([
          ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ]),
      }
    ),
  ],
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MsalInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent, MsalRedirectComponent],
})
export class AppModule {}

Próxima etapa

• Chamando uma API Web.