APIキー認証
必須の依存関係: io.ktor:ktor-server-auth, io.ktor:ktor-server-auth-api-key
ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
APIキー認証は、クライアントがリクエストの一部(通常はヘッダー内)として秘密キーを送信するシンプルな認証方式です。このキーは、識別子と認証メカニズムの両方として機能します。
Ktorでは、ルートを保護しクライアントリクエストを検証するためにAPIキー認証を使用できます。
Ktorにおける認証に関する一般的な情報は、Ktor Serverでの認証と認可セクションを参照してください。
APIキーは秘密として保持し、安全に送信する必要があります。転送中のAPIキーを保護するためにHTTPS/TLSを使用することをお勧めします。
依存関係の追加
APIキー認証を有効にするには、ビルドスクリプトに ktor-server-auth と ktor-server-auth-api-key アーティファクトを追加します。
implementation("io.ktor:ktor-server-auth-api-key:$ktor_version")
implementation("io.ktor:ktor-server-auth:$ktor_version")implementation "io.ktor:ktor-server-auth-api-key:$ktor_version"
implementation "io.ktor:ktor-server-auth:$ktor_version"<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-api-key-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>
<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth</artifactId>
<version>${ktor_version}</version>
</dependency>APIキー認証フロー
APIキー認証のフローは以下のようになります。
- クライアントがサーバーアプリケーションの特定のルートに対して、ヘッダー(通常は
X-API-Key)にAPIキーを含めてリクエストを送信します。 - サーバーはカスタム検証ロジックを使用してAPIキーを検証します。
- キーが有効な場合、サーバーは要求されたコンテンツを返します。キーが無効または不足している場合、サーバーは
401 Unauthorizedステータスを返します。
APIキー認証のインストール
apiKey 認証プロバイダーをインストールするには、install(Authentication) ブロック内で apiKey 関数を呼び出します。
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
apiKey {
// APIキー認証の設定
}
}オプションで、特定のルートを認証するために使用できるプロバイダー名を指定することもできます。
APIキー認証の設定
このセクションでは、apiKey 認証プロバイダーの具体的な設定について説明します。
Ktorでさまざまな認証プロバイダーを設定する方法については、認証の設定を参照してください。
ステップ 1: APIキープロバイダーを設定する
apiKey 認証プロバイダーは、ApiKeyAuthenticationProvider.Config クラスを介して設定を公開します。以下の例では、次の設定が指定されています。
validate関数はリクエストから抽出されたAPIキーを受け取り、認証に成功した場合はPrincipalを返し、失敗した場合はnullを返します。
最小限の例を以下に示します。
data class AppPrincipal(val key: String) : Principal
install(Authentication) {
apiKey {
validate { keyFromHeader ->
val expectedApiKey = "this-is-expected-key"
keyFromHeader
.takeIf { it == expectedApiKey }
?.let { AppPrincipal(it) }
}
}
}タイプセーフ認証スキームAPIは実験的(experimental)です。いつでも削除または変更される可能性があります。オプトインが必要です。詳細については、タイプセーフ認証のドキュメントを参照してください。
apiKey() 関数は、選択したプリンシパルタイプのスキームを作成します。install(Authentication) ステップはありません。スキームは、それを必要とするルートに渡す値となります。
data class AppPrincipal(val key: String)
val apiKeyAuth = apiKey<AppPrincipal>("api-key") {
validate { keyFromHeader ->
val expectedApiKey = "this-is-expected-key"
keyFromHeader
.takeIf { it == expectedApiKey }
?.let { AppPrincipal(it) }
}
}クラシックプロバイダーとは異なり、名前が必須です。完全なAPIについては、タイプセーフ認証を参照してください。
キーの場所のカスタマイズ
デフォルトでは、apiKey プロバイダーは X-API-Key ヘッダーからAPIキーを探します。
headerName を使用してカスタムヘッダーを指定できます。
apiKey("api-key-header") {
headerName = "X-Secret-Key"
validate { key ->
// ...
}
}val apiKeyAuth = apiKey<AppPrincipal>("api-key-header") {
headerName = "X-Secret-Key"
validate { key ->
// ...
}
}ステップ 2: APIキーを検証する
検証ロジックはアプリケーションの要件によって異なります。一般的なアプローチを以下に示します。
静的キーの比較
単純なケースでは、事前定義されたキーと比較できます。
apiKey {
validate { keyFromHeader ->
val expectedApiKey =
environment.config.property("api.key").getString()
keyFromHeader
.takeIf { it == expectedApiKey }
?.let { AppPrincipal(it) }
}
}機密性の高いAPIキーは、ソースコード内ではなく、設定ファイルや環境変数に保存してください。
データベース検索
複数のAPIキーを扱う場合は、データベースと照合して検証します。
apiKey {
validate { keyFromHeader ->
// データベースでキーを検索
val user = database.findUserByApiKey(keyFromHeader)
user?.let { UserIdPrincipal(it.username) }
}
}複数の検証基準
複雑な検証ロジックを実装することもできます。
apiKey {
validate { keyFromHeader ->
val apiKey = database.findApiKey(keyFromHeader)
// キーが存在し、アクティブで、有効期限が切れていないか確認
if (apiKey != null &&
apiKey.isActive &&
apiKey.expiresAt > Clock.System.now()
) {
UserIdPrincipal(apiKey.userId)
} else {
null
}
}
}ステップ 3: チャレンジの設定
challenge 関数を使用すると、認証に失敗したときに送信されるレスポンスをカスタマイズできます。
apiKey {
validate { key ->
// 検証ロジック
}
challenge { defaultScheme, realm ->
call.respond(
HttpStatusCode.Unauthorized,
"Invalid or missing API key"
)
}
}ステップ 4: 特定のリソースを保護する
apiKey プロバイダーを設定した後、authenticate 関数を使用してアプリケーション内の特定のリソースを保護できます。認証に成功した場合、ルートハンドラー内で call.principal 関数を使用して認証されたプリンシパルを取得できます。
routing {
authenticate {
get("/") {
val principal = call.principal<AppPrincipal>()!!
val key = principal.key
call.respondText("Hello! Your key: $key")
}
}
}スキームを authenticateWith() に渡します。ブロック内では、call.principal は指定したプリンシパルタイプになり、決して null にはならないため、!! は不要です。
routing {
authenticateWith(apiKeyAuth) {
get("/") {
val key = call.principal.key
call.respondText("Hello! Your key: $key")
}
}
}APIキー認証の例
以下は、APIキー認証の完全な最小限の例です。
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
data class AppPrincipal(val key: String) : Principal
fun Application.module() {
val expectedApiKey = "this-is-expected-key"
install(Authentication) {
apiKey {
validate { keyFromHeader ->
keyFromHeader
.takeIf { it == expectedApiKey }
?.let { AppPrincipal(it) }
}
}
}
routing {
authenticate {
get("/") {
val principal = call.principal<AppPrincipal>()!!
call.respondText("Key: ${principal.key}")
}
}
}
}ベストプラクティス
APIキー認証を実装する際は、以下のベストプラクティスを考慮してください。
- HTTPSを使用する: 傍受を防ぐため、常にHTTPS経由でAPIキーを送信してください。
- 安全に保存する: APIキーをソースコード内に直接ハードコードしないでください。環境変数や安全な設定管理機能を使用してください。
- キーのローテーション: APIキーを定期的にローテーションするメカニズムを実装してください。
- レート制限: 悪用を防ぐために、APIキー認証とレート制限(Rate limiting)を組み合わせてください。
- ロギング: セキュリティ監視のために認証失敗をログに記録しますが、実際のAPIキー自体は決してログ出力しないでください。
- キーの形式: APIキーには暗号学的に安全なランダム文字列を使用してください(例: UUIDやBase64エンコードされたランダムバイト列)。
- 複数のキー: 用途やアプリケーションごとに、ユーザー1人あたり複数のAPIキーをサポートすることを検討してください。
- 有効期限: セキュリティを強化するために、キーの有効期限を実装してください。
