Proveedor MSAL2

  • Artículo

El proveedor MSAL2 usa MSAL-browser para iniciar sesión a los usuarios y adquirir tokens para usarlos con Microsoft Graph.

Para obtener más información, consulte proveedores.

Diferencia entre el proveedor MSAL2 y el proveedor MSAL

Aunque el uso es similar, el proveedor MSAL y el proveedor MSAL2 se basan en diferentes flujos de OAuth. El proveedor MSAL se basa en msal.js, que implementa el flujo de concesión implícita de OAuth2.0. El proveedor MSAL2 se basa en MSAL-browser, que implementa el flujo de código de autorización de OAuth 2.0 con PKCE. Dado que el flujo de código de autorización se considera más seguro que el flujo de concesión implícito para aplicaciones web, se recomienda usar Msal2Provider sobre MsalProvider. Para obtener más información sobre los problemas de seguridad relacionados con el flujo de concesión implícita, consulte Desventajas del flujo implícito.

Todas las aplicaciones nuevas deben usar el proveedor MSAL2 siempre que sea posible.

Introducción

Puede inicializar el proveedor MSAL2 en HTML o JavaScript.

Inicializar en la página HTML

Inicializar el proveedor MSAL2 en HTML es la manera más sencilla de crear un nuevo proveedor. Use el mgt-msal2-provider componente para establecer el id. de cliente y otras propiedades. Esto crea una nueva PublicClientApplication instancia que se usa para toda la autenticación y la adquisición de tokens.

    <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 Description
client-id Identificador de cliente de cadena (consulte Creación de un identificador de aplicación o cliente). Obligatorio.
login-type Enumeración entre redirect y popup : el valor predeterminado es redirect. Opcional.
ámbitos Cadenas separadas por comas para ámbitos a los que el usuario debe dar su consentimiento cuando inicia sesión. Opcional.
hosts personalizados Cadenas separadas por comas para dominios adicionales a los que el cliente de Microsoft Graph puede llamar. Opcional.
Autoridad Cadena de autoridad: el valor predeterminado es la autoridad común. En el caso de las aplicaciones de inquilino único, use el identificador de inquilino o el nombre del inquilino. Por ejemplo, https://login.microsoftonline.com/[your-tenant-contoso.com o https://login.microsoftonline.com/[your-tenant-id]. Opcional.
redirect-uri Cadena de URI de redirección: se usa de forma predeterminada el URI de ventana actual. Opcional.
aviso Tipo de símbolo del sistema que se va a usar para el inicio de sesión, entre SELECT_ACCOUNTy CONSENTLOGIN. El valor predeterminado es SELECT_ACCOUNT. Opcional.
base-url Punto de conexión de Microsoft Graph que se usará para las llamadas de Microsoft Graph. Puede ser cualquiera de las implementaciones de nube nacionales admitidas. El valor predeterminado es https://graph.microsoft.com.
incremental-consent-disabled Especifica si el consentimiento incremental está deshabilitado. Valor predeterminado falsede . Opcional.

Inicialización en JavaScript

Puede proporcionar más opciones inicializando el proveedor en 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);

Puede configurar el parámetro del Msal2Provider constructor de dos maneras, como se describe en las secciones siguientes.

Proporcionar un clientId para crear un nuevo PublicClientApplication

Esta opción tiene sentido cuando Microsoft Graph Toolkit es responsable de toda la autenticación de la aplicación.

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
}

Pase un existente PublicClientApplication en la publicClientApplication propiedad .

Úsenlo cuando la aplicación use la funcionalidad de MSAL más allá de lo que exponen las Msal2Provider características del kit de herramientas de Microsoft Graph y otras. Esto es adecuado si un marco crea automáticamente una instancia y expone un PublicClientApplication objeto automáticamente; por ejemplo, cuando se usa MSAL-angular. Para obtener más información, consulte el angular-app ejemplo en el repositorio del kit de herramientas de Microsoft Graph.

Asegúrese de comprender las oportunidades de colisiones al usar esta opción. Por su propia naturaleza, existe el riesgo de que pueda cambiar el estado de una sesión; por ejemplo, haciendo que Msal2Provider el usuario inicie sesión o dé su consentimiento a ámbitos adicionales. Asegúrese de que la aplicación y otros marcos de trabajo respondan correctamente a estos cambios en el estado o considere la posibilidad de usar un proveedor personalizado en su lugar.

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
}

Uso de un punto de conexión en la nube diferente

Úselo cuando quiera usar el kit de herramientas para representar los datos de un punto de conexión de Microsoft 365 diferente.

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 llamar a las API personalizadas, solicite ese ámbito de API.

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

o a través de Javascript/Typescript

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

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

Uso de hosts personalizados para llamar a distintos puntos de conexión protegidos Microsoft Entra ID

Si desea llamar a sus propios Microsoft Entra ID puntos de conexión protegidos personalizados, pase esos dominios al cliente de Microsoft Graph subyacente.

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>

Creación de un identificador de aplicación o cliente

Para obtener más información sobre cómo registrar una aplicación y obtener un identificador de cliente, consulte Creación de una aplicación Microsoft Entra.

Migración del proveedor MSAL al proveedor MSAL2

Para migrar una aplicación que usa el proveedor MSAL al proveedor MSAL2:

  1. Ve al Centro de administración Microsoft Entra.

  2. Expanda el menú >Identidad y seleccione Aplicaciones>Registros de aplicaciones.

  3. Seleccione el registro de la aplicación de la aplicación que se va a migrar.

  4. Vaya a Autenticación en el menú de la izquierda.

  5. En Configuraciones de plataforma, seleccione Agregar una plataforma y seleccione Aplicación de página única.

  6. Quite todos los URI de redireccionamiento que ha registrado actualmente en Web y, en su lugar, agréguelos en Aplicación de página única.

  7. En el código, reemplace por MSALProviderMSAL2Provider.

    Si va a inicializar el proveedor en el código JS/TS, siga estos pasos:

    Reemplazar la instrucción import por mgt-MSAL-provider

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

    Reemplazar la inicialización de MsalProvider por

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

    Si va a inicializar el proveedor en HTML, reemplace

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

    Con

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

    Para obtener más información, vea Inicializar en la página HTML.