0Pricing
Kotlin Academy · Урок

Плагины аутентификации: JWT и сеансы

Защищайте маршруты Ktor с помощью токенов-носителей JWT и аутентификации на основе сеансов.

«Плагины аутентификации: JWT и сеансы» — бесплатный урок Kotlin Academy на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Kotlin Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Kotlin Academy содержит 4 уроков всего.

Обзор аутентификации в Ktor

Плагин Authentication в Ktor предоставляет единый API для защиты маршрутов. Вы настраиваете одного или нескольких провайдеров (JWT, Session, Basic, OAuth и т. д.), а затем оборачиваете маршруты в блок authenticate("providerName") { }.

Добавление зависимостей для аутентификации

Добавьте библиотеки аутентификации и JWT в сборку:

dependencies {
    implementation("io.ktor:ktor-server-auth:2.3.12")
    implementation("io.ktor:ktor-server-auth-jwt:2.3.12")
    implementation("io.ktor:ktor-server-sessions:2.3.12")
}

Настройка аутентификации JWT

Установите плагин Authentication и настройте провайдер JWT. verifier проверяет подпись токена, а validate извлекает принципал из полезной нагрузки:

install(Authentication) {
    jwt("auth-jwt") {
        realm = "ktor app"
        verifier(
            JWT.require(Algorithm.HMAC256(secret))
                .withAudience(audience)
                .withIssuer(issuer)
                .build()
        )
        validate { credential ->
            if (credential.payload.getClaim("username").asString() != null)
                JWTPrincipal(credential.payload)
            else null
        }
    }
}

Защита маршрутов с помощью JWT

Оберните любую группу маршрутов в authenticate("auth-jwt") { }. Неаутентифицированные запросы автоматически получают ответ 401:

routing {
    authenticate("auth-jwt") {
        get("/protected") {
            val principal = call.principal<JWTPrincipal>()!!
            val username = principal.payload.getClaim("username").asString()
            call.respondText("Hello, $username")
        }
    }
}

Выдача токена JWT

Создайте и подпишите JWT в конечной точке входа с помощью библиотеки java-jwt:

post("/login") {
    val user = call.receive<LoginRequest>()
    // validate credentials ...
    val token = JWT.create()
        .withAudience(audience)
        .withIssuer(issuer)
        .withClaim("username", user.username)
        .withExpiresAt(Date(System.currentTimeMillis() + 3_600_000))
        .sign(Algorithm.HMAC256(secret))
    call.respond(mapOf("token" to token))
}

Аутентификация по сессии

Сессии хранят состояние пользователя на сервере (или на стороне клиента в виде подписанных файлов cookie). Установите плагин Sessions и определите класс данных сессии:

data class UserSession(val userId: Long, val username: String)

install(Sessions) {
    cookie<UserSession>("user_session") {
        cookie.path = "/"
        cookie.httpOnly = true
    }
}

Настройка провайдера аутентификации по сессии

Создайте провайдер аутентификации по сессии, который считывает сессию и возвращает принципал:

install(Authentication) {
    session<UserSession>("auth-session") {
        validate { session -> session }
        challenge { call.respond(HttpStatusCode.Unauthorized) }
    }
}

Установка и очистка сессий

Установите сессию после входа с помощью call.sessions.set(), а при выходе очистите её с помощью call.sessions.clear():

post("/login") {
    val creds = call.receive<LoginRequest>()
    // validate ...
    call.sessions.set(UserSession(userId = 1L, username = creds.username))
    call.respond(HttpStatusCode.OK)
}

post("/logout") {
    call.sessions.clear<UserSession>()
    call.respond(HttpStatusCode.OK)
}

JWT и сессии: когда что использовать

JWT: без состояния, хорошо подходит для API, используемых мобильными клиентами и клиентами SPA. Токен содержит все утверждения, поэтому серверу не требуется хранилище сессий. Сессии: с состоянием, хорошо подходят для веб-приложений с отображением страниц на сервере. Идентификатор сессии хранится в cookie, а сервер хранит данные (в памяти, Redis или базе данных).

Объединение нескольких провайдеров аутентификации

Можно определить несколько провайдеров и требовать прохождения аутентификации хотя бы у одного из них с помощью authenticate("jwt", "session") { }. Ktor проверяет провайдеры по очереди и принимает запрос, если проверку успешно проходит хотя бы один провайдер.

Настраиваемые ответы на вызов проверки

У каждого провайдера есть блок challenge, который определяет действия при сбое аутентификации. Возвращайте ответ 401 с телом ошибки в формате JSON вместо стандартного заголовка WWW-Authenticate:

jwt("auth-jwt") {
    // ...
    challenge { _, _ ->
        call.respond(HttpStatusCode.Unauthorized, mapOf("error" to "Token expired or invalid"))
    }
}

Быстрая проверка

Что делает блок validate в провайдере JWT для Ktor?

Повторение: плагины аутентификации — JWT и сессии

Основные выводы:

  • Установите Authentication и настройте провайдеры (jwt, session, basic, oauth)
  • Защищайте маршруты с помощью authenticate("providerName") { }
  • JWT: токены без состояния; подписывайте их при входе, проверяйте с помощью verifier и читайте утверждения в validate
  • Сессии: с состоянием; используйте call.sessions.set() при входе и clear() при выходе
  • Используйте challenge, чтобы настроить формат ответа 401

Часто задаваемые вопросы

Урок «Плагины аутентификации: JWT и сеансы» бесплатный?

Да — полный текст урока «Плагины аутентификации: JWT и сеансы» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Kotlin Academy, подпишись на CoddyKit PRO. Курс Kotlin Academy содержит 4 уроков всего.

Чему я научусь в уроке «Плагины аутентификации: JWT и сеансы»?

Защищайте маршруты Ktor с помощью токенов-носителей JWT и аутентификации на основе сеансов. Ты практикуешь Kotlin Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Kotlin Academy?

Предыдущий опыт не требуется. Kotlin Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Плагины аутентификации: JWT и сеансы»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Kotlin Academy?

Да. Каждый урок Kotlin Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Настройка проекта Ktor: embeddedServer и модули приложения
  2. Маршрутизация и типизированные параметры
  3. Согласование содержимого и kotlinx.serialization
  4. Плагины аутентификации: JWT и сеансы
← Назад к Kotlin Academy