Core 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-party 라이브러리 (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가 없는지 확인합니다 (리디렉션 URI의 Error Response 참조).
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 또는 빈 값일 경우에도 포함됩니다.
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