通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Static Web Apps 中的自定义身份验证

  • 项目

Azure Static Web Apps 提供托管身份验证，此身份验证方法使用 Azure 管理的提供程序注册。 为了实现比该注册更高的灵活性，可使用自定义注册替代默认设置。

  • 自定义身份验证还允许配置支持 OpenID Connect 的自定义提供程序。 此配置允许注册多个外部提供程序。

  • 使用任何自定义注册会禁用所有预配置的提供程序。

注意

只能在 Azure Static Web Apps 标准计划中使用自定义身份验证。

配置自定义标识提供程序

在auth配置文件的 部分中配置自定义标识提供程序。

为了避免在源代码管理中添加机密，配置将在配置文件的应用程序设置中查找匹配的名称。 你还可以选择将机密存储在 Azure 密钥保管库中。

要创建注册，请首先创建以下应用程序设置：

设置名称 “值”
AZURE_CLIENT_ID Microsoft Entra 应用注册的应用程序（客户端）ID。
`AZURE_CLIENT_SECRET_APP_SETTING_NAME 包含 Microsoft Entra 应用注册的客户端密码的应用程序设置的名称。

接下来，使用以下示例在配置文件中配置提供程序。

Microsoft Entra 提供程序有两个不同的版本。 版本 1 显式定义了 userDetailsClaim，它允许有效负载返回用户信息。 相比之下，版本 2 默认返回用户信息，并由 openIdIssuer URL 中的 v2.0 指定。

Microsoft Entra 版本 1

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

请确保将 <TENANT_ID> 替换为你的 Microsoft Entra 租户 ID。

Microsoft Entra 版本 2

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

请确保将 <TENANT_ID> 替换为你的 Microsoft Entra 租户 ID。

有关如何配置 Microsoft Entra ID 的详细信息，请参阅有关使用现有注册的应用服务身份验证/授权文档。

若要配置哪些帐户可以登录，请参阅修改应用程序支持的帐户和将 Microsoft Entra 应用限制为 Microsoft Entra 租户中的一组用户。

注意

虽然 Microsoft Entra ID 的配置部分是 azureActiveDirectory，但平台在用于登录、注销和清除用户信息的 URL 中将它别名为 aad。 有关详细信息，请参阅身份验证和授权部分。

自定义证书

使用以下步骤将自定义证书添加到 Microsoft Entra ID 应用注册。

  1. 将证书上传到 Microsoft 密钥保管库（如果尚未上传）。

  2. 在静态 Web 应用中添加托管标识。

    对于用户分配的托管标识，请将静态站点对象上的 keyVaultReferenceIdentity 属性设置为用户分配的托管标识的 resourceId。

    如果你的托管标识是系统分配的，请跳过此步骤。

  3. 为托管标识授予以下访问策略：

    • 机密：获取/列出
    • 证书：获取/列出

  4. 使用 clientSecretCertificateKeyVaultReference 值更新 azureActiveDirectory 配置部分的 auth config 部分，如以下示例所示：

    {
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/common/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)",
          "clientSecretCertificateThumbprint": "*"
        }
      }
    }
  }
}

    请确保将 <> 括住的占位符替换为你自己的值。

    在机密 URI 中，指定密钥保管库名称和证书名称。 如果你要关联到某个版本，请包含证书版本，否则请省略版本，以允许在运行时选择最新的证书版本。

    将 clientSecretCertificateThumbprint 设置为等于 *，以始终拉取最新的证书指纹版本。

身份验证回调

标识提供程序需使用重定向 URL 来完成登录或注销请求。 大多数提供程序都要求将回调 URL 添加到允许列表。 以下终结点可用作重定向目标。

类型 URL 模式
登录 https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback
Logout https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback

如果使用的是 Microsoft Entra ID，请使用 aad 作为 <PROVIDER_NAME_IN_CONFIG> 占位符的值。

注意

这些 URL 由 Azure Static Web Apps 提供，以便用来接收身份验证提供程序的响应，你无需在这些路由中创建页面。

登录、注销和用户详细信息

要使用自定义标识提供程序，请使用以下 URL 模式。

操作 模式
登录 /.auth/login/<PROVIDER_NAME_IN_CONFIG>
Logout /.auth/logout
用户详细信息 /.auth/me
清除用户详细信息 /.auth/purge/<PROVIDER_NAME_IN_CONFIG>

如果使用的是 Microsoft Entra ID，请使用 aad 作为 <PROVIDER_NAME_IN_CONFIG> 占位符的值。

管理角色

访问静态 Web 应用的每个用户都属于一个或多个角色。 用户可以属于两个内置角色：

  • 匿名：所有用户都自动属于“匿名”角色。
  • 已通过身份验证：已登录的所有用户都属于“已通过身份验证”角色。

除了内置角色以外，还可向用户分配自定义角色，并在 staticwebapp.config.json 文件中引用这些角色。

将用户添加到角色

若要将用户添加到角色，请生成允许将用户关联到特定角色的邀请。 角色在 staticwebapp.config.json 文件中定义和维护。

创建邀请

邀请特定于单个授权提供程序，因此，在选择要支持的提供程序时，请考虑应用的需求。 某些提供程序公开用户的电子邮件地址，而其他提供程序仅提供站点的用户名。

授权提供程序 公开
Microsoft Entra ID 电子邮件地址
GitHub username
X username

使用以下步骤来创建邀请。

  1. 在 Azure 门户中转到静态 Web 应用资源。
  2. 在“设置”下面，选择“角色管理”。
  3. 选择“邀请”。
  4. 从选项列表中选择“授权提供程序”。
  5. 在“被邀请者详细信息”框中添加收件人的用户名或电子邮件地址。
    • 对于 GitHub 和 X，请输入用户名。 对于所有其他工具，输入收件人的电子邮件地址。
  6. 从“域”下拉菜单中选择静态站点的域。
    • 你选择的域是在邀请中显示的域。 如果有与站点关联的自定义域，请选择该自定义域。
  7. 在“角色”框中添加以逗号分隔的角色名称列表。
  8. 输入希望邀请保持有效的最大小时数。
    • 可能的最大限制为 168 小时，即 7 天。
  9. 然后选择“生成” 。
  10. 从“邀请链接”框中复制链接。
  11. 将邀请链接通过电子邮件方式发送给你向其授予访问权限的用户。

当用户选择邀请中的链接时，系统会提示其使用相应帐户登录。 成功登录后，用户将与所选角色关联。

注意

请确保路由规则不会与所选的身份验证提供程序冲突。 使用路由规则阻止提供程序会阻止用户接受邀请。

更新角色分配

  1. 在 Azure 门户中转到静态 Web 应用资源。
  2. 在“设置”下面，选择“角色管理”。
  3. 在列表中选择一个用户。
  4. 在“角色”框中编辑角色的列表。
  5. 选择“更新”。

删除用户

  1. 在 Azure 门户中转到静态 Web 应用资源。
  2. 在“设置”下面，选择“角色管理”。
  3. 在列表中找到该用户。
  4. 选中用户行上的复选框。
  5. 选择“删除” 。

删除用户时，请记住以下事项：

  • 删除用户会使其权限失效。
  • 全球传播可能需要几分钟时间。
  • 如果用户已重新添加到应用，则 userId 会发生更改。

后续步骤

以编程方式设置用户角色