核心 SDK 约定

基本约定

• 核心部分应仅包含与平台无关的功能。
• 核心部分应命名为 {$language} 并位于代码库的根目录下。例如，logto/js/js，logto/kotlin/kotlin。
• 核心包应在 Logto 范围内命名为 {$language}。例如，@logto/js，io.logto.sdk:kotlin。

基本要求

任何核心 SDK 应包含：

• 类型
• 工具函数
• 核心功能

类型

OidcConfigResponse

身份提供商 (IdP) 的配置，可以通过 /oidc/.well-known/openid-configuration API 获取。

属性

名称	类型
authorizationEndpoint	string
tokenEndpoint	string
endSessionEndpoint	string
revocationEndpoint	string
jwksUri	string
issuer	string

CodeTokenResponse

/oidc/token 的响应数据（通过授权码）。

属性

名称	类型	必需
accessToken	string	✅
refreshToken	string
idToken	string	✅
scope	string	✅
expiresIn	number	✅

RefreshTokenResponse

通过刷新令牌刷新令牌时，/oidc/token 的响应数据（通过刷新令牌）。

属性

名称	类型	必需
accessToken	string	✅
refreshToken	string	✅
idToken	string
scope	string	✅
expiresIn	number	✅

IdTokenClaims

ID 令牌携带的声明。

属性

名称	类型	必需
sub	string	✅
aud	string	✅
exp	number	✅
iat	number	✅
iss	string	✅
atHash	string
username	string
name	string
avatar	string

工具函数

generateCodeVerifier

生成一个代码验证器。
代码验证器的长度硬编码为 64。
返回值必须加密为 URL 安全的 base64 格式字符串。

参考

• PKCE

参数

无。

返回类型

string

generateCodeChallenge

基于代码验证器生成代码挑战。
此方法加密代码验证器，并以 URL 安全的 Base64 格式返回结果。
我们在 Logto V1 中将加密算法硬编码为 SHA-256。

参考

• PKCE

参数

名称	类型	备注
codeVerifier	string	由 generateCodeVerifier 生成

返回类型

string

generateState

"State" 用于防止 CSRF 攻击。
"State" 的长度硬编码为 64。
返回的结果字符串必须加密为 URL 安全的 base64 格式字符串。

参考

• CSRF

参数

无。

返回类型

string

decodeIdToken

解码一个 ID 令牌而不进行秘密验证。
返回一个 IdTokenClaims，其中包含所有在有效负载部分的令牌声明。

参数

名称	类型
token	string

返回类型

IdTokenClaims

抛出

• token 不是有效的 JWT。

verifyIdToken

验证一个 ID 令牌是否合法。

验证签名密钥

OIDC 支持 JSON Web Key Set。 此函数接受来自第三方库 (jose) 的 JsonWebKeySet 对象进行验证。

// JsonWebKeySet 示例
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "xxxx",
      "e": "xxxx",
      "n": "xxxx"
    }
  ]
}

验证声明

• 验证 ID 令牌中的 iss 是否与此令牌的发行者匹配。
• 验证 aud（受众）声明是否等于客户端 ID。
• 验证当前时间是否在过期时间之前。
• 验证签发时间 (iat) 是否不超过当前时间的 +/- 1 分钟。

参考

• OpenID connect core - ID Token Validation

参数

名称	类型
idToken	string
clientId	string
issuer	string
jwks	JsonWebKeySet

返回类型

void

抛出

• 验证签名密钥失败
• 验证声明失败

verifyAndParseCodeFromCallbackUri

验证登录回调 URI 是否合法，并返回从回调 URI 中提取的 code。

验证回调 URI

• 验证 callbackUri 应以 redirectUri 开头
• 验证 callbackUri 中没有 error（参见 Error Response 中的重定向 URI）。
• 验证 callbackUri 包含 state，应等于你在 generateSignInUri 中指定的 state 值。
• 验证 callbackUri 包含参数值 code，你将在请求 /oidc/token（通过刷新令牌）时使用。

参数

名称	类型
callbackUri	string
redirectUri	string
state	string

返回类型

string

抛出

• 验证失败

核心功能

fetchOidcConfig

通过请求 /oidc/.well-known/openid-configuration 返回 OidcConfigResponse。

参数

名称	类型	备注
endpoint	string	OIDC 服务端点

返回类型

OidcConfigResponse

抛出

• 获取失败

generateSignInUri

参数

名称	类型	必需	备注
authorizationEndpoint	string	✅
clientId	string	✅
redirectUri	string	✅
codeChallenge	string	✅
state	string	✅
scopes	string[]		实现可能会根据语言规范而有所不同。
resources	string[]		实现可能会根据语言规范而有所不同。
prompt	string		默认值：consent。

URL 将基于 authorizationEndpoint 生成，并包含以下查询参数：

登录 URL 查询参数

查询键	必需	备注
client_id	✅
redirect_uri	✅
code_challenge	✅
code_challenge_method	✅	硬编码为 S256。
state	✅
scope	✅	scope 始终包含 openid 和 offline_access，即使输入的 scope 提供了空或空的 scope 值。
resource		我们可以多次将 resource 添加到 uri，后端会将它们转换为列表。例如 resource=a&resource=b
response_type	✅	硬编码为 code。
prompt	✅

返回类型

string

generateSignOutUri

参数

名称	类型	必需
endSessionEndpoint	string	✅
idToken	string	✅
postLogoutRedirectUri	string

要生成的 URL 将基于 endSessionEndpoint，并包含以下查询参数：

注销 URL 查询参数

查询键	必需	备注
id_token_hint	✅	输入的 idToken 参数
post_logout_redirect_uri		输入的 postLogoutRedirectUri 参数

返回类型

string

fetchTokenByAuthorizationCode

通过请求 /oidc/token（通过授权码）获取令牌 (CodeTokenResponse)。

参数

名称	类型	必需
tokenEndpoint	string	✅
code	string	✅
codeVerifier	string	✅
clientId	string	✅
redirectUri	string	✅
resource	string

HTTP 请求

• 端点：/oidc/token
• 方法：POST
• 内容类型：application/x-www-form-urlencoded
• 负载：

查询键	类型	必需
grant_type	string: 'authorization_code'	✅
code	string	✅
code_verifier	string	✅
client_id	string	✅
redirect_uri	string	✅
resource	string

返回类型

CodeTokenResponse

抛出

• 获取失败

fetchTokenByRefreshToken

通过 /oidc/token（通过刷新令牌）获取令牌 (RefreshTokenTokenResponse)。

参数

名称	类型	必需
tokenEndpoint	string	✅
clientId	string	✅
refreshToken	string	✅
resource	string
scopes	string[]

HTTP 请求

• 端点：/oidc/token
• 方法：POST
• 内容类型：application/x-www-form-urlencoded
• 负载：

查询键	类型	必需	备注
grant_type	string: 'refresh_token'	✅
refresh_token	string	✅
client_id	string	✅
resource	string
scope	string		我们用空格连接 scopes 值来构造这个 scope 字符串

返回类型

RefreshTokenTokenResponse

抛出

• 获取失败

revoke

请求 /oidc/token/revocation API 通知授权服务器先前获取的刷新或访问令牌不再需要。

参数

名称	类型	备注
revocationEndpoint	string
clientId	string
token	string	要撤销的令牌

HTTP 请求

• 端点：/oidc/token/revocation
• 方法：POST
• 内容类型：application/x-www-form-urlencoded
• 负载：

查询键	类型
client_id	string
token	string

返回类型

void

抛出

• 撤销失败