kit-oauth

Bibliothèque client OAuth 2.0 pour les applications Kit

[TOC]

Fichiers

Dépendances

Aucune dépendance de paquet Kit.

Ce paquet utilise les modules intégrés HTTP et Time de Kit. Le manifeste demande la capacité net car les helpers d'échange de jetons et de requêtes authentifiées effectuent des appels HTTP.

Installation

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

Utilisation

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

Code d'autorisation

Après que le fournisseur a redirigé vers votre URL de callback, validez que la valeur state retournée correspond à celle que vous avez générée, puis échangez le code d'autorisation contre des jetons :

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}"

Code d'autorisation avec PKCE

Utilisez PKCE pour les clients publics tels que les applications de bureau, les applications mobiles et les flux basés sur navigateur :

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}"

Le helper PKCE actuel utilise la méthode de défi plain. Il est structuré pour pouvoir passer à S256 dès qu'un helper SHA256 pour chaîne sera disponible.

Identifiants client

Utilisez les identifiants client pour l'authentification machine à machine :

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}"

Jetons d'actualisation

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

Requêtes authentifiées

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}"

Presets de fournisseurs

Les helpers intégrés de fournisseur retournent un OAuthConfig avec les points de terminaison d'autorisation et de jeton du fournisseur renseignés :

Notes de sécurité

• Validez toujours la valeur state du callback avant d'échanger un code d'autorisation.
• Utilisez des URI de redirection HTTPS en production.
• Ne journalisez pas les jetons d'accès, les jetons d'actualisation, les codes d'autorisation ou les secrets client.
• Stockez les jetons d'actualisation dans un stockage sécurisé adapté à votre application.
• Utilisez des variables d'environnement ou un gestionnaire de secrets pour les secrets client.
• Considérez les exemples inclus dans le dépôt comme des exemples d'essai à blanc. Ils sont conçus pour être sûrs en termes de parité et ne contactent pas de fournisseurs OAuth réels.

Développement

Exécution des exemples

Exécutez les exemples avec l'interpréteur :

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

Compilez un exemple en binaire natif :

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

Exécution des tests

Lancez la suite de tests :

kit test

Lancez la suite de tests avec couverture :

kit test --coverage

Exécution de kit dev

Lancez le workflow de développement standard :

kit dev

Cela va :

1. Vérifier le formatage
2. Vérifier les types des fichiers sources dans src/
3. Vérifier les types des exemples dans examples/
4. Exécuter les tests dans tests/ avec couverture

Exécution de la parité

Exécutez les vérifications de parité interpréteur/compilateur pour les exemples :

kit parity --failures-only

Les exemples utilisent une sortie déterministe et évitent les appels réseau réels afin que la parité puisse comparer de manière fiable la sortie de l'interpréteur et de l'exécutable compilé.

Génération de la documentation

Générez la documentation API à partir des commentaires de documentation :

kit doc

Remarque : Les sources Kit avec des commentaires de documentation (##) génèrent des documents HTML dans docs/*.html.

Nettoyage des artefacts de construction

Supprimez les fichiers générés, caches, résultats de parité, documentation, fichiers de verrouillage et artefacts de construction natifs :

kit task clean

Remarque : Défini dans kit.toml.

Installation locale

Pour installer ce paquet localement pour le développement :

kit install

Ceci installe le paquet dans ~/.kit/packages/@kit/oauth/, le rendant disponible pour importation sous le nom Kit.Oauth dans d'autres projets.

Licence

Ce paquet est distribué sous la licence MIT - voir LICENSE pour plus de détails.