MSAL2 提供程序

  • 项目

MSAL2 提供程序使用 MSAL 浏览器 登录用户，并获取用于 Microsoft Graph 的令牌。

若要了解详细信息，请参阅 提供程序。

MSAL2 提供程序与 MSAL 提供程序之间的差异

尽管用法类似，但 MSAL 提供程序和 MSAL2 提供程序基于不同的 OAuth 流构建。 MSAL 提供程序基于 msal.js，该提供程序实现 OAuth2.0 隐式授予流。 MSAL2 提供程序基于 MSAL 浏览器构建，该浏览器使用 PKCE 实现 OAuth 2.0 授权代码流 。 由于授权代码流被认为比 Web 应用程序的隐式授权流更安全，因此我们建议使用 Msal2Provider 而不是 MsalProvider。 有关与隐式授予流相关的安全问题的详细信息，请参阅 隐式授予流的缺点。

所有新应用程序都应尽可能使用 MSAL2 提供程序。

入门

可以在 HTML 或 JavaScript 中初始化 MSAL2 提供程序。

在 HTML 页中初始化

初始化 HTML 格式的 MSAL2 提供程序是创建新提供程序的最简单方法。 mgt-msal2-provider使用 组件设置客户端 ID 和其他属性。 这会创建一个新 PublicClientApplication 实例，用于所有身份验证和获取令牌。

    <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>
属性 说明
client-id 字符串客户端 ID (请参阅创建应用/客户端 ID) 。 必填。
login-type 和 popup 之间的redirect枚举 - 默认值为 redirect。 可选。
scopes 用户登录时必须同意的范围的逗号分隔字符串。 可选。
custom-hosts Microsoft Graph 客户端可以调用的其他域的逗号分隔字符串。 可选。
权威 颁发机构字符串 - 默认为公共颁发机构。 对于单租户应用，请使用租户 ID 或租户名称。 例如，https://login.microsoftonline.com/[your-tenant-contoso.com 或 https://login.microsoftonline.com/[your-tenant-id]。 可选。
redirect-uri 重定向 URI 字符串 - 默认使用当前窗口 URI。 可选。
提示 在 和 CONSENTLOGIN之间SELECT_ACCOUNT用于登录的提示类型。 默认值为“SELECT_ACCOUNT”。 可选。
base-url 用于 Microsoft Graph 调用的 Microsoft Graph 终结点。 它可以是任何受支持的 国家/地区云部署。 默认值为 https://graph.microsoft.com。
incremental-consent-disabled 指定是否禁用增量同意。 默认 false。 可选。

在 JavaScript 中初始化

可以通过在 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);

可以通过两种方式配置 Msal2Provider 构造函数参数，如以下部分所述。

clientId提供 以创建新PublicClientApplication

当 Microsoft Graph 工具包负责应用程序中的所有身份验证时，此选项有意义。

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
}

传递 属性中的publicClientApplication现有 PublicClientApplication 。

当你的应用使用 MSAL 功能（超出 和 Microsoft Graph 工具包公开的功能） Msal2Provider 时，请使用此功能。 如果框架自动实例化并公开 PublicClientApplication ，则这很合适;例如，在使用 MSAL-angular 时。 有关详细信息，请参阅 angular-app Microsoft Graph 工具包 存储库中的示例。

使用此选项时，请务必了解发生冲突的机会。 就其本质而言，存在更改会话状态的风险 Msal2Provider ;例如，让用户登录或同意其他范围。 确保应用和其他框架对状态中的这些更改做出正常响应，或者考虑改用 自定义提供程序 。

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
}

使用不同的云终结点

若要使用工具包呈现来自其他 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);

或者：

<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>

若要调用自定义 API，请请求该 API 范围。

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

或通过 Javascript/Typescript

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

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

使用自定义主机调用不同的Microsoft Entra ID保护终结点

如果要调用自己的自定义Microsoft Entra ID安全终结点，请将这些域传递给基础 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);

或者：

<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>

创建应用/客户端 ID

有关如何注册应用和获取客户端 ID 的详细信息，请参阅创建Microsoft Entra应用。

从 MSAL 提供程序迁移到 MSAL2 提供程序

若要将使用 MSAL 提供程序的应用程序迁移到 MSAL2 提供程序，请执行以下操作：

  1. 转到Microsoft Entra 管理中心。

  2. 展开“标识”菜单>，展开“应用程序>”，选择“应用注册”。

  3. 选择要迁移的应用的应用注册。

  4. 转到左侧菜单中的 “身份验证 ”。

  5. 在“ 平台配置”下，选择“ 添加平台 ”，然后选择“ 单页应用程序”。

  6. 删除当前已在 Web 下注册的所有重定向 URI，并改为将它们添加到 单页应用程序下。

  7. 在代码中，将 替换为 MSALProviderMSAL2Provider。

    如果要在 JS/TS 代码中初始化提供程序，请执行以下步骤：

    将 的 mgt-MSAL-provider import 语句替换为

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

    将 MsalProvider 的初始化替换为

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

    如果要以 HTML 格式初始化提供程序，请替换

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

    与

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

    有关详细信息，请参阅 在 HTML 页中初始化。