OAuth 2.0 フロー
必要な依存関係: io.ktor:ktor-server-auth, io.ktor:ktor-server-sessions
Ktor は、型安全な認証スキーム API の一部として、2 つの型付き OAuth 2.0 フローを提供しています。
oauth2Sessionはユーザーをサインインさせてセッションを保存し、アプリケーションのルートを保護するためのスキームを提供します。特別な理由がない限り、こちらを使用してください。oauth2はユーザーをサインインさせ、コールバック内でトークンを渡します。その後のルートは保護しません。
フローは authenticateWith() に渡すスキームではありません。ルーティングに install() する値であり、ログインルートとコールバックルートを自動的に作成します。
型安全な認証スキーム API は実験的(experimental)です。いつでも廃止または変更される可能性があります。 オプトインが必要です。詳細については、 型安全な認証のドキュメントを参照してください。
このトピックでは型付き API について説明します。従来の oauth プロバイダーについては、OAuth を参照してください。
フローの仕組み
- ユーザーがログインパスにアクセスします。Ktor はユーザーを OAuth プロバイダーにリダイレクトします。
- ユーザーがプロバイダー側で要求された権限を承認します。
- プロバイダーが認可コードとともにコールバックパスにリダイレクトして戻します。
- Ktor がそのコードをアクセストークンと交換します。
oauth2Sessionの場合、Ktor はセッションを保存してプリンシパルを解決し、コールバックハンドラーを実行します。
oauth2Session を使用してユーザーをサインインさせる
フローがプロバイダーのトークンエンドポイントを呼び出すには HttpClient が必要となるため、io.ktor:ktor-client-cio などのクライアントエンジンの依存関係も追加してください。
ルートで処理するプリンシパルと、Ktor が呼び出し元用に保存するセッションの 2 つの型を宣言します。
data class User(val id: String, val email: String)
data class UserSession(val accessToken: String)次にフローを作成します。型引数の順序に注意してください。第 1 引数がプリンシパル、第 2 引数がセッションです。
val googleAuthorizeUrl =
"https://accounts.google.com/o/oauth2/auth"
val googleTokenUrl = "https://oauth2.googleapis.com/token"
val profileScope =
"https://www.googleapis.com/auth/userinfo.profile"
val googleAuth = oauth2Session<User, UserSession>("google") {
client = HttpClient(CIO)
settings = OAuthServerSettings.OAuth2ServerSettings(
name = "google",
authorizeUrl = googleAuthorizeUrl,
accessTokenUrl = googleTokenUrl,
requestMethod = HttpMethod.Post,
clientId = System.getenv("GOOGLE_CLIENT_ID"),
clientSecret = System.getenv("GOOGLE_CLIENT_SECRET"),
defaultScopes = listOf(profileScope)
)
loginPath = "/login"
callback("/callback") {
call.respondRedirect("/profile")
}
sessions {
sessionCreator = { token ->
UserSession(token.accessToken)
}
validate { session ->
userService.loadUser(session.accessToken)
}
}
}sessions ブロックには 2 つの役割があります。
sessionCreatorは、トークンレスポンスを保存したいセッションに変換します。これはトークン交換の直後に 1 回だけ実行されます。validateは、保存されたセッションをプリンシパルに変換します。これは保護されたルートへのリクエストごとに実行されます。
どちらも必須です。
フローをインストールし、flow.session でルートを保護します。
routing {
install(googleAuth)
authenticateWith(googleAuth.session) {
get("/profile") {
val user = call.principal
val session = call.session
val token = session.accessToken
call.respondText("${user.email} ($token)")
}
}
}install() はログインルートを作成し、コールバックルートを作成し、セッションスキーム用の Sessions プラグインをインストールします。ご自身で Sessions をインストールする必要はありません。
保護されたルート内では、call.principal が User となり、call.session が UserSession となります。セッションでできることの詳細については、型安全なセッション認証 を参照してください。
保護されたルートはリダイレクトしない
フローによって自動作成されるルート(ログインパスおよびコールバックパス)は、未認証のアクセス者を OAuth プロバイダーにリダイレクトします。一方、authenticateWith(flow.session) で保護されたルートはリダイレクトしません。有効なセッションのないリクエストには 401 Unauthorized が返されます。
ユーザーをプロバイダーに送るには、次の 2 つの方法があります。
サインインページから
loginPathへのリンクを設ける。セッションが存在しない場合に、手動でそこへリダイレクトする:
kotlinval googleAuth = oauth2Session<User, UserSession>("google") { // ... sessions { sessionCreator = { token -> UserSession(token.accessToken) } validate { session -> userService.loadUser(session.accessToken) } onUnauthorized = { call.respondRedirect("/login") } } }
サインインの失敗を処理する
2 つのハンドラーが、サインインが失敗する 2 つのケースをカバーします。
フロー上の onUnauthorized は、ユーザーによる同意拒否、トークン交換の失敗、sessionCreator や validate が null を返した場合などの OAuth エラーを処理します。
val googleAuth = oauth2Session<User, UserSession>("google") {
// ...
onUnauthorized = { cause ->
call.respondRedirect("/login?error=${cause}")
}
}複数のプロバイダーを使用する
リクエストごとにプロバイダーを選択するには、settings の代わりに providerLookup を設定します。このブロックはルーティングコンテキストで実行されるため、パス、クエリパラメータ、ヘッダーを読み取ることができます。
val socialAuth = oauth2Session<User, UserSession>("social") {
client = HttpClient(CIO)
providerLookup = {
when (call.parameters["provider"]) {
"google" -> googleSettings
"github" -> githubSettings
else -> null
}
}
loginPath = "/login/{provider}"
callback("/callback/{provider}") {
call.respondRedirect("/profile")
}
sessions {
sessionCreator = { token ->
UserSession(token.accessToken)
}
validate { session ->
userService.loadUser(session.accessToken)
}
}
}settings または providerLookup のいずれか一方のみを設定してください。両方を同時に設定することはできません。
セッションなしでサインインする
サインイン後に独自の JWT を発行する場合など、Ktor が以降のルートを保護する必要がない場合は oauth2 を使用します。コールバックハンドラーはトークンレスポンスを受け取ります。
val githubAuthorizeUrl =
"https://github.com/login/oauth/authorize"
val githubTokenUrl =
"https://github.com/login/oauth/access_token"
val githubOAuth = oauth2("github") {
client = HttpClient(CIO)
settings = OAuthServerSettings.OAuth2ServerSettings(
name = "github",
authorizeUrl = githubAuthorizeUrl,
accessTokenUrl = githubTokenUrl,
requestMethod = HttpMethod.Post,
clientId = System.getenv("GITHUB_CLIENT_ID"),
clientSecret = System.getenv("GITHUB_CLIENT_SECRET")
)
loginPath = "/login"
callback("/callback") { token ->
val jwt = tokenService.issueToken(token.accessToken)
call.respondText(jwt)
}
}
routing {
install(githubOAuth)
}ここには flow.session がないため、authenticateWith() に渡すものはありません。jwt などの別のスキームでルートを保護してください。
セキュリティに関する注意事項
clientSecretはソース管理に含めないでください。環境変数または設定ファイルから読み取ります。- コールバックは、新しく生成されたセッション ID でセッションを保存し、コールバックリクエストとともに届いたセッション ID は破棄します。これにより、セッション固定化攻撃(Session Fixation)を防止します。
- デフォルトのセッショントランスポートはセッションデータをサーバー側に保持し、クライアントには ID のみを送信します。値によるトランスポート(by-value transport)に切り替える場合は、トランスフォーマーを追加してください。トランスポートの選択を参照してください。
次のステップ
- 型安全な認証 では、ロール、オプションの認証、および API のその他の機能について説明しています。
- 型安全なセッション認証 では、セッション、トランスポート、およびユーザーのサインアウトについて説明しています。
- OpenID Connect では、OpenID Connect 発行者(issuer)URL からこれらのフローを自動的に構成する方法について説明しています。
