Kotlin Academy · レッスン

認証プラグイン：JWTとSession

Q: 「認証プラグイン：JWTとSession」で何を学びますか？

JWTベアラートークンとセッションベース認証でKtorのルートを保護します。 ブラウザで直接実行するハンズオンコードでKotlin Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

JWTベアラートークンとセッションベース認証でKtorのルートを保護します。

「認証プラグイン：JWTとSession」はCoddyKit上の無料Kotlin Academyレッスンです。これはレッスン4/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはKotlin Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Kotlin Academyコースには全4レッスンが含まれています。

Ktorの認証概要

KtorのAuthenticationプラグインは、ルートを保護するための統一されたAPIを提供します。1つ以上のプロバイダー（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トークンの発行

java-jwtライブラリを使用して、ログインエンドポイントで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とSession：使い分け

JWT：ステートレスで、モバイル／SPAクライアントから利用されるAPIに適しています。トークンがすべてのクレームを保持するため、サーバーにセッションストアは必要ありません。Sessions：ステートフルで、サーバーサイドレンダリングのWebアプリに適しています。CookieにはセッションIDを保存し、サーバーがデータ（メモリ、Redis、DB）を保持します。

複数の認証プロバイダーの組み合わせ

複数のプロバイダーを定義し、authenticate("jwt", "session") { }を使用して、いずれかのプロバイダーによる認証を必須にできます。Ktorは各プロバイダーを順番に試し、いずれかのプロバイダーで正常に検証できればリクエストを受け付けます。

チャレンジレスポンスのカスタマイズ

各プロバイダーには、認証に失敗したときの処理を定義するchallengeブロックがあります。デフォルトのWWW-Authenticateヘッダーの代わりに、JSON形式のエラーボディを含む401を返します：

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

クイックチェック

KtorのJWTプロバイダーにあるvalidateブロックは何を行いますか？

振り返り：認証プラグイン — JWTとSession

重要なポイント：

Authenticationをインストールし、プロバイダー（jwt、session、basic、oauth）を設定します
authenticate("providerName") { }でルートを保護します
JWT：ステートレスなトークンです。ログイン時に署名し、verifierで検証し、validateでクレームを読み取ります
Sessions：ステートフルです。ログイン時にcall.sessions.set()を、ログアウト時にclear()を使用します
challengeで401レスポンスの形式をカスタマイズします

よくある質問

「認証プラグイン：JWTとSession」レッスンは無料ですか？

はい。「認証プラグイン：JWTとSession」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Kotlin Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Kotlin Academyコースには全4レッスンが含まれています。

「認証プラグイン：JWTとSession」で何を学びますか？

JWTベアラートークンとセッションベース認証でKtorのルートを保護します。ブラウザで直接実行するハンズオンコードでKotlin Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Kotlin Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのKotlin Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン4/4です。

「認証プラグイン：JWTとSession」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このKotlin Academyレッスンでコードを書いて実行できますか？

はい。すべてのKotlin Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

Ktorプロジェクトのセットアップ：embeddedServerとApplicationモジュール
ルーティングと型付きパラメータ
Content Negotiationとkotlinx.serialization
認証プラグイン：JWTとSession

← Kotlin Academyに戻る