kit-oauth

Библиотека OAuth 2.0 для приложений на Kit

[TOC]

Файлы

Зависимости

Нет зависимостей от пакетов Kit.

Этот пакет использует встроенные модули Kit HTTP и Time. В манифесте пакета запрашивается возможность net, потому что обмен токенами и вспомогательные функции аутентифицированных запросов выполняют HTTP-вызовы.

Установка

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

Использование

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 "Откройте этот URL авторизации:"
  println auth-url

main

Код авторизации

После того как провайдер перенаправит обратно на ваш callback-URL, проверьте, что возвращённый state совпадает с тем, который вы сгенерировали, затем обменяйте код авторизации на токены:

match OAuth.exchange-code http-auth config code
  | Ok tokens ->
    println "Тип токена: ${tokens.token-type}"
    println "Истекает через: ${Int.to-string tokens.expires-in} секунд"
  | Err err ->
    println "Ошибка OAuth: ${err}"

Код авторизации с PKCE

Используйте PKCE для публичных клиентов, таких как десктопные приложения, мобильные приложения и браузерные сценарии:

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 "Получен токен доступа"
  | Err err -> println "Ошибка OAuth: ${err}"

Текущий помощник PKCE использует метод проверки plain. Он структурирован так, чтобы его можно было перевести на S256, когда станет доступна строковая функция SHA256.

Учётные данные клиента

Используйте учётные данные клиента для аутентификации «машина-машина»:

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 "Получен токен доступа"
  | Err err ->
    println "Ошибка OAuth: ${err}"

Токены обновления

match OAuth.refresh-token http-auth config refresh-token
  | Ok tokens -> println "Токен доступа обновлён"
  | Err err -> println "Ошибка обновления: ${err}"

Аутентифицированные запросы

match OAuth.get http-auth "https://api.example.com/user" tokens.access-token
  | Ok response ->
    println "Статус: ${Int.to-string response.status}"
    println response.body
  | Error err ->
    println "Ошибка API: ${err}"

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

match OAuth.post http-auth "https://api.example.com/resources" json-body tokens.access-token
  | Ok response -> println "Создано: ${Int.to-string response.status}"
  | Error err -> println "Ошибка API: ${err}"

Предустановки провайдеров

Встроенные помощники провайдеров возвращают OAuthConfig с заполненными конечными точками авторизации и токенов:

Замечания по безопасности

• Всегда проверяйте значение state колбэка перед обменом кода авторизации.
• Используйте HTTPS redirect URI в production.
• Не логируйте токены доступа, токены обновления, коды авторизации или секреты клиента.
• Храните токены обновления в безопасном хранилище, подходящем для вашего приложения.
• Используйте переменные окружения или менеджер секретов для секретов клиента.
• Относитесь к зафиксированным примерам как к примерам для тестового запуска. Они спроектированы так, чтобы быть безопасными с точки зрения контроля чётности и не взаимодействуют с реальными OAuth-провайдерами.

Разработка

Запуск примеров

Запускайте примеры с помощью интерпретатора:

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

Скомпилируйте пример в нативный бинарный файл:

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

Запуск тестов

Запустите набор тестов:

kit test

Запустите набор тестов с покрытием:

kit test --coverage

Запуск kit dev

Запустите стандартный рабочий процесс разработки:

kit dev

Это выполнит:

1. Проверку форматирования
2. Проверку типов исходных файлов в src/
3. Проверку типов примеров в examples/
4. Запуск тестов в tests/ с покрытием

Запуск проверки чётности

Запустите проверки чётности интерпретатора/компилятора для примеров:

kit parity --failures-only

Примеры используют детерминированный вывод и избегают сетевых вызовов, чтобы при проверке чётности можно было надёжно сравнить вывод интерпретатора и скомпилированного исполняемого файла.

Генерация документации

Сгенерируйте API-документацию из комментариев к документации:

kit doc

Примечание: Исходники Kit с комментариями документации (##) создадут HTML-документы в docs/*.html.

Очистка артефактов сборки

Удалите сгенерированные файлы, кеши, результаты проверки чётности, документацию, файлы блокировки и нативные артефакты сборки:

kit task clean

Примечание: Определено в kit.toml.

Локальная установка

Чтобы установить этот пакет локально для разработки:

kit install

Это установит пакет в ~/.kit/packages/@kit/oauth/, сделав его доступным для импорта как Kit.Oauth в других проектах.

Лицензия

Этот пакет выпущен под лицензией MIT — подробнее см. LICENSE.