Skip to content
Server Plugin

OAuth

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

コード例: auth-oauth-google

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

OAuth はアクセス委譲(access delegation)のためのオープンスタンダードです。OAuthを使用すると、Google、Facebook、Twitterなどの外部プロバイダーを利用してアプリケーションのユーザーを認可(authorize)できます。

oauth プロバイダーは認可コードフロー(authorization code flow)をサポートしています。OAuthパラメーターを1か所で設定でき、Ktorは必要なパラメーターを指定された認可サーバーへ自動的にリクエストします。

Ktorにおける認証と認可に関する一般的な情報については、Ktor Serverにおける認証と認可セクションを参照してください。

Ktorは型安全なOAuth 2.0フローも提供しています。名前付きプロバイダーを設定する代わりに、フロー値を作成してインストールすると、Ktorがログインおよびコールバックルートを自動生成します。oauth2Session フローでは、サインイン後にアプリケーションルートを保護するためのスキームも提供されます。詳細は OAuth 2.0フロー を参照してください。

プロバイダーがOpenID Connectをサポートしている場合、Oidc プラグインを使用するとさらに便利です。プロバイダーのディスカバリードキュメントを読み込むため、認可エンドポイント、トークンエンドポイント、JWKSエンドポイントの代わりにissuer URLを設定するだけで済み、PKCE、IDトークンの検証、セッション、ログアウトが自動的に処理されます。詳細は OpenID Connect を参照してください。

依存関係の追加 ​

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

Sessionsプラグインのインストール ​

クライアントが保護されたリソースにアクセスしようとするたびに認可を要求するのを避けるため、認可の成功時にアクセストークンをセッションに保存できます。 その後、保護されたルートのハンドラー内で現在のセッションからアクセストークンを取得し、リソースのリクエストに使用できます。

kotlin
import io.ktor.server.sessions.*

fun Application.main(
    httpClient: HttpClient = applicationHttpClient
) {
    install(Sessions) {
        cookie<UserSession>("user_session")
    }
}

@Serializable
data class UserSession(val state: String, val token: String)

OAuth認可フロー ​

KtorアプリケーションにおけるOAuth認可フローは次のようになります。

  1. ユーザーがKtorアプリケーションのログインページを開きます。

  2. Ktorは特定のプロバイダーの認可ページへの自動リダイレクトを行い、必要なパラメーターを渡します。

    • 選択したプロバイダーのAPIへのアクセスに使用されるクライアントID。
    • 認可完了後に開かれるKtorアプリケーションのページを指定するコールバックまたはリダイレクトURL。
    • Ktorアプリケーションに必要なサードパーティリソースのスコープ。
    • アクセストークンを取得するために使用されるグラントタイプ(Authorization Code)。
    • CSRF攻撃の緩和とユーザーのリダイレクトに使用される state パラメーター。
    • 特定のプロバイダー固有のオプションパラメーター。
  3. 認可ページには、Ktorアプリケーションに必要な権限レベルを示す同意画面が表示されます。これらの権限は、ステップ2: OAuthプロバイダーの設定で設定された指定スコープによって決まります。

  4. ユーザーが要求された権限を承認すると、認可サーバーは指定されたリダイレクトURLにリダイレクトし、認可コードを送信します。

  5. Ktorは指定されたアクセストークンURLに対して、以下のパラメーターを含めてもう一度自動リクエストを行います。

    • 認可コード
    • クライアントIDとクライアントシークレット

    認可サーバーはアクセストークンを返して応答します。

  6. クライアントはこのトークンを使用して、選択したプロバイダーの必要なサービスにリクエストを行うことができます。ほとんどの場合、トークンは Authorization ヘッダーに Bearer スキームを使用して送信されます。

  7. サービスはトークンを検証し、認可のためにそのスコープを使用して、要求されたデータを返します。

OAuthのインストール ​

oauth 認証プロバイダーをインストールするには、install ブロック内で oauth 関数を呼び出します。オプションで プロバイダー名を指定 することもできます。 例えば、"auth-oauth-google" という名前で oauth プロバイダーをインストールする場合は以下のようになります。

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*

fun Application.main(
    httpClient: HttpClient = applicationHttpClient
) {
    install(Authentication) {
        oauth("auth-oauth-google") {
            // OAuth認証の設定
            urlProvider = { "http://localhost:8080/callback" }
            client = httpClient
        }
    }
}

OAuthの設定 ​

このセクションでは、Googleを使用してアプリケーションのユーザーを認可するための oauth プロバイダーの設定方法を説明します。 実行可能な完全な例については、auth-oauth-google を参照してください。

前提条件: 認可認証情報の作成 ​

Google APIにアクセスするには、Google Cloud Consoleで認可認証情報を作成する必要があります。

  1. Google Cloud Consoleで 認証情報 ページを開きます。

  2. 認証情報を作成 をクリックし、OAuth クライアント ID を選択します。

  3. ドロップダウンから ウェブ アプリケーション を選択します。

  4. 以下の設定を指定します。

    • 承認済みの JavaScript 生成元: http://localhost:8080
    • 承認済みのリダイレクト URI: http://localhost:8080/callback Ktorでは、認可完了時に開かれるリダイレクトルートを指定するために urlProvider プロパティが使用されます。
  5. 作成 をクリックします。

  6. 表示されたダイアログから、oauth プロバイダーの設定に使用する作成されたクライアントIDとクライアントシークレットをコピーします。

ステップ1: HTTPクライアントの作成 ​

oauth プロバイダーを設定する前に、サーバーがOAuthサーバーへのリクエストを行うために使用する HttpClient を作成する必要があります。APIへのリクエスト後に受信したJSONデータをデシリアライズするには、JSONシリアライザーを備えた ContentNegotiation クライアントプラグインが必要です。

kotlin
val applicationHttpClient = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

サーバーのテストで別のクライアントインスタンスを作成できるように、クライアントインスタンスは main モジュール関数に渡されます。

kotlin
fun Application.main(
    httpClient: HttpClient = applicationHttpClient
) {
}

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

以下のコードスニペットは、auth-oauth-google という名前の oauth プロバイダーを作成および設定する方法を示しています。 固定のOAuth設定を持つプロバイダーには、settings プロパティを使用します。

kotlin
val googleAuthorizeUrl =
    "https://accounts.google.com/o/oauth2/auth"
val googleTokenUrl =
    "https://accounts.google.com/o/oauth2/token"
val profileScope =
    "https://www.googleapis.com/auth/userinfo.profile"
val googleClientId =
    System.getenv("GOOGLE_CLIENT_ID").orEmpty()
val googleClientSecret =
    System.getenv("GOOGLE_CLIENT_SECRET").orEmpty()
val redirects = ConcurrentMap<String, String>()
install(Authentication) {
    oauth("auth-oauth-google") {
        // OAuth認証の設定
        urlProvider = { "http://localhost:8080/callback" }
        settings = OAuthServerSettings.OAuth2ServerSettings(
                name = "google",
                authorizeUrl = googleAuthorizeUrl,
                accessTokenUrl = googleTokenUrl,
                requestMethod = HttpMethod.Post,
                clientId = googleClientId,
                clientSecret = googleClientSecret,
                defaultScopes = listOf(profileScope),
                extraAuthParameters =
                    listOf("access_type" to "offline"),
                onStateCreated = { call, state ->
                    // 新しいstateをリダイレクトURLとともに保存
                    val query = call.request.queryParameters
                    query["redirectUrl"]?.let {
                        redirects[state] = it
                    }
                }
            )
        fallback = { cause ->
            if (cause is OAuth2RedirectError) {
                respondRedirect("/login-after-fallback")
            } else {
                respond(
                    HttpStatusCode.Forbidden,
                    cause.message
                )
            }
        }
        client = httpClient
    }
}
  • urlProvider は、認可が完了したときに呼び出されるリダイレクトルートを指定します。

    このルートが承認済みのリダイレクト URIのリストに追加されていることを確認してください。

  • settings プロパティは、プロバイダーの静的なOAuth設定を指定します。これらの設定は OAuthServerSettings クラスで表され、KtorがOAuthサーバーへ自動的にリクエストを行えるようにします。静的なプロバイダー設定では、providerLookup よりも settings を優先してください。これにより、生成される OpenAPI仕様 のメタデータをKtorが推論できるようにもなります。
  • fallback プロパティは、リダイレクトまたはカスタムレスポンスで応答することにより、OAuthフローのエラーを処理します。
  • client プロパティは、KtorがOAuthサーバーへのリクエストを行うために使用する HttpClient を指定します。

特定の呼び出しに対してOAuth設定を動的に解決するために、providerLookup プロパティも引き続きサポートされています。テナント固有の認証情報やエンドポイントなど、プロバイダーの設定がリクエストデータに依存する場合に使用してください。

ステップ3: ログインルートの追加 ​

oauth プロバイダーを設定したら、oauth プロバイダーの名前を受け取る authenticate 関数内で保護されたログインルートを作成する必要があります。Ktorがこのルートへのリクエストを受信すると、settings で定義された authorizeUrl に自動的にリダイレクトされます。

kotlin
routing {
    authenticate("auth-oauth-google") {
        get("/login") {
            // 自動的に'authorizeUrl'にリダイレクト
        }
    }
}

ユーザーには、Ktorアプリケーションに必要な権限レベルを示す認可ページが表示されます。これらの権限は、settings で指定された defaultScopes によって決まります。

ステップ4: リダイレクトルートの追加 ​

ログインルートとは別に、ステップ2: OAuthプロバイダーの設定で指定した urlProvider 用のリダイレクトルートを作成する必要があります。

このルート内では、call.principal 関数を使用して OAuthAccessTokenResponse オブジェクトを取得できます。OAuthAccessTokenResponse を使用すると、トークンやOAuthサーバーから返されたその他のパラメーターにアクセスできます。

kotlin
    routing {
        authenticate("auth-oauth-google") {
            get("/login") {
                // 自動的に'authorizeUrl'にリダイレクト
            }

            get("/callback") {
                val currentPrincipal:
                    OAuthAccessTokenResponse.OAuth2? =
                        call.principal()
                // 認可前にURLが見つからない場合はホームにリダイレクト
                currentPrincipal?.let { principal ->
                    principal.state?.let { state ->
                        val session = UserSession(
                            state,
                            principal.accessToken
                        )
                        call.sessions.set(session)
                        redirects.remove(state)?.let { url ->
                            call.respondRedirect(url)
                            return@get
                        }
                    }
                }
                call.respondRedirect("/home")
            }
        }
    }

この例では、トークンを受信した後に次のアクションが実行されます。

  • トークンは Session に保存され、その内容は他のルート内からアクセスできます。
  • ユーザーは、Google APIへのリクエストが行われる次のルートにリダイレクトされます。
  • 要求されたルートが見つからない場合、ユーザーは /home ルートにリダイレクトされます。

ステップ5: APIへのリクエスト ​

リダイレクトルート内でトークンを受け取り、セッションに保存した後は、このトークンを使用して外部APIへのリクエストを行うことができます。以下のコードスニペットは、HttpClient を使用してそのようなリクエストを行い、Authorization ヘッダーにこのトークンを送信してユーザー情報を取得する方法を示しています。

リクエストを実行してレスポンスボディを返す getPersonalGreeting という新しい関数を作成します。

kotlin
private suspend fun getPersonalGreeting(
    httpClient: HttpClient,
    userSession: UserSession
): UserInfo = httpClient.get(
    "https://www.googleapis.com/oauth2/v2/userinfo"
) {
    headers {
        val bearer = "Bearer ${userSession.token}"
        append(HttpHeaders.Authorization, bearer)
    }
}.body()

その後、get ルート内でこの関数を呼び出してユーザー情報を取得できます。

kotlin
get("/{path}") {
    val userSession: UserSession? = getSession(call)
    if (userSession != null) {
        val userInfo: UserInfo =
            getPersonalGreeting(httpClient, userSession)
        call.respondText("Hello, ${userInfo.name}!")
    }
}

実行可能な完全な例については、auth-oauth-google を参照してください。