2023年8月現在、Auth0を利用してログイン・サインインフローを提供する場合、セキュリティやユーザー体験の快適さからNew Universal Login（NUL）を利用することがOktaから推奨されており、またアプリケーション側での実装が不要なため開発コストも低く済むので、導入を検討する方が多いことと思います。
今回はこのNULにおいて、所望のデザインを実現する方法について紹介します。
NULの概要についてはAuth0の記事をはじめ、いろいろなページで詳細に解説されていますので、今回は説明しません。
NULで調整できる項目と、その調整方法
NULを利用する場合、大きく分けて以下の二つの要素を調整可能です。
- ログインユーザーが入力するフォーム部分（
auth0:widgetと呼ぶことにします） - フォーム以外の部分
ここでいう１番のフォーム部分というのは、下の画像（ソースはリンク）のような、プロダクトもしくは開発企業のロゴやメールアドレス・パスワードの入力フォーム、ソーシャルログインボタンを備えたwidgetを指します。
パスワードの再発行などでもこのwidgetが活躍し、その際は入力部分が存在しない場合もあるので、厳密にはフォームとは呼べないかもしれません。今回はこの要素をauth0:widgetと呼ぶことにします。
auth0:widgetではロゴ画像や表示される文言、フォントの色やサイズ、ボタンの色などを調整可能です。ただしそのテンプレートの全てを調整できるわけではなく、その表示順序だったりサポートされていない要素の配置などは基本的に不可能です。
調整可能な項目については、Auth0のWebダッシュボードでBranding > Universal Loginに進むことで簡単に操作可能です。API（Management API）からも管理が可能です。
Webは下の画像のようなUIなのですが、とてもわかりやすく変更も「Try」からすぐに確認可能なため、今回は解説しません。
ちなみに２枚目の画像において、何も文言を何も入れたくない項目については半角スペースを入力すると、何も表示がされなくなります。
２番目のフォーム以外の部分というのは少しわかりづらい表現ではありますが、１のauth0:widget以外の部分全てです。
NULの画面はサーバー側でレンダリングされた状態でクライアントに届くのですが、デフォルトの状況でそのhtmlを眺めると<main></main>で囲われた要素が見つかると思います。
そこがauth0:widgetの部分なのですが、そのmainタグ以外の部分はテンプレートとして調整が可能です。
これにより、NULの画面にヘッダーやフッターを配置したり、aタグを使って利用規約へのリンクを表示したりすることも可能です。
こちらに関してもManagement APIから操作可能な他、Auth0 Deploy CLI（コマンドはa0deploy）やAuth0 CLI（コマンドはauth0）を利用することでも操作が可能です。
このテンプレートの調整の作法と、Management APIを利用したデプロイ方法について以下で解説します。
NULテンプレートの作法
Management APIを利用したNULテンプレートデプロイの公式Docsがあります。こちらを参照しながら実行していくのが確実ですが、いくつかポイントを解説します。
まず、NULテンプレートはLiquid templateを利用してカスタマイズすることになります。
恥ずかしながら私はこの開発に携わるまで、Liquid templateを知らなかったので、ChatGPTに聞いてみました。
Liquidテンプレートとは？
Liquid（リキッド）は、ウェブテンプレートエンジンの一種です。ウェブアプリケーションや電子商取引サイトなどで、ダイナミックなコンテンツの生成や表示を行うために使用されます。特に、Shopifyというeコマースプラットフォームで広く使われており、テーマのデザインやレイアウトをカスタマイズする際に活用されています。
その後ググって齟齬がないか確認してみましたが、誤りはありませんでした。
どうやらShopifyが開発したようで、2006年誕生のようです。
今回の記事はLiquid templateの記事ではないので詳しくは説明しませんが、テンプレート中の{{ }} 内に変数やタグを配置することで、テンプレート内で変数表示や条件分岐、ループなどの動的な情報の表示や制御を行うことができます。
上のAuth0の公式Docsを見ると、NUL画面のシンプルなテンプレート例は以下のように提示されています。
<!DOCTYPE html>
<html>
<head>
{%- auth0:head -%}
</head>
<body>
{%- auth0:widget -%}
</body>
</html>
auth0:headとauth0:widgetはどちらもNULテンプレートに必須のオブジェクトです。
auth0:widgetはログインやパスワードリセットなど、各ページに表示されるウィジェットのhtmlを返します。（上の章で名付けたauth0:widgetとそのまま対応します）
auth0:headは、ウィジェットをレンダリングするために必要なタグ（meta、style、scriptタグ等）を返します。
つまり、auth0:headとauth0:widgetを適切な位置に含むようにさえすれば、あとは自由にhtmlを改造可能ということです。
公式Docsでは、右側に画像を表示する用やレイアウトやフッターを表示するようなレイアウトが紹介されています。
私自身はhtmlをうまく書くことで、下の画像のような見た目を実現しました。
ヘッダーやフッターを追加したり、使用規約やプライバシーポリシーを追加したりしています。
auth0:widget内の表示文言やボタンの色はWebのコンソールから修正しています。
ちなみにLiquid templateで利用可能な変数は、こちらに一覧表示されています。
もしなんらかの用途で画面に応じて条件分岐をしたい場合などは、そちらにある値は利用可能です。
NULテンプレートのManagement APIを利用したデプロイ方法
htmlが準備できたら、あとはデプロイするだけです。
その方法は公式Docsにある通りではありますが、一応解説します。
まず初めにWebコンソールからApplications > APIsに進みます。
すると、Auth0 Management APIというAPIがデフォルトであると思います。
その項目のAPI AudienceのURLがエンドポイントになっているので、そのドメインをコピーして下のcurlコマンドの自分のドメインのところに対応させてください。
curl --request PUT \
--url 'https://自分のドメイン/api/v2/branding/templates/universal-login' \
--header 'authorization: Bearer ここにアクセストークン' \
--header 'content-type: text/html' \
--data 'ここにhtml'
その後、Auth0 Management APIを押下するとAPI Explorerというタブがあると思うので、そちらに進みます。
（この作業によって、ApplicationsにAPI Explorer Applicationというアプリが自動で追加されるはずです）
すると、Tokenが表示されると思うので、それをコピーして上のコマンドの「ここにアクセストークン」のところに貼り付けます。（「Bearer + 半角スペース」はそのまま）
あとは「ここにhtml」のところに、ご自身で作成したhtmlをベタ書きで貼り付けて実行すればOKです。
実行後にNULのログイン画面などにアクセスすると、うまくテンプレートが反映されているのが確認できるはずです。
ダッシュボードでは調整できないような仕様をauth0:widgetに反映させるには
ここまではAuth0が用意してくれている正攻法で、好みのデザインを実現する方法を紹介してきました。
テンプレートには自由にhtmlを記述することができるため大方のデザインは実現できると思いますが、auth0:widget内部のデザインはそのままでは実現できるデザインに限度があります。
これを無理やり調整するには、auth0:widgetによって提供されるhtmlの構造を把握して、特定の要素にcssを適用することが有効です。
例えば2023年8月現在において、ログイン画面におけるパスワード忘れへの対応リンクは、main > section > form > pという構造で置かれていることがわかります。
そのため例えば、以下のようなstyleをheadに追加することで、パスワード忘れの文言のデザインを調整することが可能です。
<head>
<style>
main section form p {
margin-top: 10px;
margin-bottom: -10px;
}
</style>
</head>
これを応用すれば、特定の要素をdisplay: hiddenにすることで非表示にしたり、scriptを利用することで文言を追加したり、特定のページのみでとある要素を非表示にしたりする、といったことが可能です。
ただしAuth0の公式Docsの最後に次のような注意が書かれています。
Additional considerations:
- The HTML structure of these pages may also change. Any customizations that depend on that structure could stop working at any time.
つまりhtmlの構造はいつでも変わる可能性があるので、このような調整をしていると突然デザインが崩れることもある、ということです。
このことをきちんと頭に入れた上で、上記のテクニックを利用するようにしてください。
まとめ
Auth0のNew Universal Loginを利用したログイン画面等のデザインを調整法を紹介しました。
テンプレートやwidget内部の見た目を調整する機能が提供されているので、おおよそのデザイン要件はそれらを活用することで実現可能であるはずです。
実は現在、Auth0を認証基盤として利用したSaaSを開発しており、その中で得た知見を記事化しました。
そちらのサービスは、Qiitaを利用している皆さんにとって役に立つであろう機能を中心としたものになっています。
皆さんにご利用いただけるのが楽しみです。
早く皆さんにご提供できるよう、開発に力を入れていきたいと思います！