Edited at

Keycloakの認証処理にSMS認証(Twilio利用)を追加してみる


はじめに

5日目の今日はKeycloakのカスタマイズです。Keycloakについての説明は 「Keycloakとは」を参照してください。去年の Keycloak by OpenStandia Advent Calendar 2017 でKeycloakを紹介する記事です。去年のKeycloak Advent Calendarには私も参加しまして、Keycloakのカスタマイズポイントについて記事を書きました。今回は、このカスタマイズポイントの中で認証機能(認証SPI)をピックアップして認証処理にSMS認証(本人確認)機能を追加するカスタマイズをやってみます。


SMS?SMS認証?

SMS(ショートメッセージサービス)とは電話番号でショートメッセージを送受信できるサービスです。SMS認証とはSMSを利用して認証(本人確認)を行うことです。絵で表現すると以下のイメージです。

SMS認証イメージ.png

ID/PWDのログインとは別にAさんの登録済み電話番号に認証コードを送信&確認することで、より確実な本人確認が出来るため、第三者からの不正ログインを防ぐ確率を上げることが出来ます。

SMS送受信サービスを提供しているのは Twilio, nexmo, Amazon SNS などいくつか存在しますが、今回のSMS送受信サービスには Twilio を利用します。


Twilioとは?

20171206203748.png

Twilioとはサンフランシスコにあるクラウド通信企業で、WEBサービスAPIを使って電話やテキストメッセージを送受信するサービスを提供しています。日本ではKDDIがその代理店となっていて日本語ドキュメントも公開していますので、始めて使う時も入りやすいのではないかと思います。

余談ですが、Twilioのアドベントカレンダー も今年登録されていました。(2015年から毎年登録されています)TwilioはSMS送受信以外にも色々なコミュニケーションAPIを提供していますので、興味がある方は参照してください。


事前準備


Twilioのアカウント作成

TwilioのSMS認証を使うにはTwilioのアカウントが必要です(正確にはSMS送受信用のAPI-KEYが必要です)

無料トライアルのアカウントが登録できてTwilio内の一定の金額までは無料で使うことが可能です。一定の金額に達するとアカウントは自動で停止状態になり、有料アカウントへアップグレード案内通知が来ます。

(2018年12月時点では)有料アカウントへアップグレードしない限り料金が発生することはないですが、今後変わる可能性もありますので登録時には利用規約を確認するようにしてください。登録自体は簡単ですので、普通に進められると思います。登録途中に電話番号検証(SMS)が発生しますのでSMS受信可能な電話を用意しましょう。(SMS通信料は受信者負担です。。)


TwilioのAPI-KEY取得

アカウント作成終了後、TOP画面が表示されたら「トップ画面」 ⇒「電話番号認証」⇒「電話番号認証 Project ダッシュボード」⇒「Verify」まで進むと以下の画面が表示されます。番号の順番通りに進めましょう。

verify.png



  • 「1. Let’s verify a phone number on your Twilio account」


    • ここでもう一回、電話番号検証します。




  • 「2. Create an application and get your API credentials」


    • applicationとAPIを作成。applicationを作成すると、SMS送受信履歴やAPI-KEY確認・更新などが出来るようになります。




  • 「3. Send your first Verify code」


    • 上記で作成したapplicationのAPI-KEYを利用してSMS認証コードをcURLで送信します。下記のようにリクエストの中身が表示されますのでAPI-KEYもここで確認できます。(設定画面からも確認できます)



verify2.png


  • 「4. Get verified」


    • 受信した認証コードが正しいかcURLで確認します。



以上、Twilio側の事前準備は完了です。


カスタマイズ前のログイン確認

カスタマイズする前のログイン処理を確認しておきます。ログイン確認はアカウント管理画面にアクセスすることで確認できます。

Login.png


  • アカウント管理画面にログイン成功

Login_OK.png

Username / Password の入力のみでログインできることを確認しました。


認証機能のカスタマイズ

認証機能をカスタマイズします。作業順番は以下の通りです。


  1. 画面(Themes)作成

  2. SMS認証モジュール作成

  3. カスタマイズモジュールをKeycloakに反映

  4. Keycloak起動

  5. 設定反映(管理コンソール)


画面(Themes)作成

二つの画面(.ftl)とメッセージファイル(.properties)を作成するため、「openstandia」という新しいThemesを作成しました。ソースコードは こちら です。反映するにはソースコードの openstandia フォルダをそのまま _KEYCLOAK_HOME_/themes/ 配下に配置すれば反映されます。


  • 認証コード入力画面(sms-validation.ftl)

verifyinput.png


  • 認証コードエラー画面(sms-validation-error.ftl)

verifyerror.png


  • メッセージファイル(*.properties)


    • messages_ja.properties (日本語メッセージ)

    • messages_en.properties (英語メッセージ)



メッセージファイルは日本語(jp)対応と英語(en)対応の2つ用意しました。対応する言語は theme.propertieslocalesで設定します。


_KEYCLOAK_HOME_/themes/テーマ名/login/theme.properties

parent=keycloak

import=common/keycloak
locales=en,ja

Themesのカスタマイズ方法は去年の「Keycloakのカスタマイズポイントを整理してみる - Themesについて」で説明していますので、参照してください。


SMS認証モジュール作成

SMS認証モジュールを作成します。先ほど「TwilioのAPI-KEY取得」時にcURLで認証コードの発行、認証コードの確認を行いましたが、これをSMS認証モジュールの中で実行するようにします。


  • SMS認証モジュールに該当するSPIは、認証SPI


  • implements する interface は、 org.keycloak.authentication.Authenticator

まず基本となる以下2つのクラスを作成します。



  • SMS認証モジュールクラス


    • SMSAuthenticator implements Authenticator




  • SMS認証モジュールクラスのファクトリークラス


    • SMSAuthenticatorFactory implements AuthenticatorFactory, ConfigurableAuthenticatorFactory




SMSAuthenticatorFactory実装



  • getId() メソッド


    • プロバイダーIDを返します。(一意)



    public static final String PROVIDER_ID = "sms-authenticator-with-twilio";

public String getId() {
return PROVIDER_ID;
}



  • getDisplayType() メソッド


    • 画面表示名を返します。



    public String getDisplayType() {

return "Twilio SMS Authentication";
}



  • isConfigurable() メソッド


    • 画面(管理コンソール)で設定可能なAuthenticatorかどうかを返す。画面から入力させる項目がある場合は true を返します。今回はAPI-KEYなどを入力させるので true




  • getConfigProperties() メソッド


    • 画面(管理コンソール)入力項目の定義です。API-KEY、認証コード桁数、プロキシ設定などを管理コンソールから入力させたいのでここで設定します。



    private static final List<ProviderConfigProperty> configProperties;

static {
configProperties = ProviderConfigurationBuilder
.create()
.property()
.name(SMSAuthContstants.CONFIG_SMS_API_KEY)
.label("API-KEY")
.type(ProviderConfigProperty.STRING_TYPE)
.helpText("")
.add()

......

.property()
.name(SMSAuthContstants.CONFIG_CODE_LENGTH)
.label("Code Length")
.type(ProviderConfigProperty.STRING_TYPE)
.helpText("")
.defaultValue(4)
.add()

.build();
}

......

public List<ProviderConfigProperty> getConfigProperties() {
return configProperties;
}



  • getRequirementChoices() メソッド


    • サポートするRequirementタイプを返します。今回は必須(REQUIRED)、無効(DISABLED)のみ設定します。他にはALTERNATIVE(代替)、OPTIONAL(任意)があります。



    private static final AuthenticationExecutionModel.Requirement[] REQUIREMENT_CHOICES = {

AuthenticationExecutionModel.Requirement.REQUIRED,
AuthenticationExecutionModel.Requirement.DISABLED
};

public Requirement[] getRequirementChoices() {
return REQUIREMENT_CHOICES;
}


  • SMSAuthenticatorFactoryクラスの登録するために、META-INF配下に、以下のようにファクトリークラス名を記述した定義ファイルを配置します。


META-INF/services/org.keycloak.authentication.AuthenticatorFactory

jp.openstandia.keycloak.authenticator.SMSAuthenticatorFactory



SMSAuthenticator実装



  • authenticate(AuthenticationFlowContext context) メソッド


    • 認証処理、このメソッドでSMS認証コード送信処理を実装



public void authenticate(AuthenticationFlowContext context) {

......

if (sendVerify.sendSMS(phoneNumber)) { // SMS送信

Response challenge = context.form().createForm("sms-validation.ftl");
context.challenge(challenge);

} else {

// SMS失敗時はエラー画面を返します
Response challenge = context.form().setError(new FormMessage("sendSMSCodeErrorMessage"))
.createForm("sms-validation-error.ftl");
context.challenge(challenge);
}

......
}

ここで注目すべきなのは結果の戻し方です。Response(Challenge)情報に戻す画面を設定(createForm)して context に設定します。エラーが発生した場合はエラーメッセージを設定(setError)することもできます。setError の設定値 new FormMessage("sendSMSCodeErrorMessage")sendSMSCodeErrorMessageは、Themesの messages ファイル messages_xx_propertiesに定義されたメッセージKeyになります。



  • action(AuthenticationFlowContext context) メソッド


    • このメソッドで画面から入力された認証コードをチェックする処理を実装



public void action(AuthenticationFlowContext context) {

MultivaluedMap<String, String> inputData = context.getHttpRequest().getDecodedFormParameters();
String enteredCode = inputData.getFirst("smsCode");

......

if (sendVerify.verifySMS(phoneNumber, enteredCode)) { // 認証コード確認
logger.info("verify code check : OK");
// 認証コードOK時
context.success();

} else {
// 認証失敗時はエラー画面を返す
Response challenge = context.form()
.setAttribute("username", context.getAuthenticationSession().getAuthenticatedUser().getUsername())
.setError(new FormMessage("invalidSMSCodeMessage")).createForm("sms-validation-error.ftl");
context.challenge(challenge);
}

......
}

ここも同じく結果の戻し方に注目です。verifySMS で認証コードのチェックが正常だった場合は、context.success()でこの認証結果はOKになります。エラーの場合は、authenticate メソッドと同じく、Response(Challenge)に表示画面やエラーメッセージを設定して context に設定します。


SMS送信/確認処理

上記SMSAuthenticatorで実装するSMS送信/コード確認処理は、HttpsURLConnection を使ってTwilioのAPIを利用して実装しました。SMS送信(TwilioのAPI呼出)処理は こちら

モジュール作成は以上です。ここでは重要なメソッドのみを紹介しました。サンプルモジュールのソースコードをGitHub公開していますので、細かい設定はソースコードを確認してください。 ソースコードは こちら


カスタマイズモジュールをKeycloakに反映

作成したファイルをKeycloakに反映します。


Themesの配置

作成したThemesファイル(Openstandiaフォルダごと) _KEYCLOAK_HOME_/themes/ に配置します。「画面(Themes)作成」時に配置済みであればスキップしてください。


認証モジュール(.jar)の配置

作成した認証モジュールはmvn packageでパッケージングして、jarファイルを _KEYCLOAK_HOME_/standalone/deployments/ に配置します。


Keycloak起動

カスタマイズモジュールを全て配置したら、Keycloakを起動します。


設定反映(管理コンソール)


Themesの反映

Themesを反映します。「レルムの設定」ー「テーマ」タブから行います。今回はログインテーマのみ作成していますので「ログインテーマ」を「openstandia」に変更します。その他のテーマは変更しません。

themes.png


認証フローの修正

SMS認証モジュールを認証処理に追加する為に、管理コンソールから認証フローを修正します。

「管理コンソール」ー「認証」ー「Browser」の認証フロー画面

console1.png

(デフォルトの「Browser」認証フローは直接修正できないため)「Browser」の認証フローをコピーします。認証フロー名は任意。

console2.png

コピーした「Openstandia Browser」認証フロー

console3.png

「Openstandia Browser Forms」の「アクション」をクリックして「Execution を追加」をクリック。

console4.png

今回作成したモジュールを選択。ここの表示名は SMSAuthenticatorFactorygetDisplayType で設定した名称。

console5.png

「Twilio SMS Authentication」を追加して、実行順序を「OTP Form」の上に移動。「OTP Form」は無効(DISABLED)に設定(任意)

console6.png

「Twilio SMS Authentication」の「アクション」をクリックして「設定」をクリック。SMSAuthenticatorFactorygetConfigProperties で設定した画面項目がここで表示されます。

console7.png


  • 「API-KEY」はTwilioで取得したAPI-KEYを設定します。

  • プロキシが必要であれば、「Proxy Enabled」を「オン」にしてプロキシ情報を入力します。

  • 「SMS Code Length」は送信する認証コードの桁数です。

認証フローに戻り、「バインディング」タブをクリック。ブラウザーフローをコピーした「Openstandia browser」に変更します。

console8.png

これで、管理コンソールの変更は完了です。


動作確認

事前にログインするユーザー属性に電話番号情報を追加します。電話番号属性の「Key」は認証モジュール内の属性名と合わせます。

user_telnum.png

アカウント管理画面(http://localhost:8080/auth/realms/レルム名/account) にログインします

Login.png

認証コード入力画面が表示されます。

verifyinput.png

入力した電話番号にSMSで認証コードが通知されます。

認証コード.png

認証コードを入力します

verify1.png

ログイン完了です

verifyok.png

※ 以下は間違ったコードを入力した場合のエラー画面。「認証コードが一致しません。」というエラーメッセージは Response(Challenge) の setError で設定したメッセージです。

verifyerror.png

動作確認は以上です。


最後に

認証SPIをカスタマイズして認証処理にSMS認証を追加してみました。Keycloakのカスタマイズは認証SPIに限らず全SPIのカスタマイズ方法は基本的に同じです。

簡単に言えば、


  • カスタマイズする機能に該当するSPIを確認する。(今回は認証SPI)


  • カスタマイズする機能が implements すべき interface を確認する。(今回はAuthenticator)


  • 対象 interfaceimplements して用意されているメソッドを実装する。


これだけです。

3つ目のメソッドを実装する際に各メソッドがどういう役割なのかを理解しながら実装していきます。(ここがメインなので一番時間かかりますが、、)

どのSPIのカスタマイズでも一度経験すれば、次からは別のSPIをカスタマイズすることになっても、スムーズに実装できると思います。ぜひ、Keycloakのカスタマイズをチャレンジしてみてください :thumbsup:


参照資料

mark.png