核心 SDK 規範

基本規範

核心應僅包含與平台無關的功能。
核心應命名為 {$language} 並位於儲存庫根目錄下。例如，logto/js/js，logto/kotlin/kotlin。
核心套件應在 Logto 範疇下命名為 {$language}。例如，@logto/js，io.logto.sdk:kotlin。

基本要求

任何核心 SDK 應包含：

類型
工具函數
核心功能

類型

OidcConfigResponse

身分提供者的配置，可透過 /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

生成一個 code verifier。
code verifier 的長度固定為 64。
返回值必須加密為 URL 安全的 base64 格式字串。

參考

PKCE

參數

無。

返回類型

string

generateCodeChallenge

基於 code verifier 生成一個 code challenge。
此方法加密 code verifier 並以 URL 安全的 Base64 格式返回結果。
我們在 Logto V1 中將加密算法固定為 SHA-256。

參考

PKCE

參數

名稱	類型	備註
codeVerifier	`string`	由 generateCodeVerifier 生成

返回類型

string

generateState

"State" 用於防止 CSRF 攻擊。
"State" 的長度固定為 64。
返回的字串必須加密為 URL 安全的 base64 格式字串。

參考

CSRF

參數

無。

返回類型

string

decodeIdToken

解碼一個 ID 權杖而不進行密鑰驗證。
返回一個 IdTokenClaims，其中包含權杖在 payload 部分的所有宣告。

參數

名稱	類型
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

驗證登入 callbackUri 是否合法並返回從 callbackUri 提取的 code。

驗證 Callback URI

驗證 callbackUri 應以 redirectUri 開頭
驗證 callbackUri 中沒有 error（參考 Error Response 在 redirect 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		我們可以多次將資源添加到 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
Content-Type：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
Content-Type：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
Content-Type：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