Convención del Core SDK

Convenciones básicas

• El núcleo debe contener solo funciones independientes de la plataforma.
• El núcleo debe nombrarse como {$language} y estar bajo el directorio raíz del repositorio. Por ejemplo, logto/js/js, logto/kotlin/kotlin.
• El paquete del núcleo debe nombrarse como {$language} bajo el ámbito de Logto. Por ejemplo, @logto/js, io.logto.sdk:kotlin.

Requisitos básicos

Cualquier Core SDK debe contener:

• Tipos
• Funciones utilitarias
• Funciones principales

Tipos

OidcConfigResponse

La configuración del proveedor de identidad, que se puede obtener a través de la API /oidc/.well-known/openid-configuration.

Propiedades

Nombre	Tipo
authorizationEndpoint	string
tokenEndpoint	string
endSessionEndpoint	string
revocationEndpoint	string
jwksUri	string
issuer	string

CodeTokenResponse

Los datos de respuesta de /oidc/token (por código de autorización).

Propiedades

Nombre	Tipo	Requerido
accessToken	string	✅
refreshToken	string
idToken	string	✅
scope	string	✅
expiresIn	number	✅

RefreshTokenResponse

Los datos de respuesta de /oidc/token (por token de actualización) al refrescar tokens mediante un token de actualización.

Propiedades

Nombre	Tipo	Requerido
accessToken	string	✅
refreshToken	string	✅
idToken	string
scope	string	✅
expiresIn	number	✅

IdTokenClaims

Reclamos llevados por el token de ID.

Propiedades

Nombre	Tipo	Requerido
sub	string	✅
aud	string	✅
exp	number	✅
iat	number	✅
iss	string	✅
atHash	string
username	string
name	string
avatar	string

Funciones utilitarias

generateCodeVerifier

Generar un verificador de código.
La longitud del verificador de código está codificada como 64.
El valor de retorno DEBE estar encriptado a una cadena en formato base64 segura para URL.

Referencia

• PKCE

Parámetros

Ninguno.

Tipo de retorno

string

generateCodeChallenge

Generar un desafío de código basado en un verificador de código.
Este método encripta el verificador de código y devuelve el resultado en un formato Base64 seguro para URL.
Codificamos el algoritmo de encriptación como SHA-256 en Logto V1.

Referencia

• PKCE

Parámetros

Nombre	Tipo	Notas
codeVerifier	string	Generado por generateCodeVerifier

Tipo de retorno

string

generateState

"State" se utiliza para prevenir el ataque CSRF.
La longitud del "state" está codificada como 64.
La cadena de resultado que se devolverá DEBE estar encriptada a una cadena en formato base64 segura para URL.

Referencia

• CSRF

Parámetros

Ninguno.

Tipo de retorno

string

decodeIdToken

Decodificar un Token de ID sin verificación secreta.
Devuelve un IdTokenClaims que lleva todos los reclamos del token en la sección de carga útil.

Parámetros

Nombre	Tipo
token	string

Tipo de retorno

IdTokenClaims

Lanza

• El token no es un JWT válido.

verifyIdToken

Verificar si un Token de ID es legal.

Verificar clave de firma

OIDC admite el JSON Web Key Set. Esta función acepta un objeto JsonWebKeySet de una biblioteca de terceros (jose) para la verificación.

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

Verificar reclamos

• Verificar que el iss en el Token de ID coincida con el emisor de este token.
• Verificar que el reclamo aud (audiencia) sea igual al ID del cliente.
• Verificar que el tiempo actual sea antes del tiempo de expiración.
• Verificar que el tiempo de emisión (iat) no sea más de +/- 1 minuto respecto al tiempo actual.

Referencia

• OpenID connect core - Validación del Token de ID

Parámetros

Nombre	Tipo
idToken	string
clientId	string
issuer	string
jwks	JsonWebKeySet

Tipo de retorno

void

Lanza

• Fallo en la verificación de la clave de firma
• Fallo en la verificación de reclamos

verifyAndParseCodeFromCallbackUri

Verificar que el callbackUri de inicio de sesión sea legal y devolver el code extraído de callbackUri.

Verificar URI de Callback

• Verificar que el callbackUri comience con redirectUri
• Verificar que no haya error en el callbackUri (Consultar Respuesta de Error en el URI de redirección).
• Verificar que el callbackUri contenga state, que debe ser igual al valor state que especificaste en generateSignInUri.
• Verificar que el callbackUri contenga el valor del parámetro code, que usarás al solicitar a /oidc/token (por token de actualización).

Parámetros

Nombre	Tipo
callbackUri	string
redirectUri	string
state	string

Tipo de retorno

string

Lanza

• Fallos en las verificaciones

Funciones principales

fetchOidcConfig

Devuelve OidcConfigResponse solicitando a /oidc/.well-known/openid-configuration.

Parámetros

Nombre	Tipo	Notas
endpoint	string	El endpoint del servicio OIDC

Tipo de retorno

OidcConfigResponse

Lanza

• Fallo en la obtención

generateSignInUri

Parámetros

Nombre	Tipo	Requerido	Notas
authorizationEndpoint	string	✅
clientId	string	✅
redirectUri	string	✅
codeChallenge	string	✅
state	string	✅
scopes	string[]		La implementación puede variar según las especificaciones del lenguaje.
resources	string[]		La implementación puede variar según las especificaciones del lenguaje.
prompt	string		Predeterminado: consent.

La URL se generará basada en authorizationEndpoint y contendrá los siguientes parámetros de consulta:

Parámetros de consulta de la URL de inicio de sesión

Clave de consulta	Requerido	Notas
client_id	✅
redirect_uri	✅
code_challenge	✅
code_challenge_method	✅	Codificado como S256.
state	✅
scope	✅	scope siempre contiene openid y offline_access, incluso si el scope de entrada proporciona un valor nulo o vacío.
resource		Podemos agregar resource a uri más de una vez, el backend los convertirá en una lista. e.g. resource=a&resource=b
response_type	✅	Codificado como code.
prompt	✅

Tipo de retorno

string

generateSignOutUri

Parámetros

Nombre	Tipo	Requerido
endSessionEndpoint	string	✅
idToken	string	✅
postLogoutRedirectUri	string

La URL a generar se basará en endSessionEndpoint y contendrá los siguientes parámetros de consulta:

Parámetros de consulta de la URL de cierre de sesión

Clave de consulta	Requerido	Notas
id_token_hint	✅	el parámetro idToken ingresado
post_logout_redirect_uri		el parámetro postLogoutRedirectUri ingresado

Tipo de retorno

string

fetchTokenByAuthorizationCode

Obtener un token (CodeTokenResponse) solicitando a /oidc/token (por código de autorización).

Parámetros

Nombre	Tipo	Requerido
tokenEndpoint	string	✅
code	string	✅
codeVerifier	string	✅
clientId	string	✅
redirectUri	string	✅
resource	string

Solicitud HTTP

• Endpoint: /oidc/token
• Método: POST
• Content-Type: application/x-www-form-urlencoded
• Carga útil:

Clave de consulta	Tipo	Requerido
grant_type	string: 'authorization_code'	✅
code	string	✅
code_verifier	string	✅
client_id	string	✅
redirect_uri	string	✅
resource	string

Tipo de retorno

CodeTokenResponse

Lanza

• Fallo en la obtención

fetchTokenByRefreshToken

Obtener un token (RefreshTokenTokenResponse) a través de /oidc/token (por token de actualización).

Parámetros

Nombre	Tipo	Requerido
tokenEndpoint	string	✅
clientId	string	✅
refreshToken	string	✅
resource	string
scopes	string[]

Solicitud HTTP

• Endpoint: /oidc/token
• Método: POST
• Content-Type: application/x-www-form-urlencoded
• Carga útil:

Clave de consulta	Tipo	Requerido	Notas
grant_type	string: 'refresh_token'	✅
refresh_token	string	✅
client_id	string	✅
resource	string
scope	string		unimos los valores de scopes con espacio para construir esta cadena scope

Tipo de retorno

RefreshTokenTokenResponse

Lanza

• Fallo en la obtención

revoke

Solicitar a la API /oidc/token/revocation para notificar al servidor de autorización que un token de actualización o acceso previamente obtenido ya no es necesario.

Parámetros

Nombre	Tipo	Notas
revocationEndpoint	string
clientId	string
token	string	token a revocar

Solicitud HTTP

• Endpoint: /oidc/token/revocation
• Método: POST
• Content-Type: application/x-www-form-urlencoded
• Carga útil:

Clave de consulta	Tipo
client_id	string
token	string

Tipo de retorno

void

Lanza

• Fallo en la revocación