Skip to content

Ktor Server での Bearer 認証 ​

必要な依存関係: io.ktor:ktor-server-auth

コード例: auth-bearer

Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

Bearer 認証スキームは、アクセス制御と認証に使用される HTTP フレームワーク の一部です。このスキームには、Bearer トークンと呼ばれるセキュリティトークンが使用されます。Bearer 認証スキームは OAuth や JWT の一部として使用されますが、Bearer トークンを認可するためのカスタムロジックを提供することもできます。

Ktor における認証全般に関する情報は、Ktor Server での認証と認可 セクションで確認できます。

Bearer 認証は、HTTPS/TLS 経由でのみ使用してください。

依存関係の追加 ​

bearer 認証を有効にするには、ビルドスクリプトに ktor-server-auth アーティファクトを含める必要があります。

kotlin
implementation(ktorLibs.server.auth)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.server.auth
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

Bearer 認証フロー ​

一般的に、Bearer 認証のフローは以下のようになります。

  1. ユーザーの認証とアクセスの認可が正常に行われた後、サーバーはクライアントにアクセストークンを返します。
  2. クライアントは、Bearer スキーマを使用して Authorization ヘッダーにトークンを渡すことで、保護されたリソースにリクエストを送信できます。
    HTTP
    GET http://localhost:8080/
    Authorization: Bearer abc123
  3. サーバーがリクエストを受信し、トークンを検証します。
  4. 検証後、サーバーは保護されたリソースのコンテンツで応答します。

Bearer 認証のインストール ​

bearer 認証プロバイダーをインストールするには、install ブロック内で bearer 関数を呼び出します。

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    bearer {
        // Bearer 認証を設定
    }
}

オプションで、特定のルートを認証するために使用できるプロバイダー名を指定できます。

Bearer 認証の設定 ​

Ktor でさまざまな認証プロバイダーを設定する方法の概要については、認証の設定 を参照してください。このセクションでは、bearer 認証プロバイダー固有の設定について見ていきます。

ステップ 1: Bearer プロバイダーの設定 ​

bearer 認証プロバイダーは、BearerAuthenticationProvider.Configuration クラスを介して設定を公開しています。以下の例では、次の設定が指定されています。

  • realm プロパティは、WWW-Authenticate ヘッダーに渡されるレルムを設定します。
  • authenticate 関数はクライアントから送信されたトークンをチェックし、認証に成功した場合は UserIdPrincipal を、失敗した場合は null を返します。
kotlin
install(Authentication) {
    bearer("auth-bearer") {
        realm = "Access to the '/' path"
        authenticate { tokenCredential ->
            if (tokenCredential.token == "abc123") {
                UserIdPrincipal("jetbrains")
            } else {
                null
            }
        }
    }
}

型安全な認証スキーム API は実験的です。いつでも廃止または変更される可能性があります。 オプトインが必要です。詳細については、 型安全な認証のドキュメント を参照してください。

bearer() 関数は、任意のプリンシパル型のスキームを作成します。install(Authentication) ステップはありません。スキームは、それを必要とするルートに渡す値です。

kotlin
data class User(val name: String)

val bearerAuth = bearer<User>("auth-bearer") {
    realm = "Access to the '/' path"
    validate { tokenCredential ->
        if (tokenCredential.token == "abc123") {
            User("jetbrains")
        } else {
            null
        }
    }
}

名前に変更があることに注意してください。従来のプロバイダーでは authenticate を使用しますが、他の型安全スキームと同様に、型安全スキームでは validate を使用します。これは定義したプリンシパル型を返し、認証に失敗した場合は null を返します。

また、authHeader を設定して Authorization ヘッダー以外の場所からトークンを読み取ったり、authSchemes を設定して Bearer 以外のスキームを受け入れたりすることもできます。完全な API については、型安全な認証 を参照してください。

ステップ 2: 特定のリソースの保護 ​

bearer プロバイダーを設定した後は、authenticate 関数を使用してアプリケーション内の特定のリソースを保護できます。認証に成功した場合、ルートハンドラー内で call.principal 関数を使用して認証済みの UserIdPrincipal を取得し、認証されたユーザーの名前を取得できます。

kotlin
routing {
    authenticate("auth-bearer") {
        get("/") {
            val user = call.principal<UserIdPrincipal>()
            call.respondText("Hello, ${user?.name}!")
        }
    }
}

スキームを authenticateWith() に渡します。ブロック内では、call.principal は指定したプリンシパル型となり、決して null にならないため、キャストや null チェックは不要です:

kotlin
routing {
    authenticateWith(bearerAuth) {
        get("/") {
            call.respondText("Hello, ${call.principal.name}!")
        }
    }
}