Core SDK convention

Basic conventions

• The core should contain platform-independent functions only.
• The core should be named as {$language} and under the repository root directory. E.g., logto/js/js, logto/kotlin/kotlin.
• The core package should be named as {$language} under Logto scope. E.g., @logto/js, io.logto.sdk:kotlin.

Basic requirements

Any core SDK should contain:

• Types
• Utility functions
• Core functions

Types

OidcConfigResponse

The configuration of the identity provider, which can be retrieved via /oidc/.well-known/openid-configuration API.

Properties

Name	Type
authorizationEndpoint	string
tokenEndpoint	string
endSessionEndpoint	string
revocationEndpoint	string
jwksUri	string
issuer	string

CodeTokenResponse

The response data of /oidc/token (by authorization code).

Properties

Name	Type	Required
accessToken	string	✅
refreshToken	string
idToken	string	✅
scope	string	✅
expiresIn	number	✅

RefreshTokenResponse

The response data of /oidc/token (by refresh token) when refreshing tokens by a refresh token.

Properties

Name	Type	Required
accessToken	string	✅
refreshToken	string	✅
idToken	string
scope	string	✅
expiresIn	number	✅

IdTokenClaims

Claims carried by the id token.

Properties

Name	Type	Required
sub	string	✅
aud	string	✅
exp	number	✅
iat	number	✅
iss	string	✅
atHash	string
username	string
name	string
avatar	string

Utility functions

generateCodeVerifier

Generate a code verifier.
The length of the code verifier is hardcoded as 64.
The return value MUST be encrypted to an URL-safe base64 format string.

Reference

• PKCE

Parameters

None.

Return Type

string

generateCodeChallenge

Generate a code challenge based on a code verifier.
This method encrypts the code verifier and returns the result in a URL-safe Base64 format.
We hardcode the encryption algorithm as SHA-256 in Logto V1.

Reference

• PKCE

Parameters

Name	Type	Notes
codeVerifier	string	Generated by generateCodeVerifier

Return Type

string

generateState

"State" is used to prevent the CSRF attack.
The length of the "state" is hardcoded as 64.
The result string to be returned MUST be encrypted to an URL-safe base64 format string.

Reference

• CSRF

Parameters

None.

Return Type

string

decodeIdToken

Decode an ID Token without secret verification.
Return an IdTokenClaims which carries all the token claims in the payload section.

Parameters

Name	Type
token	string

Return Type

IdTokenClaims

Throws

• The token is not a valid JWT.

verifyIdToken

Verify if an ID Token is legal.

Verify Signing Key

OIDC supported the JSON Web Key Set. This function accepts a JsonWebKeySet object from a 3rd-party library (jose) for verification.

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

Verify Claims

• Verify the iss in the ID Token matches the issuer of this token.
• Verify the aud (audience) Claim is equal to the client ID.
• Verify that the current time is before the expiry time.
• Verify that the issued at time (iat) is not more than +/- 1 minute on the current time.

Reference

• OpenID connect core - ID Token Validation

Parameters

Name	Type
idToken	string
clientId	string
issuer	string
jwks	JsonWebKeySet

Return Type

void

Throws

• Verify signing key failed
• Verify claims failed

verifyAndParseCodeFromCallbackUri

Verify the sign-in callbackUri is legal and return the code extracted from callbackUri.

Verify Callback URI

• Verify the callbackUri should start with redirectUri
• Verify there is no error in the callbackUri (Refer to Error Response in redirect URI).
• Verify the callbackUri contains state, which should equal to the state value you specified in generateSignInUri.
• Verify the callbackUri contains the parameter value code, which you will use when requesting to /oidc/token (by refresh token).

Parameters

Name	Type
callbackUri	string
redirectUri	string
state	string

Return Type

string

Throws

• Verifications failed

Core functions

fetchOidcConfig

Return OidcConfigResponse by requesting to /oidc/.well-known/openid-configuration.

Parameters

Name	Type	Notes
endpoint	string	The OIDC service endpoint

Return Type

OidcConfigResponse

Throws

• Fetch failed

generateSignInUri

Parameters

Name	Type	Required	Notes
authorizationEndpoint	string	✅
clientId	string	✅
redirectUri	string	✅
codeChallenge	string	✅
state	string	✅
scopes	string[]		The implementation may vary according to language specifications.
resources	string[]		The implementation may vary according to language specifications.
prompt	string		Default: consent.

The URL will be generated based on authorizationEndpoint and contains the following query params:

Sign-In Url Query Parameters

Query Key	Required	Notes
client_id	✅
redirect_uri	✅
code_challenge	✅
code_challenge_method	✅	Hardcoded as S256.
state	✅
scope	✅	scope always contains openid and offline_access, even the input scope provides a null or empty scope value.
resource		We can add resource to uri more than once, the backend will convert them as a list. e.g. resource=a&resource=b
response_type	✅	Hardcoded as code.
prompt	✅

Return Type

string

generateSignOutUri

Parameters

Name	Type	Required
endSessionEndpoint	string	✅
idToken	string	✅
postLogoutRedirectUri	string

The URL to be generated will be based on endSessionEndpoint and contain the following query parameters:

Sign-Out Url Query Parameters

Query Key	Required	Notes
id_token_hint	✅	the inputed idToken parameter
post_logout_redirect_uri		the inputed postLogoutRedirectUri parameter

Return Type

string

fetchTokenByAuthorizationCode

Fetch a token (CodeTokenResponse) by requesting to /oidc/token (by authorization code).

Parameters

Name	Type	Required
tokenEndpoint	string	✅
code	string	✅
codeVerifier	string	✅
clientId	string	✅
redirectUri	string	✅
resource	string

HTTP Request

• Endpoint: /oidc/token
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Payload:

Query Key	Type	Required
grant_type	string: 'authorization_code'	✅
code	string	✅
code_verifier	string	✅
client_id	string	✅
redirect_uri	string	✅
resource	string

Return Type

CodeTokenResponse

Throws

• Fetch failed

fetchTokenByRefreshToken

Fetch a token (RefreshTokenTokenResponse) via /oidc/token (by refresh token).

Parameters

Name	Type	Required
tokenEndpoint	string	✅
clientId	string	✅
refreshToken	string	✅
resource	string
scopes	string[]

HTTP Request

• Endpoint: /oidc/token
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Payload:

Query Key	Type	Required	Notes
grant_type	string: 'refresh_token'	✅
refresh_token	string	✅
client_id	string	✅
resource	string
scope	string		we join the scopes values with space to construct this scope string

Return Type

RefreshTokenTokenResponse

Throws

• Fetch failed

revoke

Request to /oidc/token/revocation API to notify the authorization server that a previously obtained refresh or access token is no longer needed.

Parameters

Name	Type	Notes
revocationEndpoint	string
clientId	string
token	string	token to be revoked

HTTP Request

• Endpoint: /oidc/token/revocation
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Payload:

Query Key	Type
client_id	string
token	string

Return Type

void

Throws

• Revoke failed