Keycloakのパスキー実現方法

第1回では、パスキーの仕組み、パスキー対応デバイスやパスキー導入サービスの状況、事例、メリット、Keycloakのパスキー対応状況を紹介しました。今後、安全性と利便性が高いことから、パスキーがさらに広まっていくことが考えられます。そこで第2回では、実際にKeycloakを利用してパスキーの登録と認証を行う手順を紹介します。

本記事で実施する認証パターン

はじめに本記事でKeycloakを使って実現するパスキーによる認証のパターンを説明します。まず、パスキーによる認証には、クライアントのデバイスと認証器のデバイスが同じである同一デバイス認証（図1の左）とクライアントのデバイスと認証器のデバイスが異なるクロスデバイス認証（図1の右）があります。

図1：同一デバイス認証とクロスデバイス認証

また、同一デバイス認証とクロスデバイス認証は、パスキーにデバイスバウンドパスキー（図2の左）を使用するか同期パスキー（図2の右）を使用するかで2通りのパターンに分けられます。デバイスバウンドパスキーと同期パスキーの詳細については、第1回を参照ください。

図2：デバイスバウンドパスキーと同期パスキー

つまり、パスキーによる認証には同一デバイス認証またはクロスデバイス認証と、デバイスバウンドパスキーまたは同期パスキーの計2×2の4通り存在します。本記事では、表1にある通り、3通りの認証を紹介します。デバイスバウンドパスキーを使用したクロスデバイス認証の挙動は、同期パスキーを使用したクロスデバイス認証と大きく変わりがないため、本記事では省略します。

本記事で使用するデバイス一覧

本記事で使用するデバイス、OSの情報、デバイスの使用用途、ブラウザーの情報を表2にまとめます。

Keycloakの構築

パスキーによる認証を実現するためのシステム構成を図3に示します。

図3：本記事のシステム構成

図3を構成するために、KeycloakをWindows PCに構築します。

Keycloakのインストール

まずは、2024年4月5日時点の最新バージョンであるKeycloak 24.0.2をインストールします。Keycloakのインストール方法には、Dockerイメージ、QuickStartsリポジトリやOperatorを使用する方法など多くの方法がありますが、今回はKeycloakのzipファイルをダウンロードしてインストールします。手順は以下の通りです。

• 0. 事前準備
• 1. Keycloak 24.0.2のzipファイルをダウンロード
• 2. KeycloakのAdminユーザーの設定
• 3. TLSの設定
• 4. Keycloakの起動

0. 事前準備

事前準備として、以下の2つが必要になります。

• Java 17のインストール
  Keycloak 24.0.2を動作させるためにJava 17が必要になりますの で、Java 17をインストールしておいてください。
• サーバー証明書と秘密鍵の作成
  パスキーによる認証にはHTTPS通信が必要になります（こちらを 参照）。そのため、サーバー証明書と秘密鍵を作成しておいてください。今回は動作確認のため、自 己署名証明書を使用しますが、本番用途で使用する場合は認証局から取得した証明書を使用すること を推奨します。今回作成した自己署名証明書には、CNとSANにexample.comを設定し、basicConstrain tsにCA:trueを設定します。また、動作確認で使用するデバイスに作成した自己署名証明書をインポ ートしておきます。

1. Keycloak 24.0.2のzipファイルのダウンロード

Keycloak 24.0.2のzipファイルは、こちらからダウンロードできます。ダウンロードしたzipファイルを解凍してください。

2. KeycloakのAdminユーザーの設定

次にKeycloakの管理コンソールにサインインするためのAdminユーザーのユーザー名とパスワードを設定します。Adminユーザーのユーザー名はKEYCLOAK_ADMINという環境変数から設定でき、パスワードはKEYCLOAK_ADMIN_PASSWORDという環境変数から設定できます。以下のコマンドより設定します。

set KEYCLOAK_ADMIN=admin
set KEYCLOAK_ADMIN_PASSWORD=***

3. TLSの設定

次にTLSの設定として、手順0「事前準備」で作成した自己署名証明書と秘密鍵を設定します。[Keycloakのインストールディレクトリ]\conf\keycloak.confに以下を追記します。

https-certificate-file=<手順0「事前準備」で作成した自己署名証明書>
https-certificate-key-file=<手順0「事前準備」で作成した秘密鍵>

4. Keycloakの起動

最後にKeycloakを起動します。Keycloakのインストールディレクトリに移動し、以下のコマンドを実行します。今回は動作確認のため、開発モードで起動させていますが、本番用途で使用する場合は本番モードで起動させることを推奨します。

> .\bin\kc.bat start-dev

以上で、Keycloakの管理コンソール（https://example.com:8443/admin）にアクセスできるようになりました。ブラウザーを使ってアクセスすると、Keycloakのサインイン画面が表示されます。手順2「KeycloakのAdminユーザーの設定」で設定したadminユーザーのユーザー名adminと手順2「KeycloakのAdminユーザーの設定」で設定したパスワードを入力すると、管理コンソールにサインインできます。

Keycloakの設定

続いて、Keycloakでパスキーによる認証ができるように、Keycloakの管理コンソールから設定します。必要な設定は以下の5つになります。

1. レルムの作成
2. クライアントの作成
3. ユーザーの作成
4. 認証フローの作成
5. Webauthn Passwordless Policyの設定

1. レルムの作成

まずはレルムを作成します。レルムとは、ユーザーやアプリケーションなどを管理するKeycloakにおける名前空間のことを指します。今回は「myrealm」という名前のレルムを作成します。具体的なレルムの作成方法はKeycloakのドキュメントや「CNCF IncubatingプロジェクトになったKeycloak入門」の連載を参照ください。

2. クライアントの作成

先ほど作成したmyrealmレルムにクライアントを作成します。今回はこちらで公開されているサンプルアプリケーションをクライアントに使用します。今回作成するクライアント情報は表 3の通りです。具体的なクライアントの作成方法はKeycloakのドキュメントや「CNCF IncubatingプロジェクトになったKeycloak入門」の連載を参照ください。

3. ユーザーの作成

先ほど作成したmyrealmレルムにユーザーを作成します。今回作成するユーザー情報は表4の通りです。具体的なユーザーの作成方法はKeycloakのドキュメントや「CNCF IncubatingプロジェクトになったKeycloak入門」の連載を参照ください。

また、作成したユーザーのパスワード情報を設定します。今回設定するユーザーのパスワード情報は表5の通りです。具体的なパスワード情報の設定方法はKeycloakのドキュメントや「CNCF IncubatingプロジェクトになったKeycloak入門」の連載を参照ください。

4. 認証フローの作成

次に、パスキーの認証を有効にするため、認証フローを作成します。今回はパスワード認証またはパスキーによる認証でサインインできるpasskeysという認証フローを作成します。Keycloakには「WebAuthn」が含まれるAuthenticatorが2つあります。1つ目は「WebAuthn Authenticator」です。こちらは、多要素認証で2要素目以降の認証にパスキーを使用する場合に、使用されます。2つ目は「Webauthn Passwordless Authenticator」です。こちらは、1要素目の認証にパスキーを使用する場合に、使用されます。今回は「Webauthn Passwordless Authenticator」を使用します。作成する認証フローは図4の通りです。

図4：作成した認証フロー

また、作成した認証フローをBrowser flowにバインドする必要がありますので、図4の右上の「Action」、「Bind flow」の順に押下し、Browser flowを選択し、「Save」を押下します。これにより、ユーザーはパスキーによる認証を選択できるようになりました。

5. Webauthn Passwordless Policyの設定

最後に、Webauthn Passwordless Policyの設定をします。Webauthn Passwordless Policyは管理コンソールのAuthentication>Policies> Webauthn Passwordless Policyから設定できます。今回、設定した項目を表6にまとめます。