はじめに

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

SMS？SMS認証？

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

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

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

Twilioとは？

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」まで進むと以下の画面が表示されます。番号の順番通りに進めましょう。

「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もここで確認できます。（設定画面からも確認できます）

「4. Get verified」
- 受信した認証コードが正しいかcURLで確認します。

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

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

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

アカウント管理画面を表示
- http://localhost:8080/auth/realms/レルム名/account

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

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

認証機能のカスタマイズ

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

画面(Themes)作成
SMS認証モジュール作成
カスタマイズモジュールをKeycloakに反映
Keycloak起動
設定反映(管理コンソール)

画面(Themes)作成

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

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

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

メッセージファイル(*.properties)
- messages_ja.properties （日本語メッセージ）
- messages_en.properties （英語メッセージ）

メッセージファイルは日本語（jp）対応と英語（en）対応の２つ用意しました。対応する言語は theme.properties のlocalesで設定します。

_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

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

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 に設定します。