Skip to content

Ktor ServerにおけるBasic認証 ​

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

コード例: auth-basic, auth-basic-hash-table

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

Basic認証スキームは、アクセス制御と認証に使用されるHTTPフレームワークの一部です。このスキームでは、ユーザーの認証情報(クレデンシャル)はBase64でエンコードされたユーザー名/パスワードのペアとして送信されます。

Ktorを使用すると、Basic認証を利用してユーザーのログインや特定のルートの保護を行うことができます。Ktorにおける認証全般に関する情報は、Ktor Serverにおける認証と認可セクションを参照してください。

Basic認証ではユーザー名とパスワードが平文で送信されるため、機密情報を保護するにはHTTPS/TLSを使用する必要があります。

依存関係の追加 ​

basic認証を有効にするには、ビルドスクリプトに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>

Basic認証のフロー ​

Basic認証のフローは以下のようになります。

  1. クライアントがサーバーアプリケーションの特定のルートに対して、Authorizationヘッダーなしでリクエストを送信します。

  2. サーバーはクライアントに対して401(Unauthorized)レスポンスステータスで応答し、WWW-Authenticateレスポンスヘッダーを使用してルートの保護にBasic認証スキームが使用されていることを伝えます。典型的なWWW-Authenticateヘッダーは次のようになります。

    WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"

    Ktorでは、basic認証プロバイダーの設定時に関連するプロパティを使用してレルム(realm)と文字セット(charset)を指定できます。

  3. 通常、クライアントはユーザーが認証情報を入力できるログインダイアログを表示します。その後、クライアントはBase64でエンコードされたユーザー名とパスワードのペアを含むAuthorizationヘッダーを付与してリクエストを送信します。例:

    Authorization: Basic amV0YnJhaW5zOmZvb2Jhcg
  4. サーバーはクライアントから送信された認証情報を検証し、リクエストされたコンテンツを応答します。

Basic認証のインストール ​

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

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

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

Basic認証の設定 ​

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

ステップ1: basicプロバイダーを設定する ​

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

  • realmプロパティは、WWW-Authenticateヘッダーで渡されるレルムを設定します。
  • 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関数はUserPasswordCredentialをチェックし、認証に成功した場合はUserIdPrincipalを返し、認証に失敗した場合はnullを返します。

また、ユーザー名とパスワードハッシュを保持するインメモリテーブルに格納されたユーザーを検証するために、UserHashedTableAuthを使用することもできます。

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

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

kotlin
data class User(val name: String)

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

validate関数はUserPasswordCredentialをチェックし、プリンシパル型を返します。認証に失敗した場合はnullを返します。完全なAPIについては、タイプセーフ認証を参照してください。

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

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

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

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

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

UserHashedTableAuthによる検証 ​

Ktorでは、UserHashedTableAuthを使用して、ユーザー名とパスワードハッシュを保持するインメモリテーブルに保存されたユーザーを検証できます。これにより、データソースが漏洩した場合でもユーザーのパスワードが漏洩するのを防ぐことができます。

UserHashedTableAuthを使用してユーザーを検証するには、以下の手順に従います。

  1. getDigestFunction関数を使用して、指定したアルゴリズムとソルトプロバイダーでダイジェスト関数を作成します。

    kotlin
    val digestFunction = getDigestFunction("SHA-256") {
        "ktor${it.length}"
    }
  2. UserHashedTableAuthの新しいインスタンスを初期化し、次のプロパティを指定します。

    • tableプロパティを使用して、ユーザー名とハッシュ化されたパスワードのテーブルを提供します。
    • digesterプロパティにダイジェスト関数を割り当てます。
    kotlin
    val hashedUserTable = UserHashedTableAuth(
        table = mapOf(
            "jetbrains" to digestFunction("foobar"),
            "admin" to digestFunction("password")
        ),
        digester = digestFunction
    )
  3. validate関数の内部でUserHashedTableAuth.authenticate関数を呼び出してユーザーを認証し、認証情報が有効な場合はUserIdPrincipalのインスタンスを返します。

    kotlin
    install(Authentication) {
        basic("auth-basic-hashed") {
            realm = "Access to the '/' path"
            validate { credentials ->
                hashedUserTable.authenticate(credentials)
            }
        }
    }