OAuth клиент для Kotlin: библиотека Ktor OAuth для аутентификации в API

OAuth клиент для Kotlin: библиотека Ktor OAuth

Библиотека Ktor OAuth — это официальное расширение для HTTP-клиента Ktor, предназначенное для реализации протокола OAuth 2.0 в приложениях на Kotlin. Она предоставляет гибкий и типобезопасный способ интеграции с популярными OAuth-провайдерами (Google, GitHub, Facebook, VK и др.), а также поддерживает кастомные эндпоинты. Библиотека входит в экосистему Ktor и может использоваться как в серверных, так и в клиентских Kotlin-приложениях.

Основной сценарий использования — получение токенов доступа для работы с защищёнными REST API. Библиотека автоматизирует процесс обмена авторизационного кода на токены, обновления токенов (refresh token) и управления состоянием сессии.

Ключевые возможности

• Поддержка потоков OAuth 2.0: Authorization Code Grant, Implicit Grant, Client Credentials, Resource Owner Password Credentials.
• Встроенная поддержка популярных провайдеров: Google, GitHub, Facebook, Twitter, VK, Яндекс, Microsoft и др.
• Кастомные провайдеры: возможность задать эндпоинты авторизации, токена и редиректа вручную.
• Автоматическое обновление токенов: поддержка refresh token с автоматическим вызовом при истечении access token.
• Работа с сессиями: хранение токенов в памяти, файлах, базах данных или кастомных хранилищах.
• Интеграция с Ktor Client: единая конфигурация через плагины, поддержка всех транспортов (CIO, Apache, OkHttp).
• Безопасность: поддержка PKCE (Proof Key for Code Exchange) для защиты от CSRF-атак.

Установка

Для подключения библиотеки добавьте зависимость в build.gradle.kts:

dependencies {
    // Основной клиент Ktor
    implementation("io.ktor:ktor-client-core:2.3.7")
    // OAuth плагин
    implementation("io.ktor:ktor-client-auth:2.3.7")
    // Конкретный движок (например, CIO)
    implementation("io.ktor:ktor-client-cio:2.3.7")
}

Для Maven:

<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-auth</artifactId>
    <version>2.3.7</version>
</dependency>

Пример: авторизация через Google OAuth

Создайте HTTP-клиент с OAuth-плагином, настроенным на Google:

import io.ktor.client.*
import io.ktor.client.plugins.auth.*
import io.ktor.client.plugins.auth.providers.*
import io.ktor.client.request.*
import io.ktor.client.statement.*

suspend fun main() {
    val client = HttpClient {
        install(Auth) {
            oauth {
                clientId = System.getenv("GOOGLE_CLIENT_ID")
                clientSecret = System.getenv("GOOGLE_CLIENT_SECRET")
                providerLookup = {
                    OAuthServerSettings.OAuthAuthorizationCodeServerSettings(
                        authorizeUrl = "https://accounts.google.com/o/oauth2/auth",
                        tokenUrl = "https://oauth2.googleapis.com/token",
                        clientId = clientId,
                        clientSecret = clientSecret,
                        redirectUrl = "http://localhost:8080/callback"
                    )
                }
                urlProvider = { request ->
                    // Генерация URL для редиректа пользователя
                    "http://localhost:8080/login"
                }
            }
        }
    }

    // Пример запроса к Google Sheets API
    val response: HttpResponse = client.get("https://sheets.googleapis.com/v4/spreadsheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/values/Sheet1!A1:D5")
    println(response.bodyAsText())
}

Пример: кастомный провайдер с PKCE

Для повышения безопасности используйте PKCE (Proof Key for Code Exchange):

val client = HttpClient {
    install(Auth) {
        oauth {
            clientId = "my-client-id"
            clientSecret = null // Для PKCE секрет не обязателен
            providerLookup = {
                OAuthServerSettings.OAuthAuthorizationCodeServerSettings(
                    authorizeUrl = "https://myapp.com/oauth/authorize",
                    tokenUrl = "https://myapp.com/oauth/token",
                    clientId = clientId,
                    redirectUrl = "http://localhost:8080/callback",
                    pkce = true // Включаем PKCE
                )
            }
            urlProvider = { request ->
                "http://localhost:8080/login"
            }
        }
    }
}

Работа с refresh token

Библиотека автоматически обрабатывает обновление токена, если провайдер поддерживает refresh token