オープンソース

  1. サーバ構築のデージーネットTOP
  2. OSS情報
  3. デージーネットのOSS
  4. KC-MailAuth
一覧へ

2. KC-MailAuthセットアップ

2.1. 前提・事前準備

KC-MailAuthは、Keycloak専用のため、基本的なKeycloakシステムが構築済みであることが前提です。
KC-MailAuthを使用するには、Keycloakの各レルム内でKC-MailAuthを組み込んだ認証フローを作成し、その認証フローを各クライアントのブラウザーフローに設定する必要があります。
また、使用にあたっては以下の条件を満たす必要があるため、設定が不足している場合は別途設定をしてください。
  • 認証を行うユーザが、Keycloakのレルム上に登録されていること
  • 認証を行うユーザに、メールアドレスが設定されていること
  • Keycloakのレルムにて、メール接続・認証設定がされており、Keycloakからのメール送信が問題なく行えること
  • KC-MailAuthの前段に、ユーザ認証用フォームを挟んで、ユーザ名またはメールアドレスを受け取れるようにすること

本マニュアルでは、Keycloakを「/opt/keycloak」にインストールして構築・稼働している前提でセットアップ手順を記載します。

2.2. KC-MailAuthをインストールする

2.2.1. 公式サイトからKC-MailAuthソフトウェアアーカイブをダウンロードする

下記のURLからソフトウェアアーカイブをダウンロードします。
アーカイブは、KC-MailAuth-バージョン.tar.gzです。

https://github.com/designet-inc-oss/KC-MailAuth

2.2.2. KC-MailAuthソフトウェアアーカイブを展開する

ダウンロードしたKC-MailAuth-バージョン.tar.gzを、任意のフォルダに展開します。

# tar -xvzf /path/to/KC-MailAuth-バージョン.tar.gz

2.2.3. プログラム本体を配置する

展開したKC-MailAuthソフトウェアアーカイブ内にある、「kc-mailauth.jar」というファイルを、Keycloakインストールディレクトリの「providers」ディレクトリ配下に配置します。
# cp KC-MailAuth-バージョン/kc-mailauth.jar /opt/keycloak/providers/

必要に応じて、「kc-mailauth.jar」ファイルの権限を、Keycloakサービスの実行ユーザに変更してください。

2.3. KC-MailAuthを設定する

2.3.1. 設定ファイルを配置・編集する

環境設定ファイルは、「config.properties」というファイル名で作成します。
デフォルトで「/opt/keycloak/kc-mailauth/config.properties」を読み込むようになっているため、以下のように作成します。
# mkdir /opt/keycloak/kc-mailauth
# touch /opt/keycloak/kc-mailauth/config.properties

必要に応じて、「kc-mailauth」ディレクトリと「config.properties」ファイルの権限を、Keycloakサービスの実行ユーザに変更してください。
なお、別パスに作成することも可能です。


未設定の項目については全てデフォルト値が使われるため、環境設定ファイルの中身が空の状態でも問題ありません。
デフォルト値から変更したい場合は、「項目名=設定値」の形式で1行に1項目ずつ記載します。
変更したい項目だけ記載し、その他の項目は未記載（デフォルト値を使う）といったことも可能です。
環境設定ファイルで設定可能な項目は次の通りです。

設定項目
項目名 説明 設定内容 デフォルト値
otp.length ワンタイムコードの長さ（文字数）を指定します。 1～32の数字 6
otp.charset ワンタイムコードの文字種パターンを指定します。
  • 0：数字のみ
  • 1：英小文字のみ
  • 2：英大文字のみ
  • 3：数字・英小文字
  • 4：数字・英大文字
  • 5：英小文字・英大文字
  • 6：数字・英小文字・英大文字
 0
otp.ttlSeconds ワンタイムコードの有効時間（秒）を指定します。ワンタイムコードが発行されてから指定した有効時間を過ぎると、該当のワンタイムコードは無効となります。 数字 180
otp.maxAttempts ワンタイムコードの入力試行回数上限（回）を指定します。指定した回数分ワンタイムコードの認証に失敗した場合、以降ワンタイムコードの入力を受け付けなくなります。 数字 5
otp.delaySecondsOnFail ワンタイムコードの入力失敗時の入力遅延時間（秒）を指定します。誤ったワンタイムコードを入力した場合、次回入力可能となるまで指定した時間分待たされるようになります。 数字 10
pepper ワンタイムコードのハッシュ化用文字列を指定します。 数字・英小文字・英大文字で1～32文字 特定の文字列
email.subject ワンタイムコード通知メールの件名を指定します。日本語を含める場合、文字コード「UTF-8」で記載する必要があります。 任意の文字列 Your one-time code
template.email.text ワンタイムコード通知メール（TEXT形式）用テンプレートのファイルパスを指定します。 実際にテンプレートファイルを配置したパス /opt/keycloak/kc-mailauth-templates/otp-email.txt
template.email.html ワンタイムコード通知メール（HTML形式）用テンプレートのファイルパスを指定します。 実際にテンプレートファイルを配置したパス /opt/keycloak/kc-mailauth-templates/otp-email.txt
template.page ワンタイムコード入力画面用テンプレートのファイルパスを指定します。 実際にテンプレートファイルを配置したパス /opt/keycloak/kc-mailauth-templates/otp-page.html
otp.skipClients KC-MailAuthによる認証をスキップするクライアントを指定します。ここで指定したクライアントへのアクセス時は、KC-MailAuthによるワンタイムコード認証を有効にしていた場合でも、ワンタイムコード認証を行いません。 クライアントID（Keycloak上の対象のクライアントIDをそのまま記載、複数ある場合はカンマ（,）で区切って記載） security-admin-console,admin-cli

設定例は次の通りです。
otp.length=10
otp.charset=6
otp.ttlSeconds=300
otp.maxAttempts=10
otp.delaySecondsOnFail=30
pepper=Abcd1234PepperKey
email.subject=One-time code
template.email.text=/opt/keycloak/kc-mailauth/otp-email.txt
template.email.html=/opt/keycloak/kc-mailauth/otp-email.html
template.page=/opt/keycloak/kc-mailauth/otp-page.html
otp.skipClients=security-admin-console,admin-cli,account-console

2.3.2. テンプレートを配置・編集する

テンプレートファイルは、ワンタイムコード通知メール用（TEXT形式とHTML形式）とワンタイムコード入力画面用の計3種類が必要です。
それぞれデフォルトで
  • ワンタイムコード通知メール用
    • TEXT形式: /opt/keycloak/kc-mailauth-templates/otp-email.txt
    • HTML形式: /opt/keycloak/kc-mailauth-templates/otp-email.html
  • ワンタイムコード入力画面用: /opt/keycloak/kc-mailauth-templates/otp-page.html
を読み込むようになっています。
展開したKC-MailAuthソフトウェアアーカイブ内の「templates-example」配下にサンプルのテンプレートがあるため、以下のように作成します。
# mkdir /opt/keycloak/kc-mailauth-templates
# cp KC-MailAuth-バージョン/templates-example/otp-email.txt /opt/keycloak/kc-mailauth-templates/otp-email.txt
# cp KC-MailAuth-バージョン/templates-example/otp-email.html /opt/keycloak/kc-mailauth-templates/otp-email.html
# cp KC-MailAuth-バージョン/templates-example/otp-page.html /opt/keycloak/kc-mailauth-templates/otp-page.html

必要に応じて、「kc-mailauth-templates」ディレクトリと各テンプレートファイルの権限を、Keycloakサービスの実行ユーザに変更してください。
なお、別パスに作成することも可能です。
別パスに作成した際は、設定ファイルを配置・編集する を参照して環境設定ファイルに明示的に指定してください。

テンプレートをサンプルの内容から変更する場合は、以下に従って変更してください。
  • ファイルサイズの上限は10MB
  • 日本語を含める場合、文字コード「UTF-8」で作成する
  • それぞれ以下のタグをテンプレート内に記載する
ワンタイムコード通知メール用テンプレートのタグ（共通）
タグ 説明
{{ttlSeconds}} ワンタイムコードの有効時間表示用
{{code}} ワンタイムコード表示用
{{sentAt}} ワンタイムコード通知メールの送信日時表示用
ワンタイムコード入力画面用テンプレートのタグ
タグ 説明
{{email}} ログインユーザのメールアドレス表示用（ワンタイムコード通知メールの送信先）
{{ttlSeconds}} ワンタイムコードの有効時間表示用
{{actionUrl}} 認証ステップのフォーム送信先URL埋め込み用（認証処理を行う上で必要）
  • {{#ifError}}
  • {{error}}
  • {{/ifError}}
 エラーメッセージ表示用（3つセットで必要）
{{sentAt}} ワンタイムコード通知メールの送信日時表示用

2.4. KC-MailAuthをKeycloakに組み込む

2.4.1. Keycloakをビルド・起動する

KC-MailAuthのインストールと設定が完了した後、Keycloakをビルド（再ビルド）します。
$ /opt/keycloak/bin/kc.sh build

ビルドに成功した後、Keycloakを起動します。
$ /opt/keycloak/bin/kc.sh start

設定ファイルを配置・編集する にて、環境設定ファイルをデフォルトとは異なるパスに作成した場合は、以下のように環境設定ファイルのパスを指定したうえでKeycloakを起動します。
$ JAVA_OPTS_APPEND="-Dkcmailauth.config=環境設定ファイルのパス"/opt/keycloak/bin/kc.sh start

2.4.2. Keycloakの認証フローを設定する

KC-MailAuthを使用するには、KC-MailAuthを組み込んだ認証フロー（どのような順番で、どのような認証を行っていくかを決めるルールのようなもの）を設定する必要があります。
本マニュアルでは、標準のユーザ/パスワード認証画面での認証後、KC-MailAuthによるワンタイムコード認証を行うフローを設定します。
デフォルトの認証フローをコピーして設定を行うため、認証フローを一から作成する際の手順は省略しています。

Keycloakの起動後、管理者ユーザでKeycloakの管理者Webインターフェースにアクセスします。
対象のレルムの管理画面にて、右メニューの「Authentication」をクリックし、認証フロー管理画面を表示します。
_images/menu_authentication.png

表示されている認証フローの中から「browser」をクリックします。
_images/click_browser.png

右上の「Action」をクリックし、「Duplicate」をクリックします。
_images/select_duplicate.png

任意の名前を入力し、「Duplicate」をクリックします。
_images/do_duplicate.png

コピーした認証フローの設定画面にて、「Add execution」をクリックします。
_images/click_addexecution.png

「KC-MailAuth」を選択し、「Add」をクリックします。
_images/select_execution.png

作成した「KC-MailAuth」executionを、「認証フロー名 forms」flow内の「Username Password Form」stepの下にドラッグアンドドロップします。
_images/drag_execution.png

上記を行うことで「KC-MailAuth」stepに変わるので、再度「認証フロー名 forms」flow内の「Username Password Form」stepの下にドラッグアンドドロップします。
_images/drag_step.png

Requirementを「Required」にし、標準のユーザ/パスワード認証画面での認証後に必ずワンタイムコード認証を行うように設定します。
_images/select_requirement.png

以上で認証フローの作成は完了です。

2.4.3. 対象のクライアントのブラウザーフローを設定する

認証フローを作成した後は、実際にKC-MailAuthによるワンタイムコード認証を実装するクライアント（接続先のサービス）に、その認証フローを使うよう設定する必要があります。

対象のレルムの管理画面にて、右メニューの「Clients」をクリックし、クライアント管理画面を表示します。
_images/menu_clients.png

表示されているクライアントの中から、KC-MailAuthによるワンタイムコード認証を設定したいクライアントをクリックします。
_images/click_clients.png

タブメニューから、「Advanced」をクリックします。
_images/click_advanced.png

「Authentication flow overrides」の「Browser Flow」にて、Keycloakの認証フローを設定する にて作成した認証フローを選択し、「Save」をクリックします。
_images/select_browserflow.png

以上でクライアントのブラウザーフローの設定は完了です。

一覧へ