keycloakのWebAuthnサポート実現までのいきさつ

はじめに

日立製作所の乗松隆志と申します。keycloakのWebAuthnサポート実現までのいきさつについて記します。

Notes: 本文内の各リンク先について、今後変更される可能性がありますのでご承知おきください。

まえおき : keycloakへのcontribution

keycloakへのcontributionの方法ですが、keycloakのGOVERNANCE.mdに記載があります。

keycloakは、JIRAのチケットで作業管理をしています。

バグ修正や、ちょっとした機能拡張の場合は、JIRAのチケットを作成して、変更を実装し、Pull-Requestを出します。

大規模な機能拡張の場合は、keycloakのdevelopers mailing listに提案を投稿し、メンテナーと議論します。
必要に応じて、設計ドキュメントを作成して、keycloak-communityというgithubのプロジェクトの方に投稿し、メンテナーと議論します。作業を進めてよければ、JIRAのチケットを作成して、変更を実装し、Pull-Requestを出します。

Pull-Requestを出す際、第一行目のコメントは、

"JIRAのチケット番号" "JIRAのチケットのタイトル"

とするのがお作法のようです。JIRAのチケットとPull-Requestを対応させるためのようです。

WebAuthnとは

W3Cが策定している、Web AuthenticationというWebブラウザを利用した認証方式の標準仕様です。もともとは、FIDO Allianceで策定されていました。

サポートまでの過程

keycloak-communityの方にW3C Web Authentication - Two-Factorというドキュメントが作成され、keycloakでWebAuthnのRelying Partyとしての機能をサポートしようという方針になりました。そこで、実際にやってみようと思い立ち、2019/3末あたりから作業を始めました。

ライブラリの選定

keycloakのWebAuthnサポートについてのドキュメント
W3C Web Authentication - Two-Factorでは、いくつか課題が挙げられ、JIRAのチケットが作成されています。その中に、WebAuthnの処理を行うためのライブラリの選定があります。

ここでは、その候補が2つ挙げられていますが、ynojimaさんのwebauthn4jを使わせていただくことにしました。以後、ynojimaさんにはいろいろとお助けいただきました。

テスト方法の調査

keycloakのWebAuthnサポートについてのドキュメント
W3C Web Authentication - Two-Factorで挙げられている課題として、WebAuthnのテスト方法の調査
があります。ynojimaさんに助言いただいたとおり、ChromeのWeb Authentication Testing APIを利用することとしました。

ただ、これでできることは限定的であり、筆者が出したpull-requestのインテグレーションテスト用のコードでは基本的なテストしか行えませんでした。本原稿を執筆段階でも本作業は継続して行われております。

設計ドキュメントの作成

WebAuthnのサポートは大規模な機能拡張であるため、設計ドキュメントを作成し、keycloak-communityへW3C Web Authentication - Implementation stages - Authenticator onlyとして投稿しました。

作業のスコープを、以下の3つと定めています。

• 2FAとしてのWebAuthnのサポート
• WebAuthnの処理を行うためのライブラリの選定
• WebAuthnのテスト方法の調査

2FAとしてのWebAuthnのサポートですが、JIRAのチケットがあります。他2つは前述のとおりです。

設計ドキュメントには、本作業を行う上で他の作業の進捗に影響を受ける旨を記しています。

• Application Initiated Actions
• Managing multi-factor authentication and Step-up authentication in Keycloak

前者は、ユーザーが自身の登録したWebAuthn対応の認証器の情報を閲覧・変更・削除する機能に影響を与えます。設計ドキュメントでは、このApplication Initiated Actionsが実現していない前提で、既存のUser Account Serviceで行うとしました。

後者は、keycloakの認可認証フローの構造をリファクタリングするものです。スイスのCloud Trustというチームがこれを担当しました。これにより、ユーザーの登録したWebAuthn対応認証器の情報管理と、WebAuthnでのユーザー認証機能の使われ方に影響が出ます。設計ドキュメントでは、このManaging multi-factor authentication and Step-up authentication in Keycloakが実現していない前提で、一時的な方法で管理をするとしました。

ちなみに、WebAuthn対応認証器自体を登録するわけではなく、認証器内で生成された公開鍵とそれに関する情報を登録します。が、便宜上以下では「WebAuthn対応認証器を登録」という表現を使用します。

プロトタイプの作成

設計ドキュメントの作成と並行して、プロトタイプをkeycloakでいうところのプロバイダの形式で実装し、機能がどのように実現できるかどうか、実験用に作成しました。まず弊社のt-mogiが実装し、それを筆者が改造していきました。このプロトタイプですが、githubのwebauthn4jのプロジェクトに間借りさせていただき、Keycloak WebAuthn Authenticator
という名前で作成しました。

プロバイダの形式で実装したため、keycloak動作中に動的にデプロイしたりアンデプロイしたりできます。できれば本番のPull-Requestでもプロバイダの形式で実装できないかと考えておりましたが、WebAuthn対応の認証器の登録をするRegistrationという機能が、Required Actionという形式で実現することをW3C Web Authentication - Two-Factorに書かれており、かつRequired Actionの設定がプロバイダの形式では実現できなかったため、あきらめました。

このプロトタイプですが、ありがたいことにいろいろな方からご意見をIssueの形でいただいております。ですが、現在本番のPull-Requestがmergeされたことで本プロトタイプは本来の役割を終えたとし、実質活動をしておりません。

keycloak本体への実装

プロトタイプ作成で得られた知見をもとに、本番のPull-Requestを作成しました。

1st step

設計ドキュメントでは、WebAuthnサポートは段階を踏んで実現するとしました。まずは1段階目として、WebAuthnの仕様にあるWebAuthn対応の認証器の登録(Registration)とそれによるユーザーの認証(Authentication)の機能を実装しました。JIRAのチケットはKEYCLOAK-9360で、Pull-Requestは#6248となります。8/19に投稿し、いろいろやり取りがあり、10/2にmergeされました。

少々時間がかかりましたが、その要因の一つとして、新しく依存プロジェクトを追加したことが挙げられます。本WebAuthnサポートでは、WebAuthnのRegistrationおよびAuthentication時のRelying Partyにおける検証処理にwebauthn4jを使用させていただきました。これが新しくkeycloakの依存プロジェクトとして追加されるため、keycloakのメンテナー側でもチェックを実施したようで、その為に時間がかかったようです。

また、このWebAuthnサポートは新機能であるため、ドキュメントの記載が必要となります。keycloakにはドキュメント用のレポジトリであるkeycloak-documentationがあります。ここにドキュメントのPull-Requestを出しました。#737となります。ドキュメント担当(?)の方からレビューを受け、相当指摘を受けましたが、mergeされました。

2nd step

次いで、2段階目としてWebAuthn対応の認証器の登録時のAttestation Statementの検証機能を実装しました。

webauthn4jの機能を利用して検証するにあたり、keycloakとしてwebauthn4jにこんな機能があったらいいな、というものを実装してwebauthn4jにPull-Requestを出したところ、mergeしていただきました。そこで、まずはwebauthn4jを同機能が実装されたバージョンにバージョンアップするPull-Requestを出しmergeされたのち、mergeされた機能を利用して2段階目のPull-Requestをkeycloakに出しました。JIRAのチケットはKEYCLOAK-11372で、Pull-Request#6449はとなります。

1段階目と同じく、ドキュメントの記載が必要となるため、ドキュメントのPull-Requestを出しました。#779となります。

認証フローのリファクタリング

本WebAuthnサポートと並行して、前述のスイスのCloud Trustチームが認証フローのリファクタリングManaging multi-factor authentication and Step-up authentication in Keycloak対応のPull-Requestを実装していました。こちらの作業からみると、本WebAuthnサポートは2FAの認証処理用の機能ブロック(keycloakでいうところのAuthenticatorのプロバイダ)として見えます。本WebAuthnサポート用のPull-Requestがmergeされたのち、これを取り込んでPull-Requestを投稿し、mergeされました。JIRAのチケットはKEYCLOAK-11745で、Pull-Requestは#6459となります。なかなか大掛かりな作業であったようです。

ドキュメントの記載について、筆者が1段階目で追加したWebAuthnサポートの記述をCloud Trustチームが書き換えることになったため、筆者の方でもそれをレビューし、コメントして反映していただきました。

これにより、OTPに加えてWebAuthn対応の認証器での2FAが可能となりました。また、ユーザーが複数のOTPおよびWebAuthn対応の認証器を登録し、管理できるようになりました。

ひとまず完成

上記を含んだkeycloak-8.0.0が2019/11/15にリリースされました。

その後

keycloakのメンテナーの方で、Follow Upタスクとしてユーザービリティの向上を主としてさらに改造がなされるようです。これについて、keycloakのdevelopers mailing listのWebAuthn : Next Planというスレッドで議論がされています。

今回、弊社のチームメンバやwebauthn4jのynojimaさんなど様々な方からご助力いただき、基本的なWebAuthnサポート機能をkeycloakにcontributionできました。今後様々な方の手でより使い勝手のよいものに改造されていくことを期待しています。また、筆者自身もその一助を担えればと考えております。