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 アーティファクトを追加します。
implementation(ktorLibs.server.auth)implementation ktorLibs.server.auth<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Sessionsプラグインのインストール
クライアントが保護されたリソースにアクセスしようとするたびに認可を要求するのを避けるため、認可の成功時にアクセストークンをセッションに保存できます。 その後、保護されたルートのハンドラー内で現在のセッションからアクセストークンを取得し、リソースのリクエストに使用できます。
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認可フローは次のようになります。
ユーザーがKtorアプリケーションのログインページを開きます。
Ktorは特定のプロバイダーの認可ページへの自動リダイレクトを行い、必要なパラメーターを渡します。
- 選択したプロバイダーのAPIへのアクセスに使用されるクライアントID。
- 認可完了後に開かれるKtorアプリケーションのページを指定するコールバックまたはリダイレクトURL。
- Ktorアプリケーションに必要なサードパーティリソースのスコープ。
- アクセストークンを取得するために使用されるグラントタイプ(Authorization Code)。
- CSRF攻撃の緩和とユーザーのリダイレクトに使用される
stateパラメーター。 - 特定のプロバイダー固有のオプションパラメーター。
認可ページには、Ktorアプリケーションに必要な権限レベルを示す同意画面が表示されます。これらの権限は、ステップ2: OAuthプロバイダーの設定で設定された指定スコープによって決まります。
ユーザーが要求された権限を承認すると、認可サーバーは指定されたリダイレクトURLにリダイレクトし、認可コードを送信します。
Ktorは指定されたアクセストークンURLに対して、以下のパラメーターを含めてもう一度自動リクエストを行います。
- 認可コード
- クライアントIDとクライアントシークレット
認可サーバーはアクセストークンを返して応答します。
クライアントはこのトークンを使用して、選択したプロバイダーの必要なサービスにリクエストを行うことができます。ほとんどの場合、トークンは
AuthorizationヘッダーにBearerスキームを使用して送信されます。サービスはトークンを検証し、認可のためにそのスコープを使用して、要求されたデータを返します。
OAuthのインストール
oauth 認証プロバイダーをインストールするには、install ブロック内で oauth 関数を呼び出します。オプションで プロバイダー名を指定 することもできます。 例えば、"auth-oauth-google" という名前で oauth プロバイダーをインストールする場合は以下のようになります。
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で認可認証情報を作成する必要があります。
Google Cloud Consoleで 認証情報 ページを開きます。
認証情報を作成 をクリックし、
OAuth クライアント IDを選択します。ドロップダウンから
ウェブ アプリケーションを選択します。以下の設定を指定します。
- 承認済みの JavaScript 生成元:
http://localhost:8080 - 承認済みのリダイレクト URI:
http://localhost:8080/callbackKtorでは、認可完了時に開かれるリダイレクトルートを指定するために urlProvider プロパティが使用されます。
- 承認済みの JavaScript 生成元:
作成 をクリックします。
表示されたダイアログから、
oauthプロバイダーの設定に使用する作成されたクライアントIDとクライアントシークレットをコピーします。
ステップ1: HTTPクライアントの作成
oauth プロバイダーを設定する前に、サーバーがOAuthサーバーへのリクエストを行うために使用する HttpClient を作成する必要があります。APIへのリクエスト後に受信したJSONデータをデシリアライズするには、JSONシリアライザーを備えた ContentNegotiation クライアントプラグインが必要です。
val applicationHttpClient = HttpClient(CIO) {
install(ContentNegotiation) {
json(Json {
ignoreUnknownKeys = true
})
}
}サーバーのテストで別のクライアントインスタンスを作成できるように、クライアントインスタンスは main モジュール関数に渡されます。
fun Application.main(
httpClient: HttpClient = applicationHttpClient
) {
}ステップ2: OAuthプロバイダーの設定
以下のコードスニペットは、auth-oauth-google という名前の oauth プロバイダーを作成および設定する方法を示しています。 固定のOAuth設定を持つプロバイダーには、settings プロパティを使用します。
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 に自動的にリダイレクトされます。
routing {
authenticate("auth-oauth-google") {
get("/login") {
// 自動的に'authorizeUrl'にリダイレクト
}
}
}ユーザーには、Ktorアプリケーションに必要な権限レベルを示す認可ページが表示されます。これらの権限は、settings で指定された defaultScopes によって決まります。
ステップ4: リダイレクトルートの追加
ログインルートとは別に、ステップ2: OAuthプロバイダーの設定で指定した urlProvider 用のリダイレクトルートを作成する必要があります。
このルート内では、call.principal 関数を使用して OAuthAccessTokenResponse オブジェクトを取得できます。OAuthAccessTokenResponse を使用すると、トークンやOAuthサーバーから返されたその他のパラメーターにアクセスできます。
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 という新しい関数を作成します。
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 ルート内でこの関数を呼び出してユーザー情報を取得できます。
get("/{path}") {
val userSession: UserSession? = getSession(call)
if (userSession != null) {
val userInfo: UserInfo =
getPersonalGreeting(httpClient, userSession)
call.respondText("Hello, ${userInfo.name}!")
}
}実行可能な完全な例については、auth-oauth-google を参照してください。
