Skip to content
Server Plugin

Ktor Serverにおける認証と認可

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

Ktorは、認証と認可を処理するためのAuthenticationプラグインを提供しています。一般的なユースケースとしては、ユーザーのログイン、特定のリソースへのアクセス許可、関係者間での安全な情報伝送などがあります。また、AuthenticationをSessionsと組み合わせて使用し、リクエスト間でユーザー情報を保持することもできます。

クライアント側では、Ktorは認証と認可を処理するためのAuthenticationプラグインを提供しています。

サポートされている認証タイプ ​

Ktorは以下の認証および認可スキームをサポートしています。

HTTP認証 ​

HTTPは、アクセス制御と認証のための一般的なフレームワークを提供しています。Ktorでは、以下のHTTP認証スキームを使用できます。

  • Basic - Base64エンコーディングを使用してユーザー名とパスワードを提供します。HTTPSと組み合わせて使用しない限り、一般的には推奨されません。
  • Digest - ユーザー名とパスワードにハッシュ関数を適用することにより、暗号化された形式でユーザーのクレデンシャルを通信する認証方式です。
  • Bearer - ベアラートークン(Bearer token)と呼ばれるセキュリティトークンを使用する認証スキームです。 Bearer認証スキームはOAuthやJWTの一部として使用されますが、ベアラートークンを認可するためのカスタムロジックを提供することも可能です。
  • API Key - クライアントがヘッダーに秘密鍵(シークレットキー)を渡すシンプルな認証方式です。

フォームベース認証 ​

フォームベース認証は、Webフォームを使用してクレデンシャル情報を収集し、ユーザーを認証します。

JSON Web Tokens (JWT) ​

JSON Web Tokenは、JSONオブジェクトとして関係者間で安全に情報を伝送するためのオープンスタンダードです。JSON Web Tokensは認可に使用できます。ユーザーがログインすると、各リクエストにトークンが含まれ、そのトークンで許可されているリソースへのアクセスが可能になります。Ktorでは、jwt認証を使用してトークンを検証し、トークン内に含まれるクレーム(claims)の妥当性を確認できます。

LDAP ​

LDAPは、ディレクトリサービスの認証に使用されるオープンなクロスプラットフォームプロトコルです。Ktorは、指定されたLDAPサーバーに対してユーザーのクレデンシャルを認証するためのldapAuthenticate関数を提供しています。

OAuth ​

OAuthは、APIへの安全なアクセスを実現するためのオープンスタンダードです。Ktorのoauthプロバイダーを使用すると、Google、Facebook、Twitterなどの外部プロバイダーを利用した認証を実装できます。

OpenID Connect ​

OpenID Connectは、OAuth 2.0の上に構築されたアイデンティティ層です。Oidcプラグインはプロバイダーのディスカバリードキュメントを読み取るため、エンドポイントや署名キーの代わりに発行者(issuer)URLを設定します。API内のアクセストークンを検証でき、PKCE、セッション、ログアウトを含むブラウザサインインを実行できます。

このプラグインは実験的(experimental)であり、JVMでのみ利用可能です。

セッション ​

セッションは、異なるHTTPリクエスト間でデータを保持するメカニズムを提供します。一般的なユースケースとしては、ログインしたユーザーのIDの保存、ショッピングカートの内容、クライアント側のユーザー設定の保持などがあります。Ktorでは、関連付けられたセッションをすでに持っているユーザーをsessionプロバイダーを使用して認証できます。設定方法については、Ktor Serverにおけるセッション認証を参照してください。

カスタム ​

Ktorは、認証および認可の動作をカスタマイズする2つの方法を提供しています。

Experimental

型安全な認証スキームAPI

Ktorは、スキームをプリンシパル型にバインドする型安全な認証スキームAPIも提供しています。 保護されたルート内では、call.principalはそのプリンシパル型になり、nullではないことが保証されるため、キャストやnullチェックは不要です。 このAPIは、オプトインのロールチェック、匿名フォールバック、型付きセッション、およびOAuth 2.0フローもサポートしています。

このAPIは、本トピックで説明されている名前付きプロバイダーアプローチに代わるものです。 両方のAPIを同じアプリケーション内で使用できます。詳細については、型安全な認証を参照してください。

依存関係の追加 ​

Authenticationを使用するには、ビルドスクリプトに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>

なお、JWTやLDAPなど、一部の認証プロバイダーには追加のアーティファクトが必要です。

Authenticationのインストール ​

Authenticationプラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内のinstall関数に渡します。 以下の例は、Authenticationのインストール方法を示しています。

  • embeddedServer()関数呼び出し内。
  • Applicationクラスに明示的に定義されたmodule()拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.auth.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Authentication)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
fun Application.module() {
    install(Authentication)
    // ...
}

Authenticationの設定 ​

Authenticationのインストール後、以下のようにAuthenticationを設定して使用できます。

ステップ1: 認証プロバイダーの選択 ​

basic、digest、formなどの特定の認証プロバイダーを使用するには、installブロック内で対応する関数を呼び出す必要があります。例えば、Basic認証を使用するには、.basic()関数を呼び出します。

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    basic {
        // Basic認証の設定
    }
}

この関数内で、該当プロバイダー固有の設定を構成できます。

組み込みのプロバイダーが要件に合わない場合は、カスタム認証プロバイダーを実装できます。

ステップ2: プロバイダー名の指定 ​

特定のプロバイダーを使用するための関数では、オプションでプロバイダー名を指定できます。以下のコード例では、basicプロバイダーとformプロバイダーを、それぞれ"auth-basic"および"auth-form"という名前でインストールしています。

kotlin
install(Authentication) {
    basic("auth-basic") {
        // Basic認証の設定
    }
    form("auth-form") {
        // フォーム認証の設定
    }
    // ...
}

これらの名前は、後で異なるプロバイダーを使用して異なるルートを認証するために使用できます。

なお、プロバイダー名は一意である必要があり、名前のないプロバイダーは1つしか定義できません。

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

各プロバイダータイプには独自の設定があります。例えば、BasicAuthenticationProvider.Configクラスは.basic()関数のオプションを提供します。このクラスの主要な関数はvalidate()であり、ユーザー名とパスワードの検証を担当します。次のコード例はその使用法を示しています。

kotlin
install(Authentication) {
    basic("auth-basic") {
        realm = "Access to the '/' path"
        validate { credentials ->
            val isValid = credentials.name == "jetbrains" &&
                credentials.password == "foobar"
            if (isValid) {
                UserIdPrincipal(credentials.name)
            } else {
                null
            }
        }
    }
}

validate()関数の仕組みを理解するために、2つの用語を紹介します。

  • プリンシパル(principal)は、認証可能なエンティティ(ユーザー、コンピューター、サービスなど)です。Ktorでは、認証プロバイダーによって異なるプリンシパルを使用する場合があります。例えば、basic、digest、formプロバイダーはUserIdPrincipalを認証しますが、jwtプロバイダーはJWTPrincipalを検証します。

    カスタムプリンシパルを作成することもできます。これは以下の場合に役立ちます。

    • クレデンシャルをカスタムプリンシパルにマッピングすることで、ルートハンドラー内で認証されたプリンシパルに関する追加情報を保持できます。
    • セッション認証を使用する場合、プリンシパルはセッションデータを格納するデータクラスになります。
  • クレデンシャル(credential)は、サーバーがプリンシパルを認証するための一連のプロパティ(ユーザー名/パスワードのペア、APIキーなど)です。例えば、basicプロバイダーとformプロバイダーはユーザー名とパスワードを検証するためにUserPasswordCredentialを使用しますが、jwtはJWTCredentialを検証します。

つまり、validate()関数は指定されたクレデンシャルをチェックし、認証が成功した場合はプリンシパルAnyを返し、認証に失敗した場合はnullを返します。

特定の条件に基づいて認証をスキップするには、skipWhen()を使用します。 例えば、セッションが既に存在する場合にbasic認証をスキップできます。

kotlin
basic {
    skipWhen { call -> call.sessions.get<UserSession>() != null }
}

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

最後のステップは、アプリケーション内の特定のリソースを保護することです。これを行うには、authenticate()関数を使用します。この関数は2つのオプションパラメーターを受け取ります。

  • ネストされたルートを認証するために使用されるプロバイダー名。 以下のコードスニペットでは、/loginおよび/ordersルートを保護するために_auth-basic_という名前のプロバイダーを使用しています。

    kotlin
    routing {
        authenticate("auth-basic") {
            get("/login") {
                // ...
            }    
            get("/orders") {
                // ...
            }    
        }
        get("/") {
            // ...
        }
    }
  • ネストされた認証プロバイダーを解決するために使用される戦略(ストラテジー)。 この戦略は、AuthenticationStrategy列挙値で表されます。

    例えば、クライアントはAuthenticationStrategy.Required戦略で登録されたすべてのプロバイダーに対して認証データを提供する必要があります。 以下のコードスニペットでは、セッション認証を通過したユーザーのみが、Basic認証を使用して/adminルートへのアクセスを試行できます。

    kotlin
    routing {
        val required = AuthenticationStrategy.Required
        authenticate("auth-session", strategy = required) {
            get("/hello") {
                // ...
            }
            authenticate("auth-basic", strategy = required) {
                get("/admin") {
                    // ...
                }
            }
        }
    }

完全な例については、auth-form-session-nestedを参照してください。

ステップ5: ルートハンドラー内でプリンシパルを取得 ​

認証が成功すると、call.principal()関数を使用してルートハンドラー内で認証済みプリンシパルを取得できます。この関数は、設定された認証プロバイダーから返された特定のプリンシパル型を受け取ります。次の例では、call.principal()を使用してUserIdPrincipalを取得し、認証されたユーザーの名前を取得しています。

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

セッション認証を使用する場合、プリンシパルはセッションデータを格納するデータクラスになることがあります。 そのため、このデータクラスをcall.principal()に渡す必要があります。

kotlin
authenticate("auth-session") {
    get("/hello") {
        val userSession = call.principal<UserSession>()
    }
}

ネストされた認証プロバイダーの場合、call.principal()にプロバイダー名を渡して目的のプロバイダーのプリンシパルを取得できます。

以下の例では、最上位のセッションプロバイダーのプリンシパルを取得するために"auth-session"値を渡しています。

kotlin
val required = AuthenticationStrategy.Required
authenticate("auth-session", strategy = required) {
    authenticate("auth-basic", strategy = required) {
        get("/admin") {
            val userSession =
                call.principal<UserSession>(
                    "auth-session"
                )
        }
    }
}

カスタム認証プロバイダー ​

組み込みのプロバイダーが要件に合致しない場合にカスタム認証ロジックを実装するには、provider()関数を使用します。

kotlin
provider("custom") {
  authenticate { context ->
    val headers = context.call.request.headers
    val exampleHeader = headers["Example-Header"]
    if (exampleHeader == null) {
      val message = "No example header found"
      val cause = AuthenticationFailedCause.Error(message)
      context.challenge(key = this, cause) { challenge, call ->
        call.respondText("Challenge")
        challenge.complete()
      }
    }
  }
}

上記の例では、provider("custom")関数が名前付き認証プロバイダーを登録し、後でauthenticate("custom")を使用してルートに適用できるようにしています。

プロバイダー内では、受信したすべてのリクエストに対してauthenticate {}ブロックが実行され、コンテキストオブジェクトを介して認証プロセスの完全な制御が可能になります。これには、現在の呼び出し(context.call)へのアクセスや、ヘッダー、パラメーター、その他のリクエストデータを検査する機能が含まれます。

DynamicProviderConfigクラスが提供するオプションを使用して、追加のプロバイダー動作を設定できます。