Convenção do Core SDK

Convenções básicas

• O core deve conter apenas funções independentes de plataforma.
• O core deve ser nomeado como {$language} e estar sob o diretório raiz do repositório. Ex.: logto/js/js, logto/kotlin/kotlin.
• O pacote core deve ser nomeado como {$language} sob o escopo Logto. Ex.: @logto/js, io.logto.sdk:kotlin.

Requisitos básicos

Qualquer core SDK deve conter:

• Tipos
• Funções utilitárias
• Funções principais

Tipos

OidcConfigResponse

A configuração do provedor de identidade, que pode ser recuperada via a API /oidc/.well-known/openid-configuration.

Propriedades

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

CodeTokenResponse

Os dados de resposta de /oidc/token (por solicitação de autorização).

Propriedades

Nome	Tipo	Obrigatório
accessToken	string	✅
refreshToken	string
idToken	string	✅
scope	string	✅
expiresIn	number	✅

RefreshTokenResponse

Os dados de resposta de /oidc/token (por token de atualização) ao atualizar tokens por um token de atualização.

Propriedades

Nome	Tipo	Obrigatório
accessToken	string	✅
refreshToken	string	✅
idToken	string
scope	string	✅
expiresIn	number	✅

IdTokenClaims

Reivindicações carregadas pelo token de ID.

Propriedades

Nome	Tipo	Obrigatório
sub	string	✅
aud	string	✅
exp	number	✅
iat	number	✅
iss	string	✅
atHash	string
username	string
name	string
avatar	string

Funções utilitárias

generateCodeVerifier

Gera um verificador de código.
O comprimento do verificador de código é fixado em 64.
O valor de retorno DEVE ser criptografado para uma string em formato base64 segura para URL.

Referência

• PKCE

Parâmetros

Nenhum.

Tipo de Retorno

string

generateCodeChallenge

Gera um desafio de código com base em um verificador de código.
Este método criptografa o verificador de código e retorna o resultado em um formato Base64 seguro para URL.
Nós fixamos o algoritmo de criptografia como SHA-256 no Logto V1.

Referência

• PKCE

Parâmetros

Nome	Tipo	Notas
codeVerifier	string	Gerado por generateCodeVerifier

Tipo de Retorno

string

generateState

"State" é usado para prevenir o ataque CSRF.
O comprimento do "state" é fixado em 64.
A string de resultado a ser retornada DEVE ser criptografada para uma string em formato base64 segura para URL.

Referência

• CSRF

Parâmetros

Nenhum.

Tipo de Retorno

string

decodeIdToken

Decodifica um Token de ID sem verificação de segredo.
Retorna um IdTokenClaims que carrega todas as reivindicações do token na seção de payload.

Parâmetros

Nome	Tipo
token	string

Tipo de Retorno

IdTokenClaims

Lança

• O token não é um JWT válido.

verifyIdToken

Verifica se um Token de ID é legal.

Verificar Chave de Assinatura

OIDC suporta o JSON Web Key Set. Esta função aceita um objeto JsonWebKeySet de uma biblioteca de terceiros (jose) para verificação.

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

Verificar Reivindicações

• Verificar se o iss no Token de ID corresponde ao emissor deste token.
• Verificar se a aud (Público) reivindicação é igual ao ID do cliente.
• Verificar se o tempo atual é anterior ao tempo de expiração.
• Verificar se o tempo de emissão (iat) não é mais do que +/- 1 minuto no tempo atual.

Referência

• OpenID connect core - ID Token Validation

Parâmetros

Nome	Tipo
idToken	string
clientId	string
issuer	string
jwks	JsonWebKeySet

Tipo de Retorno

void

Lança

• Falha na verificação da chave de assinatura
• Falha na verificação das reivindicações

verifyAndParseCodeFromCallbackUri

Verifica se o callbackUri de login é legal e retorna o code extraído do callbackUri.

Verificar URI de Callback

• Verificar se o callbackUri deve começar com redirectUri
• Verificar se não há error no callbackUri (Consulte Resposta de Erro no URI de redirecionamento).
• Verificar se o callbackUri contém state, que deve ser igual ao valor state que você especificou em generateSignInUri.
• Verificar se o callbackUri contém o valor do parâmetro code, que você usará ao solicitar /oidc/token (por token de atualização).

Parâmetros

Nome	Tipo
callbackUri	string
redirectUri	string
state	string

Tipo de Retorno

string

Lança

• Falhas nas verificações

Funções principais

fetchOidcConfig

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

Parâmetros

Nome	Tipo	Notas
endpoint	string	O endpoint do serviço OIDC

Tipo de Retorno

OidcConfigResponse

Lança

• Falha na busca

generateSignInUri

Parâmetros

Nome	Tipo	Obrigatório	Notas
authorizationEndpoint	string	✅
clientId	string	✅
redirectUri	string	✅
codeChallenge	string	✅
state	string	✅
scopes	string[]		A implementação pode variar de acordo com as especificações da linguagem.
resources	string[]		A implementação pode variar de acordo com as especificações da linguagem.
prompt	string		Padrão: consent.

A URL será gerada com base em authorizationEndpoint e conterá os seguintes parâmetros de consulta:

Parâmetros de Consulta da URL de Login

Chave de Consulta	Obrigatório	Notas
client_id	✅
redirect_uri	✅
code_challenge	✅
code_challenge_method	✅	Fixado como S256.
state	✅
scope	✅	scope sempre contém openid e offline_access, mesmo que o escopo de entrada forneça um valor nulo ou vazio.
resource		Podemos adicionar resource à uri mais de uma vez, o backend os converterá como uma lista. ex. resource=a&resource=b
response_type	✅	Fixado como code.
prompt	✅

Tipo de Retorno

string

generateSignOutUri

Parâmetros

Nome	Tipo	Obrigatório
endSessionEndpoint	string	✅
idToken	string	✅
postLogoutRedirectUri	string

A URL a ser gerada será baseada em endSessionEndpoint e conterá os seguintes parâmetros de consulta:

Parâmetros de Consulta da URL de Logout

Chave de Consulta	Obrigatório	Notas
id_token_hint	✅	o parâmetro idToken informado
post_logout_redirect_uri		o parâmetro postLogoutRedirectUri informado

Tipo de Retorno

string

fetchTokenByAuthorizationCode

Busca um token (CodeTokenResponse) solicitando a /oidc/token (por código de autorização).

Parâmetros

Nome	Tipo	Obrigatório
tokenEndpoint	string	✅
code	string	✅
codeVerifier	string	✅
clientId	string	✅
redirectUri	string	✅
resource	string

Requisição HTTP

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

Chave de Consulta	Tipo	Obrigatório
grant_type	string: 'authorization_code'	✅
code	string	✅
code_verifier	string	✅
client_id	string	✅
redirect_uri	string	✅
resource	string

Tipo de Retorno

CodeTokenResponse

Lança

• Falha na busca

fetchTokenByRefreshToken

Busca um token (RefreshTokenTokenResponse) via /oidc/token (por token de atualização).

Parâmetros

Nome	Tipo	Obrigatório
tokenEndpoint	string	✅
clientId	string	✅
refreshToken	string	✅
resource	string
scopes	string[]

Requisição HTTP

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

Chave de Consulta	Tipo	Obrigatório	Notas
grant_type	string: 'refresh_token'	✅
refresh_token	string	✅
client_id	string	✅
resource	string
scope	string		unimos os valores de scopes com espaço para construir esta string scope

Tipo de Retorno

RefreshTokenTokenResponse

Lança

• Falha na busca

revoke

Solicita à API /oidc/token/revocation para notificar o servidor de autorização que um token de atualização ou acesso obtido anteriormente não é mais necessário.

Parâmetros

Nome	Tipo	Notas
revocationEndpoint	string
clientId	string
token	string	token a ser revogado

Requisição HTTP

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

Chave de Consulta	Tipo
client_id	string
token	string

Tipo de Retorno

void

Lança

• Falha na revogação