跳到主要内容

为你的 Angular 应用添加认证 (Authentication)

提示:

前提条件

安装

安装 Logto JS core SDK 和 Angular OIDC 客户端库:

npm i @logto/js angular-auth-oidc-client

集成

配置应用程序

在你的 Angular 项目中,在 app.config.ts 中添加认证 (Authentication) 提供者:

app/app.config.ts
import { buildAngularAuthConfig } from '@logto/js';
import { provideAuth } from 'angular-auth-oidc-client';

export const appConfig: ApplicationConfig = {
providers: [
provideHttpClient(withFetch()),
provideAuth({
config: buildAngularAuthConfig({
endpoint: '<your-logto-endpoint>',
appId: '<your-app-id>',
redirectUri: 'http://localhost:3000/callback',
postLogoutRedirectUri: 'http://localhost:3000/',
}),
}),
// ...other providers
],
};

配置重定向 URI

在我们深入细节之前,这里是终端用户体验的快速概述。登录过程可以简化如下:

  1. 你的应用调用登录方法。
  2. 用户被重定向到 Logto 登录页面。对于原生应用,将打开系统浏览器。
  3. 用户登录并被重定向回你的应用(配置为重定向 URI)。

关于基于重定向的登录

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

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


备注:

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

配置重定向 URI

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

Logto Console 中的重定向 URI

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

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

处理重定向

由于我们使用 http://localhost:3000/callback 作为重定向 URI,现在我们需要正确处理它。angular-auth-oidc-client 库提供了处理重定向的内置支持。你只需正确配置认证 (Authentication) 提供者配置,库将处理其余部分。

app/app.config.ts
export const appConfig: ApplicationConfig = {
providers: [
provideAuth({
config: buildAngularAuthConfig({
// ...other config
redirectUri: 'http://localhost:3000/callback',
postLogoutRedirectUri: 'http://localhost:3000/',
}),
}),
// ...other providers
],
};

实现登录和登出

在你想要实现登录和登出的组件中(例如,app.component.ts),注入 OidcSecurityService 并使用它进行登录和登出。

app/app.component.ts
import { OidcSecurityService } from 'angular-auth-oidc-client';

export class AppComponent implements OnInit {
constructor(public oidcSecurityService: OidcSecurityService) {}

signIn() {
this.oidcSecurityService.authorize();
}

signOut() {
this.oidcSecurityService.logoff().subscribe((result) => {
console.log('app sign-out', result);
});
}
}

然后,在模板中添加登录和登出的按钮:

app/app.component.html
<button (click)="signIn()">Sign in</button>
<br />
<button (click)="signOut()">Sign out</button>

调用 .signOut() 将清除内存和 localStorage 中所有的 Logto 数据(如果存在)。

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

现在,你可以测试你的应用程序:

  1. 运行你的应用程序,你将看到登录按钮。
  2. 点击登录按钮,SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
  3. 登录后,你将被重定向回你的应用程序,并看到登出按钮。
  4. 点击登出按钮以清除本地存储并登出。

获取用户信息

一旦用户成功登录,Logto 将签发一个包含用户信息声明的 ID 令牌。ID 令牌是一个 JSON Web Token (JWT)。

需要注意的是,可以检索的用户信息声明取决于用户在登录时使用的权限,并且考虑到性能和数据大小,ID 令牌可能不包含所有用户声明,某些用户声明仅在 userinfo endpoint 中可用(请参阅下面的相关列表)。

如果配置中没有提供 resourcebuildAngularAuthConfig() 工具将启用 autoUserInforenewUserInfoAfterTokenRenew。这意味着 Logto 将在用户登录后自动获取用户信息,并在令牌更新后更新用户信息。

信息:

要了解有关配置 angular-auth-oidc-client 库的更多信息,请参阅 官方文档

显示用户信息

OidcSecurityService 提供了一种方便的方法来订阅认证状态以及用户信息:

app/app.component.ts
import { OidcSecurityService } from 'angular-auth-oidc-client';
import { decodeIdToken, type IdTokenClaims } from '@logto/js';

export class AppComponent implements OnInit {
isAuthenticated = false;
idTokenClaims?: IdTokenClaims;
accessToken?: string;

constructor(public oidcSecurityService: OidcSecurityService) {}

ngOnInit() {
this.oidcSecurityService.checkAuth().subscribe(({ isAuthenticated, idToken, accessToken }) => {
console.log('app authenticated', isAuthenticated, idToken);
this.isAuthenticated = isAuthenticated;
this.idTokenClaims = decodeIdToken(idToken);
this.accessToken = accessToken;
});
}

// ...other methods
}

并在模板中使用它:

app/app.component.html
<button *ngIf="!isAuthenticated" (click)="signIn()">Sign in</button>
<ng-container *ngIf="isAuthenticated">
<pre>{{ idTokenClaims | json }}</pre>
<p>Access token: {{ accessToken }}</p>
<!-- ... -->
<button (click)="signOut()">Sign out</button>
</ng-container>

请求额外的声明

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

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

信息:

“声明(Claim)”是关于主体的断言;“权限(Scope)”是一组声明。在当前情况下,声明是关于用户的一条信息。

以下是权限(Scope)与声明(Claim)关系的非规范性示例:

提示:

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

Logto SDK 将始终请求三个权限(Scope):openidprofileoffline_access

要请求额外的权限,你可以配置认证提供者配置:

app/app.config.ts
import { UserScope, buildAngularAuthConfig } from '@logto/js';

export const appConfig: ApplicationConfig = {
providers: [
provideHttpClient(withFetch()),
provideAuth({
config: buildAngularAuthConfig({
// ...other configs
scopes: [
UserScope.Email,
UserScope.Phone,
UserScope.CustomData,
UserScope.Identities,
UserScope.Organizations,
],
}),
}),
// ...other providers
],
};

然后你可以在 idToken 的返回值中访问额外的声明。

需要网络请求的声明

为了防止 ID 令牌 (ID token) 过大,一些声明需要通过网络请求来获取。例如,即使在权限中请求了 custom_data 声明,它也不会包含在用户对象中。要访问这些声明,你可以配置 userData 选项

app/app.component.ts
import { OidcSecurityService } from 'angular-auth-oidc-client';
import { type UserInfoResponse } from '@logto/js';

export class AppComponent implements OnInit {
isAuthenticated = false;
userData?: UserInfoResponse;
accessToken?: string;

constructor(public oidcSecurityService: OidcSecurityService) {}

ngOnInit() {
this.oidcSecurityService
.checkAuth()
.subscribe(({ isAuthenticated, userData, accessToken }) => {
console.log('app authenticated', isAuthenticated, idToken);
this.isAuthenticated = isAuthenticated;
this.userData = userData;
this.accessToken = accessToken;
});
}

// ...other methods
}

// Now you can access the claim `userData.custom_data`
通过配置 userData,SDK 将在用户登录后通过请求 userinfo 端点 来获取用户信息,并且一旦请求完成,userData 将可用。

权限和声明

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

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

openid

声明名称类型描述需要用户信息吗?
substring用户的唯一标识符

profile

声明名称类型描述需要用户信息吗?
namestring用户的全名
usernamestring用户名
picturestring终端用户的个人资料图片的 URL。此 URL 必须指向一个图像文件(例如,PNG、JPEG 或 GIF 图像文件),而不是包含图像的网页。请注意,此 URL 应特别引用适合在描述终端用户时显示的终端用户的个人资料照片,而不是终端用户拍摄的任意照片。
created_atnumber终端用户创建的时间。时间表示为自 Unix 纪元(1970-01-01T00:00:00Z)以来的毫秒数。
updated_atnumber终端用户信息最后更新的时间。时间表示为自 Unix 纪元(1970-01-01T00:00:00Z)以来的毫秒数。

其他 标准声明 包括 family_namegiven_namemiddle_namenicknamepreferred_usernameprofilewebsitegenderbirthdatezoneinfolocale 也将包含在 profile 权限中,而无需请求用户信息端点。与上述声明的区别在于,这些声明只有在其值不为空时才会返回,而上述声明在值为空时将返回 null

备注:

与标准声明不同,created_atupdated_at 声明使用毫秒而不是秒。

email

声明名称类型描述需要用户信息吗?
emailstring用户的电子邮件地址
email_verifiedboolean电子邮件地址是否已验证

phone

声明名称类型描述需要用户信息吗?
phone_numberstring用户的电话号码
phone_number_verifiedboolean电话号码是否已验证

address

请参阅 OpenID Connect Core 1.0 以获取地址声明的详细信息。

custom_data

声明名称类型描述需要用户信息吗?
custom_dataobject用户的自定义数据

identities

声明名称类型描述需要用户信息吗?
identitiesobject用户的关联身份
sso_identitiesarray用户的关联 SSO 身份

urn:logto:scope:organizations

声明名称类型描述需要用户信息吗?
organizationsstring[]用户所属的组织 ID
organization_dataobject[]用户所属的组织数据

urn:logto:scope:organization_roles

声明名称类型描述需要用户信息吗?
organization_rolesstring[]用户所属的组织角色,格式为 <organization_id>:<role_name>

考虑到性能和数据大小,如果“需要用户信息吗?”为“是”,则表示声明不会显示在 ID 令牌中,而会在 用户信息端点 响应中返回。

API 资源

为 API 资源配置 angular-auth-oidc-client

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

一旦你设置了 API 资源,就可以在应用中配置 Logto 时添加它们:

/app/app.config.ts
export const appConfig: ApplicationConfig = {
providers: [
provideHttpClient(withFetch()),
provideAuth({
config: buildAngularAuthConfig({
// ...other config
resource: 'https://your-api-resource.com',
}),
}),
// ...other providers
],
};

每个 API 资源都有其自己的权限(权限)。

例如,https://shopping.your-app.com/api 资源具有 shopping:readshopping:write 权限,而 https://store.your-app.com/api 资源具有 store:readstore:write 权限。

要请求这些权限,你可以在应用中配置 Logto 时添加它们:

app/app.config.ts
export const appConfig: ApplicationConfig = {
providers: [
provideHttpClient(withFetch()),
provideAuth({
config: buildAngularAuthConfig({
// ...other config
resource: 'https://your-api-resource.com',
scopes: ['openid', 'profile', 'offline_access', 'read', 'write'],
}),
}),
// ...other providers
],
};

你可能会注意到权限是与 API 资源分开定义的。这是因为 OAuth 2.0 的资源指示器 指定请求的最终权限将是所有目标服务中所有权限的笛卡尔积。

备注:

请求 API 资源中未定义的权限是可以的。例如,即使 API 资源没有可用的 email 权限,你也可以请求 email 权限。不可用的权限将被安全地忽略。

成功登录后,Logto 将根据用户的角色向 API 资源发布适当的权限。

现在,访问令牌 (access token) 将采用 JSON Web Token (JWT) 格式,而不是随机字符串(不透明令牌 (opaque token))。

注意:

当设置了 resource 时,autoUserInforenewUserInfoAfterTokenRenew 都将被禁用。这是因为访问令牌 (access token) 将为特定的 API 资源请求,而不是为用户信息端点请求。

目前,只有 Logto 官方 SDK 支持同时请求用户信息和 API 资源访问令牌 (access token) 的功能。如果你需要同时请求这两者,请随时联系我们。

延伸阅读

终端用户流程:认证流程、账户流程和组织流程 配置连接器 保护你的 API