型安全な認証
必要な依存関係: io.ktor:ktor-server-auth
Ktorは、認証スキームをプリンシパル型にバインドする型安全な認証スキームAPIを提供します。スキームを一度作成してルートに渡せば、キャストやnullチェックなしでプリンシパルを読み取ることができます。
このAPIは、install(Authentication) アプローチの代替となるものです。両方のAPIを同じアプリケーション内で使用でき、一方のAPIを使用するルートをもう一方のAPIを使用するルートの内側にネストすることも可能です。
依存関係の追加
型付き認証を使用するには、ビルドスクリプトに ktor-server-auth アーティファクトを追加します。
implementation(ktorLibs.server.auth)implementation ktorLibs.server.auth<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>jwt スキームを使用する場合は、ktor-server-auth-jwt アーティファクトを追加します。
implementation(ktorLibs.server.auth.jwt)implementation ktorLibs.server.auth.jwt<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jwt-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>apiKey スキームを使用する場合は、ktor-server-auth-api-key アーティファクトを追加します。
implementation(ktorLibs.server.auth.apiKey)implementation ktorLibs.server.auth.apiKey<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-api-key-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>APIの有効化
このAPIには @ExperimentalKtorApi がマークされているため、オプトインする必要があります。
@OptIn(ExperimentalKtorApi::class)
fun Application.module() {
// ...
}ルートビルダーはKotlinのコンテキストパラメータ(context parameters)を使用します。Kotlin 2.4.0ではコンテキストパラメータがデフォルトで有効になっています。Kotlin 2.2.xまたは2.3.xを使用している場合は、ビルドスクリプトでこれらを有効にしてください。
kotlin {
compilerOptions {
freeCompilerArgs.add("-Xcontext-parameters")
}
}プリンシパルの定義
プリンシパルは、認証された呼び出し元に関連付ける識別情報やその他の情報を表します。プリンシパル型は非nullでなければなりません。
data class User(
val id: String,
val email: String
)スキームの作成
各認証方式は、プリンシパル型、名前、および設定ブロックを受け取るファクトリ関数を提供します。validate {} ブロックはプリンシパル型を返すか、クレデンシャルが拒否された場合は null を返します。
val jwtAuth = jwt<User>("my-jwt") {
realm = "my-app"
verifier(jwkProvider, issuer)
validate { credential ->
val payload = credential.payload
User(
id = payload.subject,
email = payload.getClaim("email").asString()
)
}
}ファクトリは値を返します。それを保持し、それを必要とするルートに渡します。
| ファクトリ | アーティファクト | 備考 |
|---|---|---|
basic<P>() | ktor-server-auth | Ktor ServerでのBasic認証を参照 |
digest<P>() | ktor-server-auth | JVMのみ。Ktor ServerでのDigest認証を参照 |
bearer<P>() | ktor-server-auth | Ktor ServerでのBearer認証を参照 |
form<P>() | ktor-server-auth | Ktor Serverでのフォームベース認証を参照 |
session<S, P>() | ktor-server-auth | 型安全なセッション認証を参照 |
apiKey<P>() | ktor-server-auth-api-key | APIキー認証を参照 |
jwt<P>() | ktor-server-auth-jwt | JVMのみ。JSON Web Tokensを参照 |
oauth2(), oauth2Session<P, S>() | ktor-server-auth | OAuth 2.0フローを参照 |
スキーム名は一意である必要があります。同じ名前で2つの異なるスキームを作成すると、ルートがそれを使用しようとした際に2つ目のスキームが失敗します。
ルートの保護
ルートを保護するには、authenticateWith() 関数にスキームを渡します。ブロック内では、call.principal はスキームによって定義されたプリンシパル型を持ち、非nullであることが保証されます。
routing {
authenticateWith(jwtAuth) {
get("/profile") {
val user: User = call.principal
call.respondText(user.email)
}
}
}認証をオプションにする
ルートでサインイン済みの呼び出し元と匿名の呼び出し元の両方を処理する場合は、authenticateWithOptional() 関数を使用します。ブロック内では、call.principalOrNull を使用してプリンシパルにアクセスします。
routing {
authenticateWithOptional(jwtAuth) {
get("/me") {
val user = call.principalOrNull
call.respondText(user?.email ?: "anonymous")
}
}
}クレデンシャルを持たないリクエストは成功し、call.principalOrNull は null になります。無効なクレデンシャルを持つリクエストは引き続き失敗します。
複数のスキームを受け入れる
同じルートで複数のスキームを受け入れるには、authenticateWithAnyOf() 関数を使用します。Ktorはリストされた順序でスキームを試行し、最初に成功したスキームがプリンシパルを提供します。
すべてのスキームは、共通の型に適合するプリンシパルを生成する必要があり、その型を呼び出し時に宣言します。
interface AppUser {
val email: String
}
data class JwtUser(
override val email: String,
val id: String
) : AppUser
data class ApiUser(override val email: String) : AppUser
val jwtScheme = jwt<JwtUser>("my-jwt") { /* ... */ }
val apiKeyScheme = apiKey<ApiUser>("my-api-key") { /* ... */ }
routing {
// AppUser is
authenticateWithAnyOf<AppUser>(jwtScheme, apiKeyScheme) {
get("/profile") {
call.respondText(call.principal.email)
}
}
}authenticateWithAnyOf() の内部では、call.principal のみが利用可能です。セッションスキームの call.session のように、単一のスキームに属する追加機能は利用できません。
匿名の呼び出し元を許可する
クレデンシャルを持たない呼び出し元を処理するスキームを構築するには、orAnonymous() 関数を使用します。クレデンシャルのないリクエストは、ブロックが返したプリンシパルを取得します。無効なクレデンシャルを持つリクエストは引き続き失敗します。
結果として、2つの共通のスーパータイプをプリンシパル型とするスキームが得られます。
interface Identity
data class AuthenticatedUser(val id: String) : Identity
data class GuestUser(val label: String = "guest") : Identity
val feedAuth = jwt<AuthenticatedUser>("my-jwt") {
verifier(jwkProvider, issuer)
validate { credential ->
AuthenticatedUser(credential.payload.subject)
}
}.orAnonymous { GuestUser() }
routing {
authenticateWith(feedAuth) {
get("/feed") {
when (val user = call.principal) {
is AuthenticatedUser ->
call.respondText(user.id)
is GuestUser ->
call.respondText(user.label)
}
}
}
}プリンシパルの変換
データベースからユーザーレコードを読み込むなどしてプリンシパルを別の型に変換するには、mapPrincipal() 関数を使用します。
data class AppUser(val id: String, val email: String)
val appAuth = jwtAuth.mapPrincipal { jwtUser ->
userDirectory.find(jwtUser.id)?.let { row ->
AppUser(id = row.id, email = row.email)
}
}変換は、スキームがプリンシパルを生成した後にのみ実行されます。変換が null を返した場合、リクエストは 401 Unauthorized で拒否されます。
ロールの確認
ロールチェックはオプトインです。AuthenticationRole を実装するロール型を定義し、withRoles() を使用してロール対応スキームを構築します。
enum class Role : AuthenticationRole {
User, Admin, Moderator
}
val roleAuth = jwtAuth.withRoles { user ->
roleService.resolveRoles(user.id)
}withRoles {} ブロックは、認証が成功した後に各リクエストで実行されます。データベース、キャッシュ、またはプリンシパル自体からロールをロードするために使用します。
ルートが必要とするロールを roles パラメータで宣言します。
routing {
authenticateWith(roleAuth, roles = setOf(Role.Admin)) {
get("/admin") {
val userRoles: Set<Role> = call.principal.roles
call.respondText(userRoles.joinToString { it.name })
}
}
}認証されたものの必要なロールを持たない呼び出し元は、403 Forbidden を受け取ります。呼び出し元は、いずれか1つだけでなく、セットに含まれるすべてのロールを持っている必要があります。
ロールを要求せずに解決したい場合は、roles = null を渡します。これはハンドラ自体で判断を行いたい場合に役立ちます。
authenticateWith(roleAuth, roles = null) {
get("/dashboard") {
if (Role.Admin in call.principal.roles) {
call.respondText("admin view")
} else {
call.respondText("user view")
}
}
}roles プロパティは、ロール対応ルートの内部にのみ存在します。通常のスキームで保護されたルート上ではコンパイルされません。
失敗の処理
エラーが発生するケースは2つあり、それぞれ個別に処理されます。
onUnauthorizedは認証が失敗したときに実行されます。デフォルトのレスポンスは401 Unauthorizedです。onForbiddenは認証には成功したものの、呼び出し元に必要なロールがない場合に実行されます。デフォルトのレスポンスは403 Forbiddenです。
そのスキームを使用するすべてのルートに適用するには、スキーム側でハンドラを設定します。
val jwtAuth = jwt<User>("my-jwt") {
verifier(jwkProvider, issuer)
validate { credential -> /* ... */ }
onUnauthorized = { cause ->
val message = cause.toString()
call.respond(HttpStatusCode.Unauthorized, message)
}
}
val roleAuth = jwtAuth.withRoles(
onForbidden = {
val forbidden = HttpStatusCode.Forbidden
call.respondText("Not allowed", status = forbidden)
}
) { user ->
roleService.resolveRoles(user.id)
}あるいは、個別のルートにハンドラを設定して、スキームレベルのハンドラを上書きすることもできます。
authenticateWith(
roleAuth,
roles = setOf(Role.Admin),
onUnauthorized = { call.respondRedirect("/login") },
onForbidden = {
val forbidden = HttpStatusCode.Forbidden
call.respondText("Admins only", status = forbidden)
},
) {
get("/admin") {
call.respondText(call.principal.email)
}
}Ktorは次の順序で未認証ハンドラを検索します。
authenticateWith()に渡されたハンドラ。- スキームに設定された
onUnauthorizedハンドラ。 - プロバイダーのデフォルトのチャレンジ。
いずれも応答しない場合、リクエストは 401 Unauthorized で失敗します。
authenticateWithAnyOf() の場合、ハンドラはスキーム名と失敗原因のマッピングを受け取るため、それぞれが失敗した理由を報告できます。
authenticateWithAnyOf<AppUser>(
jwtScheme,
apiKeyScheme,
onUnauthorized = { failures ->
val schemes = failures.keys.joinToString()
call.respond(HttpStatusCode.Unauthorized, schemes)
}
) {
get("/profile") { /* ... */ }
}従来のAPIとの組み合わせ
両方の認証APIを同じアプリケーション内で使用できます。名前付きプロバイダーAPIによって保護されたルートの内側に型安全なルートをネストしたり、型安全なルートの内側にプロバイダーベースのルートをネストしたりできます。
routing {
authenticate("auth-session") {
authenticateWith(basicAuth) {
get("/admin") {
val basicUser = call.principal
val sessionUser =
checkNotNull(call.principal<SessionUser>())
if (basicUser.name == sessionUser.name) {
call.respondText("You are ${basicUser.name}!")
} else {
call.respondText("Who are you?")
}
}
}
}
authenticate(basicAuth.name) {
get("/hello") {
val user = checkNotNull(call.principal<BasicUser>())
call.respondText("Hello ${user.name}!")
}
}
}ネストされた認証レイヤーは順番に適用されます。
制限事項
- このAPIは実験的(experimental)です。マイナーリリースで変更される可能性があります。
- このAPIはKotlinのコンテキストパラメータを使用しており、Kotlin 2.4.0または
-Xcontext-parametersコンパイラオプションが必要です。 authenticateWithAnyOf()関数はcall.principalのみを提供します。その内部ではcall.sessionなどのスキーム固有のプロパティは利用できません。- LDAPプロバイダーに相当する型安全な実装はありません。代わりに、型付きの
validate {}ブロック内でldapAuthenticate()を呼び出してください。
