Platform SDK 규칙

Platform SDK는 특정 플랫폼에서 Logto 서비스와 클라이언트를 통합하는 표준 방법을 제공하며 통합 과정을 가속화합니다.

• Platform SDK는 플랫폼별 구현으로 핵심을 캡슐화합니다.
• Platform SDK는 SDK를 더 쉽게 사용할 수 있도록 기본 유형을 제공해야 합니다.
• Platform SDK는 LogtoClient라는 이름의 클래스로 내보내야 합니다.

기본 유형

LogtoConfig

Name	Type	Required	Default Value	Notes
endpoint	string	✅		OIDC 서비스 엔드포인트입니다.
appId	string	✅		Logto 서비스에 등록한 애플리케이션의 ID입니다.
scopes	string[]		[openid, offline_access, profile]	이 필드는 항상 openid, offline_access 및 profile을 포함합니다.
resources	string[]			사용하고자 하는 보호된 리소스 지표입니다.
prompt	string		consent	generateSignInUri에서 사용되는 프롬프트 값입니다.
usingPersistStorage	boolean		true	로컬 머신에 자격 증명을 저장할지 여부를 결정합니다.

*Notes

• 필요에 따라 이 LogtoConfig를 확장할 수 있습니다.
• usingPersistStorage는 클라이언트 SDK에서만 제공됩니다. 예: iOS, Android, SPA.

AccessToken

Name	Type	Notes
token	string
scope	string
expiresAt	number	초 단위의 타임스탬프

LogtoClient

속성

logtoConfig

Type

LogtoConfig

oidcConfig

Type

OidcConfigResponse?

accessTokenMap

Type

Map<string, AccessToken>

Key

• 키는 scope와 resource로 구성되어야 합니다.
• scope의 값은 알파벳 순으로 정렬되고 공백으로 연결되어야 합니다.
• 키는 다음 패턴으로 구성되어야 합니다: ${scope}@${resource}.
• scope 또는 resource가 null이거나 비어 있는 경우, 해당 값은 비어 있는 것으로 처리해야 합니다.

예: "offline_access openid read:usr@https://logto.dev/api", "@https://logto.dev/api", "openid@", "@".

Value

• AccessToken, expiresAt 속성을 사용하여 액세스 토큰이 만료되는 정확한 시간을 나타냅니다.

Notes

• Logto V1에서는 사용자 정의 스코프를 지원하지 않으므로 scope는 항상 null 값이 됩니다.
• 액세스 토큰 키를 생성하여 액세스 토큰을 저장할 때:
  • scope는 항상 null 값이 됩니다.
  • 액세스 토큰이 JWT가 아닌 경우, resource를 null 값으로 처리합니다.
  • 액세스 토큰이 JWT인 경우, 액세스 토큰을 디코딩하고 페이로드의 aud 클레임 값을 액세스 토큰 키의 resource 부분으로 사용합니다.

refreshToken

Type

string?

Notes

refreshToken은 아래 상황에서 설정되거나 업데이트됩니다:

• 저장소에서 refreshToken을 로드합니다.
• 서버가 토큰을 성공적으로 가져오는 응답에서 refreshToken을 반환합니다.
• 로그아웃 (null로 설정됩니다).

idToken

Type

string?

Notes

• idToken은 백엔드에서 온 경우 검증되어야 합니다.
• idToken은 아래 상황에서 설정되거나 업데이트됩니다:
  • 저장소에서 idToken을 로드합니다.
  • 서버가 토큰을 성공적으로 가져오는 응답에서 idToken을 반환합니다.
  • 로그아웃 (null로 설정됩니다).

메서드

constructor

Parameters

Parameter	Type
logtoConfig	LogtoConfig

Return Type

LogtoClient

Notes

• 필요에 따라 추가 매개변수를 추가할 수 있습니다.
• logtoConfig에서 usePersistStorage가 활성화된 경우, 플랫폼 SDK는 다음 기능을 제공합니다:
  • clientId를 기반으로 고유한 키로 영구 데이터를 저장합니다.
  • 초기화 시 로컬 머신에서 refreshToken과 idToken을 로드합니다.
  • Core.fetchTokenByAuthorizationCode 및 Core.fetchTokenByRefreshToken에서 refreshToken과 idToken을 로컬에 저장합니다.

isAuthenticated

사용자가 인증되었는지 여부를 확인합니다.
이것은 getter로도 정의될 수 있습니다.

사용자가 인증된 것으로 간주되는 경우:

• ID 토큰을 성공적으로 획득한 경우.
• 로컬 머신에서 ID 토큰을 로드한 경우.

Parameters

없음.

Return Type

boolean

SignIn

이 메서드는 로그인 흐름을 시작해야 하며, 플랫폼 SDK는 로그인 리디렉션 프로세스를 포함하여 인가를 완료하는 데 필요한 모든 단계를 처리해야 합니다.

이 메서드가 성공적으로 호출된 후 사용자가 인증됩니다.

로그인 프로세스는 Core SDK 함수에 의존합니다:

• generateSignInUri
• verifyAndParseCodeFromCallbackUri
• fetchTokenByAuthorizationCode

Notes:

• generateSignInUri는 필요한 리소스를 포함하므로 fetchTokenByAuthorizationCode 함수에 리소스를 전달할 필요가 없습니다.

Parameters

Parameter	Type
redirectUri	string

Return Type

void

Throws

• 이 로그인 과정에서 발생하는 모든 오류.

SignOut

로그아웃 프로세스는 다음 단계를 따라야 합니다:

1. 로컬 저장소, 쿠키, 영구 데이터 또는 기타 항목을 지웁니다.
2. Core.revoke를 통해 획득한 리프레시 토큰을 취소합니다 (리프레시 토큰이 취소되면 Logto 서비스는 모든 관련 토큰을 취소합니다).
3. 1단계에서 로그인 페이지의 세션을 지우지 않는 한 사용자를 Logto의 로그아웃 엔드포인트로 리디렉션합니다.

Notes:

• 2단계에서 Core.revoke는 비동기 호출이며 실패하더라도 로그아웃 프로세스를 차단하지 않습니다.
• 3단계는 Logto의 로그아웃 엔드포인트를 생성하기 위해 Core.generateSignOutUri에 의존합니다.

Parameters

Parameter	Type	Required	Default Value
postLogoutRedirectUri	string		null

Return Type

void

Throws

• 이 로그아웃 과정에서 발생하는 모든 오류.

getAccessToken

getAccessToken은 accessTokenMap에서 resource와 scope로 AccessToken을 검색한 다음 해당 AccessToken의 token 값을 반환합니다.

Logto V1에서는 사용자 정의 스코프를 지원하지 않으므로 accessTokenMap의 키를 생성할 때 scope를 null로 설정합니다.

Notes

• 해당하는 AccessToken을 찾을 수 없는 경우, 필요한 토큰을 가져오기 위해 Core.fetchTokenByRefreshToken 작업을 수행합니다.
• accessToken이 만료되지 않은 경우, 내부의 token 값을 반환합니다.
• accessToken이 만료된 경우, 새로운 accessToken을 가져오기 위해 Core.fetchTokenByRefreshToken 작업을 수행하고, 로컬 accessTokenMap을 업데이트한 후 새로운 token 값을 반환합니다.
• Core.fetchTokenByRefreshToken이 실패하면 발생한 예외를 사용자에게 알립니다.
• 리프레시 토큰을 찾을 수 없는 경우, 사용자에게 인가되지 않은 예외를 알립니다.
• 로그인 후 리프레시 토큰을 획득한 경우에만 Core.fetchTokenByRefreshToken 작업을 수행할 수 있습니다.

Parameters

Parameter	Type	Required	Default value
resource	string		null

Return Type

string

Throws

• 사용자가 인증되지 않았습니다.
• 입력된 resource가 logtoConfig에 설정되지 않았습니다.
• Core.fetchTokenByRefreshToken 전에 리프레시 토큰을 찾을 수 없습니다.
• Core.fetchTokenByRefreshToken이 실패했습니다.

getIdTokenClaims

getIdTokenClaims는 idToken 속성의 클레임을 담고 있는 객체를 반환합니다.

Parameters

없음.

Return Type

IdTokenClaims

Throws

• 사용자가 인증되지 않았습니다.