Skip to content

Ktor ServerにおけるDigest認証 ​

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

コード例: auth-digest

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

Digest認証スキームは、アクセス制御と認証に使用されるHTTPフレームワークの一部です。このスキームでは、ユーザー名とパスワードをネットワーク経由で送信する前にハッシュ関数が適用されます。

KtorはRFC 7616(HTTP Digest Access Authentication)をサポートしており、より強力なハッシュアルゴリズム、QoP(Quality of Protection)オプション、プライバシー保護のためのユーザー名ハッシュ化などの最新のセキュリティ機能によって従来のRFC 2617を強化しています。

Ktorでは、Digest認証を使用してユーザーをログインさせ、特定のルートを保護できます。Ktorにおける認証に関する一般的な情報は、Ktor Serverにおける認証と認可セクションを参照してください。

Digest認証は、パスワードが平文で送信されることがないため、Basic認証よりも強力なセキュリティを提供します。ただし、トランスポートレベルのセキュリティを強化するため、本番環境ではHTTPS/TLSを使用することをお勧めします。

依存関係の追加 ​

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

Digest認証のフロー ​

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

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

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

    WWW-Authenticate: Digest
            realm="Access to the '/' path",
            nonce="e4549c0548886bc2",
            algorithm=SHA-512-256,
            qop="auth"

    Ktorでは、digest認証プロバイダーを設定する際に、レルム(realm)、サポートするアルゴリズム、QoP(Quality of Protection)、およびnonce値の生成方法を指定できます。

  3. 通常、クライアントはユーザーが認証情報を入力できるログインダイアログを表示します。その後、クライアントは次のAuthorizationヘッダーを付与してリクエストを送信します。

    Authorization: Digest username="jetbrains",
            realm="Access to the '/' path",
            nonce="e4549c0548886bc2",
            uri="/",
            algorithm=SHA-512-256,
            qop=auth,
            nc=00000001,
            cnonce="0a4f113b",
            response="6629fae49393a05397450978507c4ef1"

    responseの値は次のように生成されます。

    • HA1 = H(username:realm:password)。ここでHは設定されたハッシュアルゴリズム(例: SHA-512-256)です。

    この部分はサーバー上に保存され、Ktorがユーザーの認証情報を検証するために使用できます。

    • HA2 = H(method:digestURI)(qop=authの場合)、またはHA2 = H(method:digestURI:H(entityBody))(qop=auth-intの場合)

    • response = H(HA1:nonce:nc:cnonce:qop:HA2)

  4. サーバーはクライアントから送信された認証情報を検証し、要求されたコンテンツで応答します。QoPを使用した認証に成功すると、サーバーは相互認証のためにAuthentication-Infoヘッダーも返します。

Digest認証のインストール ​

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

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

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

Digest認証の設定 ​

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

ステップ1: ハッシュアルゴリズムの選択 ​

KtorはDigest認証向けに複数のハッシュアルゴリズムをサポートしています。サーバーが受け入れるアルゴリズムは、algorithmsプロパティを使用して設定できます。

アルゴリズム定数セキュリティレベル備考
SHA-512-256DigestAlgorithm.SHA_512_256推奨最も強力なセキュリティ、新規実装で使用
SHA-512-256-sessDigestAlgorithm.SHA_512_256_SESS推奨セッションバリアント - HA1にクライアントnonceを含む
SHA-256DigestAlgorithm.SHA_256良好本番環境における最低推奨
SHA-256-sessDigestAlgorithm.SHA_256_SESS良好セッションバリアント - HA1にクライアントnonceを含む
MD5DigestAlgorithm.MD5非推奨下位互換性のためのみ
MD5-sessDigestAlgorithm.MD5_SESS非推奨セッションバリアント - レガシーな互換性のためのみ
kotlin
install(Authentication) {
    digest("auth-digest") {
        realm = "Access to the '/' path"
        algorithms = listOf(
            DigestAlgorithm.SHA_512_256,
            DigestAlgorithm.MD5
        )
        // ...
    }
}

複数のアルゴリズムが設定されている場合、サーバーは複数のWWW-Authenticateヘッダーを送信し、クライアントがサポートする最も強力なアルゴリズムを選択できるようにします。

デフォルトのアルゴリズムはSHA-512-256およびMD5(古いクライアントとの下位互換性のため)です。

セッションアルゴリズム(-sessバリアント) ​

-sessアルゴリズムのバリアント(例: SHA-512-256-sess、SHA-256-sess、MD5-sess)は、HA1ハッシュの計算方法を変更します。H(username:realm:password)を保存する代わりに、セッションアルゴリズムはH(H(username:realm:password):nonce:cnonce)を計算します(cnonceはクライアントが提供するnonce)。

メリット:

  • セッション固有のハッシュにより、事前計算された辞書攻撃を防ぎます
  • 1つのセッションのハッシュが侵害されても、パスワードが漏洩したり他のセッションが悪用されたりすることはありません

デメリット:

  • サーバーは認証リクエストごとにハッシュを計算する必要があります(事前計算された値を使用できません)

ほとんどのアプリケーションでは、特にSHA-512-256のような強力なハッシュ関数と組み合わせて使用する場合、標準の(非セッション)アルゴリズムで十分です。

ステップ2: ダイジェストを含むユーザーテーブルの提供 ​

digest認証プロバイダーは、ダイジェストメッセージのHA1部分を使用してユーザーの認証情報を検証するため、ユーザー名とそれに対応するHA1ハッシュを含むユーザーテーブルを提供できます。

アルゴリズムが異なれば生成されるハッシュ値も異なるため、サポートする各アルゴリズムに応じた適切なハッシュを保存するか、クライアントから要求されたアルゴリズムに基づいて動的にハッシュを計算する必要があります。

kotlin
val userPasswords: Map<String, String> = mapOf(
    "jetbrains" to "foobar",
    "admin" to "password"
)

fun computeHash(
    userName: String,
    realm: String,
    password: String,
    algorithm: DigestAlgorithm
): ByteArray =
    algorithm.toDigester()
        .digest("$userName:$realm:$password".toByteArray(UTF_8))

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

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

  • realmプロパティは、WWW-Authenticateヘッダーで渡されるレルムを設定します。
  • algorithmsプロパティは、受け入れるハッシュアルゴリズムを指定します。
  • digestProvider関数は、指定されたユーザー名とアルゴリズムに対応するダイジェストのHA1部分を取得します。
  • (オプション)validate関数を使用すると、認証情報をカスタムプリンシパルにマッピングできます。
kotlin
install(Authentication) {
    digest("auth-digest") {
        realm = myRealm
        // 最新のSHA-512-256と
        // レガシーなMD5クライアントの両方をサポート
        algorithms = listOf(
            DigestAlgorithm.SHA_512_256,
            DigestAlgorithm.MD5
        )
        digestProvider { userName, realm, algorithm ->
            // 要求されたアルゴリズムを使用して
            // H(username:realm:password)を計算
            userPasswords[userName]?.let { password ->
                computeHash(
                    userName, realm, password, algorithm
                )
            }
        }
        validate { credentials ->
            if (credentials.userName.isNotEmpty()) {
                CustomPrincipal(
                    credentials.userName,
                    credentials.realm
                )
            } else {
                null
            }
        }
    }
}

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

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

kotlin
data class CustomPrincipal(
    val userName: String,
    val realm: String
)

val digestAuth = digest<CustomPrincipal>("auth-digest") {
    realm = myRealm
    // 最新のSHA-512-256と
    // レガシーなMD5クライアントの両方をサポート
    algorithms = listOf(
        DigestAlgorithm.SHA_512_256,
        DigestAlgorithm.MD5
    )
    digestProvider { userName, realm, algorithm ->
        // 要求されたアルゴリズムを使用して
        // H(username:realm:password)を計算
        userPasswords[userName]?.let { password ->
            computeHash(userName, realm, password, algorithm)
        }
    }
    validate { credentials ->
        if (credentials.userName.isNotEmpty()) {
            CustomPrincipal(
                credentials.userName,
                credentials.realm
            )
        } else {
            null
        }
    }
}

型安全なdigest()関数はJVMでのみ利用可能です。完全なAPIについては、型安全な認証を参照してください。

digestProvider関数は3つのパラメータを受け取ります。

  • userName – クライアントのリクエストからのユーザー名
  • realm - 設定されたレルム
  • algorithm – クライアントが使用しているハッシュアルゴリズム

指定されたアルゴリズムで計算されたHA1ハッシュを返す必要があります。ユーザーが見つからない場合はnullを返します。

また、nonceManagerプロパティを使用して、nonce値の生成方法を指定することもできます。

ステップ4: Quality of Protection(QoP)の設定 ​

Quality of Protection(QoP)は、ダイジェスト計算に何を含めるかを決定します。

  • DigestQop.AUTH – 認証のみ(デフォルト)。ダイジェストにはリクエストメソッドとURIが含まれます。
  • DigestQop.AUTH_INT – 改ざん防止保護付きの認証。ダイジェストにはリクエストボディも含まれ、改ざんに対する保護を提供します。
kotlin
install(Authentication) {
    digest("auth-digest") {
        realm = "Secure API"
        supportedQop = listOf(
            DigestQop.AUTH,
            DigestQop.AUTH_INT
        )
        // ...
    }
}

auth-intを使用する場合、認証中にリクエストボディが消費されます。ルートハンドラー内でボディにアクセスする必要がある場合は、DoubleReceiveプラグインをインストールしてください。

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

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

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

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

kotlin
routing {
    authenticateWith(digestAuth) {
        get("/") {
            val user = call.principal
            call.respondText("Hello, ${user.userName}!")
        }
    }
}

高度な設定 ​

ユーザーハッシュのサポート ​

RFC 7616では、プライバシー保護のためにユーザー名のハッシュ化(userhash)が導入されました。これを有効にすると、クライアントは平文のユーザー名の代わりにハッシュ化されたユーザー名を送信できます。

ユーザー名ハッシュをサポートするには、userHashResolverを設定します。

kotlin
val users = listOf("alice", "bob", "charlie")

install(Authentication) {
    digest("auth-digest") {
        realm = "Private API"
        userHashResolver { userhash, realm, algorithm ->
            // ハッシュから実際のユーザー名を検索
            users.find { username ->
                val digester = algorithm.toDigester()
                val bytes = "$username:$realm".toByteArray()
                hex(digester.digest(bytes)) == userhash
            }
        }
        digestProvider { userName, realm, algorithm ->
            // ...
        }
    }
}

userHashResolverが設定されている場合、サーバーはWWW-Authenticateチャレンジヘッダーでuserhash=trueを通知します。

厳格なRFC 7616モード ​

レガシーなクライアント要件のない新規アプリケーションで最大限のセキュリティを確保するには、strictRfc7616Mode()を使用します。

kotlin
install(Authentication) {
    digest("auth-digest") {
        realm = "Secure Zone"
        strictRfc7616Mode()
        digestProvider { userName, realm, algorithm ->
            // 厳格モードではアルゴリズムがMD5になることはありません
        }
    }
}

厳格モードの動作:

  • MD5アルゴリズムを削除(SHA-256、SHA-512-256、およびそれらのセッションバリアントのみを許可)
  • UTF-8文字セットを強制

UTF-8文字セットのサポート ​

digest認証プロバイダーは、非ASCII文字を含むユーザー名とパスワードに対してUTF-8文字セットをサポートしています。

kotlin
install(Authentication) {
    digest("auth-digest") {
        realm = "My App"
        charset = Charsets.UTF_8  // これがデフォルトです
        // ...
    }
}

Authentication-Infoヘッダー ​

QoPを使用した認証に成功すると、サーバーは自動的に以下を含むAuthentication-Infoヘッダーを返します。

  • rspauth - 相互認証のためのレスポンス認証値
  • nextnonce - クライアントが次に使用するnonce
  • qop、nc、cnonce - 認証パラメータのエコー

これにより、クライアントはサーバーの身元を検証できます(相互認証)。

セキュリティに関する推奨事項 ​

  1. SHA-512-256またはSHA-256を使用する - 本番環境ではMD5を避けてください。これはレガシーな互換性のためだけに含まれています。

  2. strictRfc7616Mode()を使用する - レガシーなクライアント要件のない新規アプリケーション向け。

  3. 適切なnonce管理を実装する – 分散環境でのリプレイ攻撃を防ぐために、カスタムのNonceManagerを使用してください。

  4. auth-intを検討する - アプリケーションにとってリクエストボディの整合性が重要な場合。

  5. userhashを有効にする - ユーザー名のプライバシーを保護するため。

  6. 常にHTTPSを使用する – Digest認証単体ではトラフィックは暗号化されません。本番環境では常にTLSを使用してください。