Core SDK-Konvention

Grundlegende Konventionen

• Der Kern sollte nur plattformunabhängige Funktionen enthalten.
• Der Kern sollte als {$language} benannt und im Stammverzeichnis des Repositories abgelegt werden. Z.B. logto/js/js, logto/kotlin/kotlin.
• Das Kernpaket sollte unter dem Logto-Scope als {$language} benannt werden. Z.B. @logto/js, io.logto.sdk:kotlin.

Grundlegende Anforderungen

Jedes Core SDK sollte enthalten:

• Typen
• Hilfsfunktionen
• Kernfunktionen

Typen

OidcConfigResponse

Die Konfiguration des Identitätsanbieters, die über die /oidc/.well-known/openid-configuration API abgerufen werden kann.

Eigenschaften

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

CodeTokenResponse

Die Antwortdaten von /oidc/token (durch Autorisierungscode).

Eigenschaften

Name	Typ	Erforderlich
accessToken	string	✅
refreshToken	string
idToken	string	✅
scope	string	✅
expiresIn	number	✅

RefreshTokenResponse

Die Antwortdaten von /oidc/token (durch Auffrischungstoken), wenn Tokens durch ein Auffrischungstoken aktualisiert werden.

Eigenschaften

Name	Typ	Erforderlich
accessToken	string	✅
refreshToken	string	✅
idToken	string
scope	string	✅
expiresIn	number	✅

IdTokenClaims

Ansprüche, die vom ID-Token getragen werden.

Eigenschaften

Name	Typ	Erforderlich
sub	string	✅
aud	string	✅
exp	number	✅
iat	number	✅
iss	string	✅
atHash	string
username	string
name	string
avatar	string

Hilfsfunktionen

generateCodeVerifier

Generiere einen Code-Verifier.
Die Länge des Code-Verifiers ist fest auf 64 eingestellt.
Der Rückgabewert MUSS in einen URL-sicheren Base64-Format-String verschlüsselt werden.

Referenz

• PKCE

Parameter

Keine.

Rückgabetyp

string

generateCodeChallenge

Generiere eine Code-Challenge basierend auf einem Code-Verifier.
Diese Methode verschlüsselt den Code-Verifier und gibt das Ergebnis in einem URL-sicheren Base64-Format zurück.
Wir haben den Verschlüsselungsalgorithmus in Logto V1 fest auf SHA-256 eingestellt.

Referenz

• PKCE

Parameter

Name	Typ	Anmerkungen
codeVerifier	string	Generiert durch generateCodeVerifier

Rückgabetyp

string

generateState

"State" wird verwendet, um CSRF-Angriffe zu verhindern.
Die Länge des "State" ist fest auf 64 eingestellt.
Der zurückzugebende Ergebnisstring MUSS in einen URL-sicheren Base64-Format-String verschlüsselt werden.

Referenz

• CSRF

Parameter

Keine.

Rückgabetyp

string

decodeIdToken

Dekodiere ein ID-Token ohne geheime Überprüfung.
Gibt ein IdTokenClaims zurück, das alle Token-Ansprüche im Payload-Abschnitt enthält.

Parameter

Name	Typ
token	string

Rückgabetyp

IdTokenClaims

Ausnahmen

• Das token ist kein gültiges JWT.

verifyIdToken

Überprüfe, ob ein ID-Token legal ist.

Überprüfung des Signaturschlüssels

OIDC unterstützt das JSON Web Key Set. Diese Funktion akzeptiert ein JsonWebKeySet-Objekt aus einer Drittanbieterbibliothek (jose) zur Überprüfung.

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

Überprüfung der Ansprüche

• Überprüfe, ob der iss im ID-Token mit dem Aussteller dieses Tokens übereinstimmt.
• Überprüfe, ob der aud (Zielgruppe) Anspruch gleich der Client-ID ist.
• Überprüfe, ob die aktuelle Zeit vor der Ablaufzeit liegt.
• Überprüfe, ob die Ausstellungszeit (iat) nicht mehr als +/- 1 Minute von der aktuellen Zeit abweicht.

Referenz

• OpenID Connect Core - ID Token Validation

Parameter

Name	Typ
idToken	string
clientId	string
issuer	string
jwks	JsonWebKeySet

Rückgabetyp

void

Ausnahmen

• Überprüfung des Signaturschlüssels fehlgeschlagen
• Überprüfung der Ansprüche fehlgeschlagen

verifyAndParseCodeFromCallbackUri

Überprüfe, ob die Anmelde-Callback-URI legal ist, und gib den code zurück, der aus der Callback-URI extrahiert wurde.

Überprüfung der Callback-URI

• Überprüfe, ob die callbackUri mit redirectUri beginnt
• Überprüfe, ob kein error in der callbackUri vorhanden ist (siehe Fehlerantwort in der Redirect-URI).
• Überprüfe, ob die callbackUri state enthält, das dem state-Wert entsprechen sollte, den du in generateSignInUri angegeben hast.
• Überprüfe, ob die callbackUri den Parameterwert code enthält, den du bei der Anforderung an /oidc/token (durch Auffrischungstoken) verwenden wirst.

Parameter

Name	Typ
callbackUri	string
redirectUri	string
state	string

Rückgabetyp

string

Ausnahmen

• Überprüfungen fehlgeschlagen

Kernfunktionen

fetchOidcConfig

Gibt OidcConfigResponse zurück, indem eine Anfrage an /oidc/.well-known/openid-configuration gestellt wird.

Parameter

Name	Typ	Anmerkungen
endpoint	string	Der OIDC-Service-Endpunkt

Rückgabetyp

OidcConfigResponse

Ausnahmen

• Abruf fehlgeschlagen

generateSignInUri

Parameter

Name	Typ	Erforderlich	Anmerkungen
authorizationEndpoint	string	✅
clientId	string	✅
redirectUri	string	✅
codeChallenge	string	✅
state	string	✅
scopes	string[]		Die Implementierung kann je nach Sprachspezifikationen variieren.
resources	string[]		Die Implementierung kann je nach Sprachspezifikationen variieren.
prompt	string		Standard: consent.

Die URL wird basierend auf authorizationEndpoint generiert und enthält die folgenden Abfrageparameter:

Anmelde-URL-Abfrageparameter

Abfrage-Schlüssel	Erforderlich	Anmerkungen
client_id	✅
redirect_uri	✅
code_challenge	✅
code_challenge_method	✅	Fest auf S256 eingestellt.
state	✅
scope	✅	scope enthält immer openid und offline_access, auch wenn der Eingabebereich einen null oder leeren Bereichswert liefert.
resource		Wir können resource mehrmals zur URI hinzufügen, der Backend wird sie als Liste konvertieren. z.B. resource=a&resource=b
response_type	✅	Fest auf code eingestellt.
prompt	✅

Rückgabetyp

string

generateSignOutUri

Parameter

Name	Typ	Erforderlich
endSessionEndpoint	string	✅
idToken	string	✅
postLogoutRedirectUri	string

Die zu generierende URL basiert auf endSessionEndpoint und enthält die folgenden Abfrageparameter:

Abmelde-URL-Abfrageparameter

Abfrage-Schlüssel	Erforderlich	Anmerkungen
id_token_hint	✅	der eingegebene idToken-Parameter
post_logout_redirect_uri		der eingegebene postLogoutRedirectUri-Parameter

Rückgabetyp

string

fetchTokenByAuthorizationCode

Hole ein Token (CodeTokenResponse), indem eine Anfrage an /oidc/token (durch Autorisierungscode) gestellt wird.

Parameter

Name	Typ	Erforderlich
tokenEndpoint	string	✅
code	string	✅
codeVerifier	string	✅
clientId	string	✅
redirectUri	string	✅
resource	string

HTTP-Anfrage

• Endpunkt: /oidc/token
• Methode: POST
• Content-Type: application/x-www-form-urlencoded
• Nutzlast:

Abfrage-Schlüssel	Typ	Erforderlich
grant_type	string: 'authorization_code'	✅
code	string	✅
code_verifier	string	✅
client_id	string	✅
redirect_uri	string	✅
resource	string

Rückgabetyp

CodeTokenResponse

Ausnahmen

• Abruf fehlgeschlagen

fetchTokenByRefreshToken

Hole ein Token (RefreshTokenTokenResponse) über /oidc/token (durch Auffrischungstoken).

Parameter

Name	Typ	Erforderlich
tokenEndpoint	string	✅
clientId	string	✅
refreshToken	string	✅
resource	string
scopes	string[]

HTTP-Anfrage

• Endpunkt: /oidc/token
• Methode: POST
• Content-Type: application/x-www-form-urlencoded
• Nutzlast:

Abfrage-Schlüssel	Typ	Erforderlich	Anmerkungen
grant_type	string: 'refresh_token'	✅
refresh_token	string	✅
client_id	string	✅
resource	string
scope	string		wir verbinden die scopes-Werte mit Leerzeichen, um diesen scope-String zu konstruieren

Rückgabetyp

RefreshTokenTokenResponse

Ausnahmen

• Abruf fehlgeschlagen

revoke

Anfrage an die /oidc/token/revocation API, um den Autorisierungsserver darüber zu informieren, dass ein zuvor erhaltenes Auffrischungs- oder Zugangstoken nicht mehr benötigt wird.

Parameter

Name	Typ	Anmerkungen
revocationEndpoint	string
clientId	string
token	string	zu widerrufendes Token

HTTP-Anfrage

• Endpunkt: /oidc/token/revocation
• Methode: POST
• Content-Type: application/x-www-form-urlencoded
• Nutzlast:

Abfrage-Schlüssel	Typ
client_id	string
token	string

Rückgabetyp

void

Ausnahmen

• Widerruf fehlgeschlagen