kit-oauth

Libreria client OAuth 2.0 per applicazioni Kit

[TOC]

File

Dipendenze

Nessuna dipendenza da pacchetti Kit.

Questo pacchetto utilizza i moduli HTTP e Time integrati di Kit. Il manifesto del pacchetto richiede la capacità net poiché gli helper di scambio di token e richieste autenticate effettuano chiamate HTTP.

Installazione

kit add gitlab.com/kit-lang/packages/kit-oauth.git

Utilizzo

import Kit.Oauth as OAuth

main = fn =>
  config = OAuth.github "client-id" "client-secret" "http://localhost:3000/callback" ["read:user", "user:email"]

  state = OAuth.generate-state
  auth-url = OAuth.authorize-url config state

  println "Open this authorization URL:"
  println auth-url

main

Codice di autorizzazione

Dopo che il provider ha reindirizzato all'URL di callback, convalidare che il state restituito corrisponda a quello generato, quindi scambiare il codice di autorizzazione per i token:

match OAuth.exchange-code http-auth config code
  | Ok tokens ->
    println "Token type: ${tokens.token-type}"
    println "Expires in: ${Int.to-string tokens.expires-in} seconds"
  | Err err ->
    println "OAuth error: ${err}"

Codice di autorizzazione con PKCE

Utilizzare PKCE per client pubblici come app desktop, app mobili e flussi basati su browser:

verifier = "abcdefghijklmnopqrstuvwxyz0123456789-._~abc"
state = OAuth.generate-state
auth-url = OAuth.authorize-url-pkce config state verifier

match OAuth.exchange-code-pkce http-auth config code verifier
  | Ok tokens -> println "Access token received"
  | Err err -> println "OAuth error: ${err}"

L'attuale helper PKCE utilizza il metodo di verifica plain. È strutturato in modo da poter passare a S256 non appena sarà disponibile un helper SHA256 per stringhe.

Credenziali client

Utilizzare le credenziali client per l'autenticazione macchina-macchina:

config = OAuth.custom "client-id" "client-secret" "https://auth.example.com/oauth/authorize" "https://auth.example.com/oauth/token" "https://app.example.com/oauth/callback" ["api:read", "api:write"]

match OAuth.client-credentials http-auth config
  | Ok tokens ->
    println "Access token received"
  | Err err ->
    println "OAuth error: ${err}"

Token di aggiornamento

match OAuth.refresh-token http-auth config refresh-token
  | Ok tokens -> println "Refreshed access token"
  | Err err -> println "Refresh failed: ${err}"

Richieste autenticate

match OAuth.get http-auth "https://api.example.com/user" tokens.access-token
  | Ok response ->
    println "Status: ${Int.to-string response.status}"
    println response.body
  | Error err ->
    println "API error: ${err}"

json-body = "{\"name\":\"Kit\"}"

match OAuth.post http-auth "https://api.example.com/resources" json-body tokens.access-token
  | Ok response -> println "Created: ${Int.to-string response.status}"
  | Error err -> println "API error: ${err}"

Preset dei provider

Gli helper dei provider integrati restituiscono un OAuthConfig con gli endpoint di autorizzazione e token del provider già impostati:

Note sulla sicurezza

• Convalidare sempre il valore state del callback prima di scambiare un codice di autorizzazione.
• Utilizzare URI di reindirizzamento HTTPS in produzione.
• Non registrare token di accesso, token di aggiornamento, codici di autorizzazione o segreti client.
• Archiviare i token di aggiornamento in un archivio sicuro appropriato per la propria applicazione.
• Utilizzare variabili d'ambiente o un gestore di segreti per i segreti client.
• Considerare gli esempi presenti nel repository come esempi di dry-run. Sono progettati per essere sicuri per il test di parità e non contattano provider OAuth reali.

Sviluppo

Esecuzione degli esempi

Eseguire gli esempi con l'interprete:

kit run examples/github.kit
kit run examples/client-credentials.kit

Compilare un esempio in un eseguibile nativo:

kit build examples/github.kit && ./github

Esecuzione dei test

Eseguire la suite di test:

kit test

Eseguire la suite di test con copertura:

kit test --coverage

Esecuzione di kit dev

Eseguire il flusso di lavoro di sviluppo standard:

kit dev

Questo:

1. Controlla la formattazione
2. Controlla i tipi dei file sorgente in src/
3. Controlla i tipi degli esempi in examples/
4. Esegue i test in tests/ con copertura

Esecuzione della parità

Eseguire i controlli di parità interprete/compilatore per gli esempi:

kit parity --failures-only

Gli esempi utilizzano output deterministico e evitano chiamate di rete in tempo reale in modo che la parità possa confrontare in modo affidabile l'output dell'interprete e dell'eseguibile compilato.

Generazione della documentazione

Generare la documentazione dell'API dai commenti doc:

kit doc

Nota: I sorgenti Kit con commenti doc (##) genereranno documenti HTML in docs/*.html.

Pulizia degli artefatti di build

Rimuovere file generati, cache, risultati di parità, documenti, file di lock e artefatti di build nativi:

kit task clean

Nota: Definito in kit.toml.

Installazione locale

Per installare questo pacchetto localmente per lo sviluppo:

kit install

Questo installa il pacchetto in ~/.kit/packages/@kit/oauth/, rendendolo disponibile per l'import come Kit.Oauth in altri progetti.

Licenza

Questo pacchetto è rilasciato sotto la licenza MIT - vedere LICENSE per i dettagli.