核心 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

抛出

撤销失败

基本约定​

基本要求​

类型​

OidcConfigResponse​

CodeTokenResponse​

RefreshTokenResponse​

IdTokenClaims​

工具函数​

generateCodeVerifier​

generateCodeChallenge​

generateState​

decodeIdToken​

verifyIdToken​

verifyAndParseCodeFromCallbackUri​

核心功能​

fetchOidcConfig​

generateSignInUri​

generateSignOutUri​

fetchTokenByAuthorizationCode​

fetchTokenByRefreshToken​

revoke​

基本约定

基本要求

类型

OidcConfigResponse

CodeTokenResponse

RefreshTokenResponse

IdTokenClaims

工具函数

generateCodeVerifier

generateCodeChallenge

generateState

decodeIdToken

verifyIdToken

verifyAndParseCodeFromCallbackUri

核心功能

fetchOidcConfig

generateSignInUri

generateSignOutUri

fetchTokenByAuthorizationCode

fetchTokenByRefreshToken

revoke