为你的 .NET Core (Blazor WASM) 应用添加认证 (Authentication)

提示:

以下演示基于 .NET Core 8.0 和 Blorc.OpenIdConnect。
.NET Core 示例项目可在 GitHub 仓库中找到。

前提条件

一个 Logto Cloud 账户或一个自托管 Logto。
一个已创建的 Logto 单页应用。

安装

将 NuGet 包添加到你的项目中：

dotnet add package Blorc.OpenIdConnect

集成

添加脚本引用

在 index.html 文件中包含 Blorc.Core/injector.js：

index.html
<head>
  <!-- ... -->
  <script src="_content/Blorc.Core/injector.js"></script>
  <!-- ... -->
</head>

注册服务

将以下代码添加到 Program.cs 文件中：

Program.cs
using Blorc.OpenIdConnect;
using Blorc.Services;

builder.Services.AddBlorcCore();
builder.Services.AddAuthorizationCore();
builder.Services.AddBlorcOpenIdConnect(
    options =>
    {
        builder.Configuration.Bind("IdentityServer", options);
    });

var webAssemblyHost = builder.Build();

await webAssemblyHost
    .ConfigureDocumentAsync(async documentService =>
    {
        await documentService.InjectBlorcCoreJsAsync();
        await documentService.InjectOpenIdConnectAsync();
    });

await webAssemblyHost.RunAsync();

信息:

无需使用 Microsoft.AspNetCore.Components.WebAssembly.Authentication 包。Blorc.OpenIdConnect 包将负责认证过程。

配置重定向 URI

在我们深入细节之前，下面是终端用户体验的快速概览。登录流程可以简化为如下：

你的应用调用登录方法。
用户被重定向到 Logto 登录页面。对于原生应用，会打开系统浏览器。
用户完成登录后被重定向回你的应用（配置为重定向 URI）。

此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议，Logto 强制执行严格的安全措施以保护用户登录。
如果你有多个应用程序，可以使用相同的身份提供商 (IdP)（日志 (Logto)）。一旦用户登录到一个应用程序，当用户访问另一个应用程序时，Logto 将自动完成登录过程。

要了解有关基于重定向的登录的原理和好处的更多信息，请参阅 Logto 登录体验解释。

备注:

在以下代码片段中，我们假设你的应用程序运行在 http://localhost:3000/。

配置重定向 URI

切换到 Logto Console 的应用详情页面。添加一个重定向 URI http://localhost:3000/callback。

就像登录一样，用户应该被重定向到 Logto 以注销共享会话。完成后，最好将用户重定向回你的网站。例如，添加 http://localhost:3000/ 作为注销后重定向 URI 部分。

然后点击“保存”以保存更改。

配置应用程序

将以下代码添加到 appsettings.json 文件中：

appsettings.json
{
// ...
IdentityServer: {
  Authority: 'https://<your-logto-endpoint>/oidc',
  ClientId: '<your-logto-app-id>',
  PostLogoutRedirectUri: 'http://localhost:3000/',
  RedirectUri: 'http://localhost:3000/callback',
  ResponseType: 'code',
  Scope: 'openid profile', // 如有需要可添加更多 scopes
},
}

记得将 RedirectUri 和 PostLogoutRedirectUri 添加到 Logto 应用程序设置中允许的重定向 URI 列表中。它们都是你的 WASM 应用程序的 URL。

添加 `AuthorizeView` 组件

在需要认证的 Razor 页面中，添加 AuthorizeView 组件。假设是在 Home.razor 页面：

Pages/Home.razor
@using Microsoft.AspNetCore.Components.Authorization
@page "/"

<AuthorizeView>
    <Authorized>
        @* 已登录视图 *@
        <button @onclick="OnLogoutButtonClickAsync">
            Sign out
        </button>
    </Authorized>
    <NotAuthorized>
        @* 未认证视图 *@
        <button @onclick="OnLoginButtonClickAsync">
            Sign in
        </button>
    </NotAuthorized>
</AuthorizeView>

设置认证

在 Home.razor.cs 文件中（如果不存在则创建），添加以下代码：

Pages/Home.razor.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;
using Blorc.OpenIdConnect;
using Microsoft.AspNetCore.Components.Authorization;

[Authorize]
public partial class Home : ComponentBase
{
    [Inject]
    public required IUserManager UserManager { get; set; }

    public User<Profile>? User { get; set; }

    [CascadingParameter]
    protected Task<AuthenticationState>? AuthenticationStateTask { get; set; }

    protected override async Task OnInitializedAsync()
    {
        User = await UserManager.GetUserAsync<User<Profile>>(AuthenticationStateTask!);
    }

    private async Task OnLoginButtonClickAsync(MouseEventArgs obj)
    {
        await UserManager.SignInRedirectAsync();
    }

    private async Task OnLogoutButtonClickAsync(MouseEventArgs obj)
    {
        await UserManager.SignOutRedirectAsync();
    }
}

一旦用户通过认证，User 属性将被填充用户信息。

检查点：测试你的应用程序

现在，你可以测试你的应用程序：

运行你的应用程序，你将看到登录按钮。
点击登录按钮，SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
登录后，你将被重定向回你的应用程序，并看到登出按钮。
点击登出按钮以清除令牌存储并登出。

获取用户信息

显示用户信息

以下是在 Home.razor 页面中显示用户信息的一些示例：

<AuthorizeView>
    <Authorized>
        @* 登录视图 *@
        @* ... *@
        <p>你已登录为 @(@User?.Profile?.Name ?? "(unknown name)").</p>
    </Authorized>
    @* ... *@
</AuthorizeView>

有关更多属性和声明，请查看 Blorc.OpenIdConnect 包中的 User 和 Profile 类。

请求额外的声明

你可能会发现从 User 返回的对象中缺少一些用户信息。这是因为 OAuth 2.0 和 OpenID Connect (OIDC) 的设计遵循最小权限原则 (PoLP)，而 Logto 是基于这些标准构建的。

默认情况下，返回的声明（Claim）是有限的。如果你需要更多信息，可以请求额外的权限（Scope）以访问更多的声明（Claim）。

信息:

“声明（Claim）”是关于主体的断言；“权限（Scope）”是一组声明。在当前情况下，声明是关于用户的一条信息。

以下是权限（Scope）与声明（Claim）关系的非规范性示例：

提示:

“sub” 声明（Claim）表示“主体（Subject）”，即用户的唯一标识符（例如用户 ID）。

Logto SDK 将始终请求三个权限（Scope）：openid、profile 和 offline_access。

要请求额外的权限，你可以在 appsettings.json 文件中的 IdentityServer.Scope 属性中添加有效的权限。

{
  // ...
  "IdentityServer": {
    // ...
    "Scope": "openid profile email phone"
  }
}

需要网络请求的声明

为了防止用户对象膨胀，某些声明需要通过网络请求获取。例如，即使在权限中请求了 custom_data 声明，它也不会包含在用户对象中。要获取这些声明，你可以在 appsettings.json 文件中将 IdentityServer.LoadUserInfo 属性设置为 true。

例如，要获取用户的电子邮件地址和自定义数据，你可以使用以下配置：

{
  // ...
  "IdentityServer": {
    // ...
    "Scope": "openid profile email custom_data",
    "LoadUserInfo": true
  }
}

权限和声明

Logto 使用 OIDC 权限和声明约定来定义从 ID 令牌和 OIDC 用户信息端点检索用户信息的权限和声明。“权限”和“声明”都是 OAuth 2.0 和 OpenID Connect (OIDC) 规范中的术语。

以下是支持的权限 (Scopes) 列表及其对应的声明 (Claims)：

openid

Claim name	Type	描述	需要 userinfo 吗？
sub	`string`	用户的唯一标识符	否

profile

Claim name	Type	描述	需要 userinfo 吗？
name	`string`	用户的全名	否
username	`string`	用户名	否
picture	`string`	终端用户头像的 URL。该 URL 必须指向图片文件（如 PNG、JPEG 或 GIF），而不是包含图片的网页。注意，该 URL 应专门指向适合在描述终端用户时展示的头像，而不是终端用户拍摄的任意照片。	否
created_at	`number`	终端用户的创建时间。该时间以自 Unix 纪元（1970-01-01T00:00:00Z）以来的毫秒数表示。	否
updated_at	`number`	终端用户信息最后更新时间。该时间以自 Unix 纪元（1970-01-01T00:00:00Z）以来的毫秒数表示。	否

其他标准声明 (Claims) 包括 family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo 和 locale 也会包含在 profile 权限 (Scope) 中，无需请求 userinfo 端点。与上表声明 (Claims) 不同的是，这些声明 (Claims) 只有在值不为空时才会返回，而上表中的声明 (Claims) 如果值为空则会返回 null。

备注:

与标准声明 (Claims) 不同，created_at 和 updated_at 声明 (Claims) 使用的是毫秒而不是秒。

email

Claim name	Type	描述	需要 userinfo 吗？
email	`string`	用户的电子邮件地址	否
email_verified	`boolean`	电子邮件地址是否已验证	否

phone

Claim name	Type	描述	需要 userinfo 吗？
phone_number	`string`	用户的电话号码	否
phone_number_verified	`boolean`	电话号码是否已验证	否

address

关于 address 声明 (Claim) 的详细信息，请参阅 OpenID Connect Core 1.0。

custom_data

Claim name	Type	描述	需要 userinfo 吗？
custom_data	`object`	用户的自定义数据	是

identities

Claim name	Type	描述	需要 userinfo 吗？
identities	`object`	用户关联的身份信息	是
sso_identities	`array`	用户关联的 SSO 身份信息	是

roles

Claim name	Type	描述	需要 userinfo 吗？
roles	`string[]`	用户的角色 (Roles)	否

urn:logto:scope:organizations

Claim name	Type	描述	需要 userinfo 吗？
organizations	`string[]`	用户所属的组织 (Organizations) ID 列表	否
organization_data	`object[]`	用户所属的组织 (Organizations) 数据	是

备注:

这些组织 (Organizations) 声明 (Claims) 也可以通过 userinfo 端点获取，当使用不透明令牌 (Opaque token) 时也是如此。然而，不透明令牌 (Opaque tokens) 不能作为组织令牌 (Organization tokens) 用于访问组织专属资源。详情请参见不透明令牌 (Opaque token) 与组织 (Organizations)。

urn:logto:scope:organization_roles

Claim name	Type	描述	需要 userinfo 吗？
organization_roles	`string[]`	用户所属组织 (Organizations) 的角色 (Roles)，格式为 `<organization_id>:<role_name>`	否

考虑到性能和数据大小，如果“需要 userinfo 吗？”为“是”，则该声明 (Claim) 不会出现在 ID 令牌 (ID token) 中，而会在 userinfo 端点响应中返回。

API 资源

我们建议首先阅读 🔐 基于角色的访问控制 (RBAC)，以了解 Logto RBAC 的基本概念以及如何正确设置 API 资源。

默认情况下，当你访问 User?.AccessToken 时，你会获得一个不透明令牌 (Opaque token)，它长度较短，并且不是 JWT (JSON Web Token)。该令牌用于访问 userinfo 端点。

将 API 资源添加到配置中

为了获取可用于访问在 Logto 中定义的 API 资源的 JWT，你需要在 appsettings.json 文件中添加以下参数（以 https://my-api-resource 为例）：

appsettings.json
{
  // ...
  "IdentityServer": {
    // ...
    "Scope": "openid profile email <your-api-scopes>", // 在此处添加你的 API 权限 (Scopes)
    "Resource": "https://my-api-resource",
    "ExtraTokenParams": {
        "resource": "https://my-api-resource" // 确保键 "resource" 为小写
    }
  }
}

Resource 属性用于将 API 资源添加到认证请求 (Authentication request) 中。ExtraTokenParams 属性用于将 API 资源添加到令牌请求 (Token request) 中。由于 Logto 遵循 RFC 8707 关于 API 资源的规范，因此这两个属性都是必需的。

警告:

由于 WebAssembly 是客户端应用程序，令牌请求 (Token request) 只会发送到服务器端一次。基于这一特性，LoadUserInfo 与为 API 资源获取访问令牌 (Access token) 存在冲突。

使用访问令牌 (Access token)

一旦用户通过认证 (Authentication)，你就可以通过 User?.AccessToken 属性访问 API 资源。例如，你可以使用 HttpClient 访问 API 资源：

using Blorc.OpenIdConnect;

builder.Services
    .AddHttpClient("MyApiResource", client =>
    {
        client.BaseAddress = new Uri("https://my-api-resource");
    })
    .AddAccessToken(); // 将访问令牌 (Access token) 添加到请求头

延伸阅读

终端用户流程：认证 (Authentication) 流程、账户流程和组织流程配置连接器 (Connectors) 授权 (Authorization)

前提条件​

安装​

集成​

添加脚本引用​

注册服务​

配置重定向 URI​

关于基于重定向的登录​

配置重定向 URI​

配置应用程序​

添加 AuthorizeView 组件​

设置认证​

检查点：测试你的应用程序​

获取用户信息​

显示用户信息​

请求额外的声明​

需要网络请求的声明​

权限和声明​

API 资源​

将 API 资源添加到配置中​

使用访问令牌 (Access token)​

延伸阅读​

前提条件

安装

集成

添加脚本引用

注册服务

配置重定向 URI

关于基于重定向的登录

配置重定向 URI

配置应用程序

添加 `AuthorizeView` 组件

设置认证

检查点：测试你的应用程序

获取用户信息

显示用户信息

请求额外的声明

需要网络请求的声明

权限和声明

API 资源

将 API 资源添加到配置中

使用访问令牌 (Access token)

延伸阅读