Provedor MSAL2

  • Artigo

O Provedor MSAL2 usa o navegador MSAL para entrar usuários e adquirir tokens a serem usados com o Microsoft Graph.

Para saber mais, confira provedores.

Diferença entre o provedor MSAL2 e o provedor MSAL

Embora o uso seja semelhante, o Provedor MSAL e o Provedor MSAL2 são criados em fluxos OAuth diferentes. O Provedor MSAL é criado em msal.js, que implementa o Fluxo de Concessão Implícita OAuth2.0. O Provedor MSAL2 é criado no navegador MSAL, que implementa o Fluxo de Código de Autorização do OAuth 2.0 com o PKCE. Como o Fluxo de Código de Autorização é considerado mais seguro do que o Fluxo de Concessão Implícita para aplicativos Web, recomendamos usar Msal2Provider em MsalProvider. Para obter detalhes sobre problemas de segurança relacionados ao fluxo de concessão implícito, consulte Desvantagens do fluxo implícito.

Todos os novos aplicativos devem usar o Provedor MSAL2 sempre que possível.

Introdução

Você pode inicializar o Provedor MSAL2 em HTML ou JavaScript.

Inicializar em sua página HTML

Inicializar o provedor MSAL2 em HTML é a maneira mais simples de criar um novo provedor. Use o mgt-msal2-provider componente para definir a id do cliente e outras propriedades. Isso cria uma nova PublicClientApplication instância que é usada para todos os tokens de autenticação e aquisição.

    <mgt-msal2-provider client-id="<YOUR_CLIENT_ID>"
                        login-type="redirect/popup"
                        scopes="user.read,people.read"
                        redirect-uri="https://my.redirect/uri"
                        authority="">
    </mgt-msal2-provider>
Atributo Descrição
client-id ID do cliente de cadeia de caracteres (consulte Criando uma ID de aplicativo/cliente). Obrigatório.
tipo de logon Enumeração entre redirect e popup – o valor padrão é redirect. Opcional.
escopos Cadeias de caracteres separadas por vírgulas para escopos aos quais o usuário deve consentir quando entrar. Opcional.
hosts personalizados Cadeias de caracteres separadas por vírgulas para domínios adicionais que o cliente do Microsoft Graph pode chamar. Opcional.
Autoridade Cadeia de caracteres de autoridade – padrão é a autoridade comum. Para aplicativos de locatário único, use a ID do locatário ou o nome do locatário. Por exemplo: https://login.microsoftonline.com/[your-tenant-contoso.com ou https://login.microsoftonline.com/[your-tenant-id]. Opcional.
redirecionamento-uri Cadeia de caracteres URI de redirecionamento – por padrão, o URI da janela atual é usado. Opcional.
prompt Tipo de prompt a ser usado para logon, entre SELECT_ACCOUNTe CONSENTLOGIN. O padrão é SELECT_ACCOUNT. Opcional.
url base O ponto de extremidade do Microsoft Graph a ser usado para chamadas do Microsoft Graph. Pode ser qualquer uma das implantações de nuvem nacionais com suporte. O valor padrão é https://graph.microsoft.com.
incremental-consent-disabled Especifica se o consentimento incremental está desabilitado. Padrão false. Opcional.

Inicializar no JavaScript

Você pode fornecer mais opções inicializando o provedor no JavaScript.

    import {Providers} from '@microsoft/mgt-element';
    import {Msal2Provider, Msal2Config, Msal2PublicClientApplicationConfig} from '@microsoft/mgt-msal2-provider';

    // initialize the auth provider globally
    Providers.globalProvider = new Msal2Provider(config: Msal2Config | Msal2PublicClientApplicationConfig);

Você pode configurar o Msal2Provider parâmetro de construtor de duas maneiras, conforme descrito nas seções a seguir.

Fornecer um clientId para criar um novo PublicClientApplication

Essa opção faz sentido quando o Kit de Ferramentas do Microsoft Graph é responsável por toda a autenticação em seu aplicativo.

interface Msal2Config {
  clientId: string;
  scopes?: string[];
  customHosts?: string[];
  authority?: string;
  redirectUri?: string;
  loginType?: LoginType; // LoginType.Popup or LoginType.Redirect (redirect is default)
  prompt?: PromptType; // PromptType.CONSENT, PromptType.LOGIN or PromptType.SELECT_ACCOUNT
  sid?: string; // Session ID
  loginHint?: string;
  domainHint?: string;
  isIncrementalConsentDisabled?: boolean, //Disable incremental consent, true by default
  options?: Configuration // msal-browser Configuration object
}

Passe um existente PublicClientApplication na publicClientApplication propriedade.

Use isso quando seu aplicativo usar a funcionalidade MSAL além do que é exposto pelos recursos do Kit de Ferramentas do Msal2Provider Microsoft Graph. Isso é apropriado se uma estrutura instanciar e expor automaticamente uma PublicClientApplication para você; por exemplo, ao usar MSAL-angular. Para obter mais informações, confira o angular-app exemplo no repositório kit de ferramentas do Microsoft Graph.

Certifique-se de entender as oportunidades de colisões ao usar essa opção. Por sua própria natureza, há o risco de que o Msal2Provider pode alterar o estado de uma sessão; por exemplo, fazendo com que o usuário entre ou consenta em escopos adicionais. Certifique-se de que seu aplicativo e outras estruturas respondam normalmente a essas alterações no estado ou considere usar um provedor personalizado .

interface Msal2PublicClientApplicationConfig {
  publicClientApplication: PublicClientApplication;
  scopes?: string[];
  customHosts?: string[];
  authority?: string;
  redirectUri?: string;
  loginType?: LoginType; // LoginType.Popup or LoginType.Redirect (redirect is default)
  prompt?: PromptType; // PromptType.CONSENT, PromptType.LOGIN or PromptType.SELECT_ACCOUNT
  sid?: string; // Session ID
  loginHint?: string;
  domainHint?: string;
  isIncrementalConsentDisabled?: boolean, //Disable incremental consent, true by default
  options?: Configuration // msal-browser Configuration object
}

Usar um ponto de extremidade de nuvem diferente

Use isso quando quiser usar o kit de ferramentas para renderizar seus dados de um ponto de extremidade diferente do Microsoft 365.

import {Providers, Msal2Provider} from '@microsoft/mgt'

const config: Msal2Config = {
  baseUrl: 'https://graph.microsoft.us', // change the base URL
  clientId: '2dfea037-xxx-c05708a1b241',
  ... // rest of the config
}

Providers.globalProvider = new Msal2Provider(config);

Alternativamente:

<mgt-msal2-provider
      client-id="2dfea037-xxx-c05708a1b241"
      redirect-uri="http://localhost:3000"
      base-url="https://dod-graph.microsoft.us"
      scopes="user.read,user.read.all">
</mgt-msal2-provider>

Para chamar as APIs personalizadas, solicite esse escopo de API.

<mgt-get resource="https://myapi.com/v1.0/api" scopes="api://CUSTOM_API_GUID/SCOPE">
  ...
</mgt-get>

ou via Javascript/Typescript

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("https://myapi.com/v1.0/api")
  .middlewareOptions(prepScopes("api://CUSTOM_API_GUID/SCOPE"))
  .get();
...

Usar hosts personalizados para chamar diferentes pontos de extremidade protegidos por Microsoft Entra ID

Se você quiser chamar seus próprios pontos de extremidade personalizados Microsoft Entra ID protegidos, passe esses domínios para o cliente subjacente do Microsoft Graph.

import {Providers, Msal2Provider} from '@microsoft/mgt'

const config: Msal2Config = {
  clientId: '2dfea037-xxx-c05708a1b241',
  customHosts: ['mydomain.com'] //array of domains, not urls!
  ... // rest of the config
}

Providers.globalProvider = new Msal2Provider(config);

Alternativamente:

<mgt-msal2-provider
      client-id="2dfea037-xxx-c05708a1b241"
      redirect-uri="http://localhost:3000"
      custom-hosts="mydomain.com"
      scopes="user.read,user.read.all">
</mgt-msal2-provider>

Criando uma ID de aplicativo/cliente

Para obter detalhes sobre como registrar um aplicativo e obter uma ID do cliente, consulte Criar um aplicativo Microsoft Entra.

Migrando do Provedor MSAL para o Provedor MSAL2

Para migrar um aplicativo que está usando o provedor MSAL para o Provedor MSAL2:

  1. Vá para o centro de administração do Microsoft Entra.

  2. Expanda o menu > Identidade expanda Aplicativos> selecione Registros de aplicativo.

  3. Selecione o registro do aplicativo para migrar.

  4. Vá para Autenticação no menu à esquerda.

  5. Em Configurações de plataforma, selecione em Adicionar uma plataforma e selecione Aplicativo de página única.

  6. Remova todas as URIs de redirecionamento que você registrou atualmente na Web e, em vez disso, adicione-as em aplicativo de página única.

  7. No código, substitua por MSALProviderMSAL2Provider.

    Se você estiver inicializando seu provedor no código JS/TS, siga estas etapas:

    Substituir a instrução de importação por mgt-MSAL-provider por

    import {Msal2Provider, PromptType} from '@microsoft/mgt-msal2-provider';

    Substituir a inicialização do MsalProvider por

    Providers.globalProvider = new Msal2Provider({
  clientId: 'REPLACE_WITH_CLIENTID'
  ...
})

    Se você estiver inicializando o provedor em HTML, substitua

    <mgt-msal-provider client-id="" ... ></mgt-msal-provider>

    Com

    <mgt-msal2-provider  client-id="" ... ></mgt-msal2-provider>

    Para obter detalhes, consulte Inicializar em sua página HTML.