使用英语阅读

通过


MSAL2 提供程序

MSAL2 提供程序基于 MSAL 浏览器 构建,该浏览器使用 PKCE 实现 OAuth 2.0 授权代码流 。 它用于登录用户并获取用于 Microsoft Graph 的令牌。

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

入门

可以在 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.comhttps://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 功能(超出 和 Graph 工具包的其他Microsoft公开 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 页中初始化