平台 SDK 约定

平台 SDK 提供了一种在特定平台上与 Logto 服务集成的标准方式，并加速集成过程。

平台 SDK 封装了核心的平台特定实现。
平台 SDK 应提供使 SDK 更易于使用的基本类型。
平台 SDK 应作为名为 LogtoClient 的类导出。

基本类型

LogtoConfig

名称	类型	必需	默认值	备注
endpoint	`string`	✅		OIDC 服务端点。
appId	`string`	✅		应用程序 ID 来自我们在 Logto 服务中注册的应用程序。
scopes	`string[]`		`[openid, offline_access, profile]`	此字段始终包含 `openid`、`offline_access` 和 `profile`。
resources	`string[]`			我们想要使用的受保护资源指示器。
prompt	`string`		`consent`	在 `generateSignInUri` 中使用的 prompt 值。
usingPersistStorage	`boolean`		`true`	决定是否在本地机器上存储凭据。

*备注

如果需要，可以扩展此 LogtoConfig。
usingPersistStorage 仅在客户端 SDK 中提供。例如，iOS、Android 和 SPA。

AccessToken

名称	类型	备注
token	`string`
scope	`string`
expiresAt	`number`	时间戳（秒）

LogtoClient

属性

logtoConfig

类型

LogtoConfig

oidcConfig

类型

OidcConfigResponse?

accessTokenMap

类型

Map<string, AccessToken>

键

键应由 scope 和 resource 构成。
scope 中的值应按字母顺序排序并用空格连接。
键应按模式构建：${scope}@${resource}。
如果 scope 或 resource 为 null 或为空，则其值应视为空。

例如，"offline_access openid read:usr@https://logto.dev/api"，"@https://logto.dev/api"，"openid@"，"@"。

值

AccessToken，使用 expiresAt 属性指示访问令牌过期的确切时间。

备注

scope 将始终为 null 值，因为我们在 Logto V1 中不支持自定义权限。
在构建访问令牌键以存储访问令牌时：
- scope 将始终为 null 值。
- 如果访问令牌不是 JWT，请将 resource 视为 null 值。
- 如果访问令牌是 JWT，请解码访问令牌并使用有效负载的 aud 声明值作为访问令牌键的 resource 部分。

refreshToken

类型

string?

备注

refreshToken 将在以下情况下设置或更新：

从存储中加载 refreshToken。
服务器在成功获取令牌的响应中返回 refreshToken。
注销（将设置为 null）。

idToken

类型

string?

备注

如果 idToken 来自后端，则应进行验证。
idToken 将在以下情况下设置或更新：
- 从存储中加载 idToken。
- 服务器在成功获取令牌的响应中返回 idToken。
- 注销（将设置为 null）。

方法

constructor

参数

参数	类型
logtoConfig	`LogtoConfig`

返回类型

LogtoClient

备注

如果需要，可以添加额外的参数。
如果在 logtoConfig 中启用了 usePersistStorage，平台 SDK 将提供以下功能：
- 使用基于 clientId 的唯一键存储持久数据。
- 在初始化时从本地机器加载 refreshToken 和 idToken。
- 在 Core.fetchTokenByAuthorizationCode 和 Core.fetchTokenByRefreshToken 上本地存储 refreshToken 和 idToken。

isAuthenticated

用于判断用户是否已认证。
这也可以定义为一个 getter。

当满足以下条件时，用户被视为已认证：

我们已成功获取 ID 令牌。
我们已从本地机器加载 ID 令牌。

参数

无。

返回类型

boolean

SignIn

此方法应启动登录流程，平台 SDK 应处理授权需要完成的所有步骤，包括登录重定向过程。

在此方法成功调用后，用户将被认证。

登录过程将依赖于核心 SDK 功能：

generateSignInUri
verifyAndParseCodeFromCallbackUri
fetchTokenByAuthorizationCode

备注：

因为 generateSignInUri 包含了我们需要的资源，所以我们不需要将资源传递给 fetchTokenByAuthorizationCode 函数。

参数

参数	类型
redirectUri	`string`

返回类型

void

抛出

在此登录过程中发生的任何错误。

SignOut

注销过程应遵循以下步骤：

清除本地存储、cookies、持久数据或其他内容。
通过 Core.revoke 撤销获取的刷新令牌（如果刷新令牌被撤销，Logto 服务将撤销所有相关令牌）。
将用户重定向到 Logto 的注销端点，除非第 1 步清除了登录页面的会话。

备注：

在步骤 2 中，Core.revoke 是一个异步调用，即使失败也不会阻止注销过程。
第 3 步依赖于 Core.generateSignOutUri 生成 Logto 的注销端点。

参数

参数	类型	必需	默认值
postLogoutRedirectUri	`string`		`null`

返回类型

void

抛出

在此注销过程中发生的任何错误。

getAccessToken

getAccessToken 通过 resource 和 scope 从 accessTokenMap 中检索一个 AccessToken，然后返回该 AccessToken 的 token 值。

在构建 accessTokenMap 的键时，我们将 scope 设置为 null，因为我们在 Logto V1 中不支持自定义权限。

备注

如果找不到相应的 AccessToken，则执行 Core.fetchTokenByRefreshToken 操作以获取所需的令牌。
如果 accessToken 未过期，则返回其中的 token 值。
如果 accessToken 已过期，则执行 Core.fetchTokenByRefreshToken 操作以检索新的 accessToken，更新本地 accessTokenMap 并返回新的 token 值。
如果 Core.fetchTokenByRefreshToken 失败，则通知用户发生的异常。
如果找不到 refreshToken，则通知用户未授权的异常。
只有在登录后获取到 refreshToken 后，我们才能执行 Core.fetchTokenByRefreshToken 操作。

参数

参数	类型	必需	默认值
resource	`string`		`null`

返回类型

string

抛出

用户未认证。
输入的 resource 未在 logtoConfig 中设置。
在 Core.fetchTokenByRefreshToken 之前找不到刷新令牌。
Core.fetchTokenByRefreshToken 失败。

getIdTokenClaims

getIdTokenClaims 返回一个携带 idToken 属性声明的对象。

参数

无。

返回类型

IdTokenClaims

抛出

用户未认证。

基本类型​

LogtoClient​

属性​

方法​

基本类型

LogtoClient

属性

方法