コア 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

コードベリファイアを生成します。
コードベリファイアの長さは 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 をサポートしています。
この関数は、3rd パーティライブラリ (jose) からの JsonWebKeySet オブジェクトを受け入れて検証を行います。

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

クレームの検証

ID トークン内の iss がこのトークンの発行者と一致することを確認します。
aud (オーディエンス) クレームがクライアント ID と等しいことを確認します。
現在の時間が有効期限の前であることを確認します。
発行時刻 (iat) が現在の時間から +/- 1 分以内であることを確認します。

参考

OpenID connect core - ID トークンの検証

パラメータ

名前	型
idToken	`string`
clientId	`string`
issuer	`string`
jwks	`JsonWebKeySet`

戻り値の型

void

例外

署名キーの検証に失敗した場合
クレームの検証に失敗した場合

verifyAndParseCodeFromCallbackUri

サインイン callbackUri が合法であることを検証し、callbackUri から抽出された code を返します。

コールバック URI の検証

callbackUri が redirectUri で始まることを確認します。
callbackUri に error がないことを確認します（リダイレクト URI のエラーレスポンスを参照）。
callbackUri に state が含まれており、それが generateSignInUri で指定した state 値と等しいことを確認します。
callbackUri に /oidc/token（リフレッシュトークンによる）をリクエストする際に使用する code パラメータ値が含まれていることを確認します。

パラメータ

名前	型
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 が null または空の scope 値を提供しても含まれます。
resource		URI に resource を複数回追加できます。バックエンドはそれらをリストとして変換します。例：`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