Skip to main content
Version: 1.x

Core

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

NameType
authorizationEndpointstring
tokenEndpointstring
endSessionEndpointstring
revocationEndpointstring
jwksUristring
issuerstring
CodeTokenResponse

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

Properties

NameTypeRequired
accessTokenstringโœ…
refreshTokenstring
idTokenstringโœ…
scopestringโœ…
expiresInnumberโœ…
RefreshTokenResponse

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

Properties

NameTypeRequired
accessTokenstringโœ…
refreshTokenstringโœ…
idTokenstring
scopestringโœ…
expiresInnumberโœ…
IdTokenClaims

Claims carried by the id token.

Properties

NameTypeRequired
substringโœ…
audstringโœ…
expnumberโœ…
iatnumberโœ…
issstringโœ…
atHashstring
usernamestring
namestring
avatarstring

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

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

Parameters

NameTypeNotes
codeVerifierstringGenerated 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

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

NameType
tokenstring

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

Parameters

NameType
idTokenstring
clientIdstring
issuerstring
jwksJsonWebKeySet

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

NameType
callbackUristring
redirectUristring
statestring

Return Type

string

Throws

  • Verifications failed

Core Functionsโ€‹

fetchOidcConfig

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

Parameters

NameTypeNotes
endpointstringThe OIDC service endpoint

Return Type

OidcConfigResponse

Throws

  • Fetch failed
generateSignInUri

Parameters

NameTypeRequiredNotes
authorizationEndpointstringโœ…
clientIdstringโœ…
redirectUristringโœ…
codeChallengestringโœ…
statestringโœ…
scopesstring[]The implementation may vary according to language specifications.
resourcesstring[]The implementation may vary according to language specifications.
promptstringDefault: consent.

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

Sign-In Url Query Parameters

Query KeyRequiredNotes
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.
resourceWe 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

NameTypeRequired
endSessionEndpointstringโœ…
idTokenstringโœ…
postLogoutRedirectUristring

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

Sign-Out Url Query Parameters

Query KeyRequiredNotes
id_token_hintโœ…the inputed idToken parameter
post_logout_redirect_urithe inputed postLogoutRedirectUri parameter

Return Type

string

fetchTokenByAuthorizationCode

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

Parameters

NameTypeRequired
tokenEndpointstringโœ…
codestringโœ…
codeVerifierstringโœ…
clientIdstringโœ…
redirectUristringโœ…
resourcestring

HTTP Request

  • Endpoint: /oidc/token
  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Payload:
Query KeyTypeRequired
grant_typestring: 'authorization_code'โœ…
codestringโœ…
code_verifierstringโœ…
client_idstringโœ…
redirect_uristringโœ…
resourcestring

Return Type

CodeTokenResponse

Throws

  • Fetch failed
fetchTokenByRefreshToken

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

Parameters

NameTypeRequired
tokenEndpointstringโœ…
clientIdstringโœ…
refreshTokenstringโœ…
resourcestring
scopesstring[]

HTTP Request

  • Endpoint: /oidc/token
  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Payload:
Query KeyTypeRequiredNotes
grant_typestring: 'refresh_token'โœ…
refresh_tokenstringโœ…
client_idstringโœ…
resourcestring
scopestringwe 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

NameTypeNotes
revocationEndpointstring
clientIdstring
tokenstringtoken to be revoked

HTTP Request

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

Return Type

void

Throws

  • Revoke failed