メインコンテンツにスキップ

Casdoorのログインページのカスタマイズ: フォークせずに認証UIをカスタムスタイリング

· 1分読む
Yang Luo
Yang Luo
Casdoor Maintainer

はい、Casdoorは認証UIのカスタムスタイリングをサポートしており、フロントエンドをフォークする必要はありません。すべてのアプリケーションには UI Customization タブがあり、ここでロゴ、ファビコン、背景画像、デスクトップ用とモバイル用のカスタムCSS、フォームの位置、サイドパネル、フッターHTML、テーマを設定できます。Signin items と Signup items の2つのテーブルにより、ログインおよびサインアップページに表示されるフィールド、その順序、ラベル、プレースホルダーが決まります。これらはすべてデータベースにアプリケーションごとに保存されるため、1つのCasdoorインスタンスで多くの異なるブランド化されたログインページを提供でき、組織管理者は安全な制限内で自分のページを編集できます。

変更内容と場所​

変更したい内容Casdoor内の場所ドキュメント
プライマリカラー、角丸、ダークまたはコンパクトスタイル組織の Theme、または Follow organization theme をオフにしたアプリケーションのテーマCustomize the theme
完成済みの見た目全体Identity → Marketplace、サインインテーマMarketplace
ロゴ、ダークロゴ、ファビコン、ページタイトルアプリケーション編集ページApplication settings
背景画像（デスクトップとスマホ）Background URL、Background URL MobileUI customization
フォームの外観Custom CSS、Custom CSS MobileUI customization
フォームを左、中央、右に配置、またはパネルの横に配置Form position、Side panel HTMLUI customization
フォーム下のテキストFooter HTMLApplication settings
ログインページに表示するフィールド、順序、プレースホルダーSignin itemsSign-in items table
パスワード、コード、マジックリンク、WebAuthn、LDAPとその順序Signin methodsSign-in methods
サインアップフィールド、必須フラグ、ラベル、正規表現Signup itemsSign-up items table
言語セレクターLanguages サインイン項目、組織の LanguagesSign-in items table
ユーザーに組織を選択または入力させるOrg choice modeSpecify login organization

中国語コンソールではタブが「界面定制」、サインインテーブルが「登录项」と呼ばれるため、アプリケーションの「登录界面」を変更する方法を探している場合は、そこから始めてください。

テーマ: 組織、アプリケーション、Marketplace​

最も迅速な変更はテーマです。Casdoorのテーマは、スタイル（エディタではDefault、Dark、Document、Blossom）、プライマリカラー、境界線半径、コンパクトスイッチを持つ小さなオブジェクトです。これを組織に設定すると、メンバー用のコンソールと組織テーマに従うすべてのアプリケーションのエントリーページに適用されます。または、Follow organization theme をオフにして単一のアプリケーションに設定することもできます。アプリケーション編集ページにはライブプレビューがあるため、保存前に結果を確認できます。

色以上の変更をしたい場合、Casdoor Marketplace にサインインテーマがあります。1つをインストールすると、テーマデータ、フォーム位置、デスクトップとモバイル用のフォームCSS、サイドパネルHTML、フッターHTML、背景URLが書き込まれます。casdoor-integrationsリポジトリには現在、MidnightやSplitからTerminal、Nord、Solarizedまで24のテーマが含まれています。テーマをアンインストールすると、アプリケーションが以前持っていた状態に戻されるため、試すことによるコストはありません。marketplace.casdoor.com で閲覧してください。

ブランディング: ロゴ、ファビコン、背景​

各アプリケーションは、組織とは別に独自の Logo、Favicon、Title を持ちます。1つの組織は、ユーザーを共有しつつ異なるロゴを表示する複数の製品を実行できます。また、オプションの Logo dark もあり、ページがダークモードの場合に表示されます。これが設定されていない場合、Casdoorは通常のロゴを引き続き使用します。

Background URL はフォームの後ろにある画像を設定します。デスクトップ画像がスマホでうまくトリミングされない場合は、Background URL Mobile も設定してください。プレビューはURLが読み込まれると同時に更新されます。

カスタムCSSとフォームレイアウト​

Custom CSS はプレーンなCSSルールを受け入れます。Casdoor自体がstyle要素でラップするため、独自に追加しないでください。ターゲットにする主なコンテナは .login-panel と .login-form です:

.login-panel {
  border-radius: 12px;
  background-color: #ffffff;
  box-shadow: 0 0 30px 20px rgba(0, 0, 0, 0.2);
}

Custom CSS Mobile にはスマホ用のルールが入るため、一般的なケースではメディアクエリを書く必要がありません。

Form position はフォームを左、中央、右に配置します。4番目のオプションである Enable side panel は、フォームを中央に配置し、その隣にコンテンツが Side panel HTML から取得されるパネルを置きます。このフィールドはHTMLを受け取るため、内部にstyle要素を含めても問題ありません。

Footer HTML はサインインおよびサインアップフォームの下にレンダリングされます。アプリケーションが所属組織のデフォルトアプリケーションである場合、そのフッターは当該組織のユーザーに対する管理コンソールの "Powered by Casdoor" も置き換えます。

ステージング環境でのデザインに満足したら、アプリケーション編集ページの下部にある Export JSON で外観（ロゴ、ファビコン、背景、CSS、フォーム位置、サイドパネル、テーマ、カスタムHTMLフィールド）をクリップボードにコピーし、別のインスタンス上の同じアプリケーションで Import JSON を実行して適用します。エクスポートにはシークレットやプロバイダーは含まれません。

フィールド、ラベル、順序​

Signin items テーブルには、ログインページのすべての要素（ロゴ、ユーザー名とパスワードフィールド、パスワード紛失時のリンク、同意チェックボックス、言語セレクタ、CAPTCHA、プロバイダボタンなど）が一覧表示されます。各行に対して Visible（表示）、カスタムの Placeholder（プレースホルダー）、項目ごとの Custom CSS（カスタムCSS）、およびルールの設定ができ、上下への移動も可能です。また、ラベルがHTMLであるカスタム項目を追加することもできます。

知っておくべきいくつかのルール:

  • Forgot password? を非表示にすると、リンクだけでなくAPI経由でのパスワードリセットも無効になります。
  • Captcha ルールは、ポップアップ型とインライン型のCAPTCHAを切り替えます。CAPTCHAプロバイダを選択する場合は、CAPTCHA providers compared for login pages を参照してください。
  • Languages ルールは、地球儀アイコンとラベル付きセレクタを切り替えます。リスト自体は組織の Languages に限定されるため、英語と日本語のみを提供する組織ではそれらの2言語のみが表示されます。

サインイン方法（パスワード、確認コード、マジックリンク、WebAuthn、LDAP、Face IDなど）は、独自の順序と表示名を持つ別のテーブル Signin methods で管理されます。

Signup items テーブルは登録についても同様の機能を提供し、Required（必須）、Regex（正規表現）によるバリデーション、カスタムの Label（ラベル）、メールに対する "No verification"（検証なし）などのルールを設定できます。POST /api/signup は、項目が非表示になっているすべてのフィールドをクリアするため、APIクライアントはフォームに表示されていないフィールドを設定できません。Prompted は、電話番号などの不足しているフィールドについて、そのような情報を提供しなかったプロバイダ経由でサインインした後にユーザーに尋ねます。

ログイン組織の指定​

複数の組織が1つのCasdoorを共有する場合、ユーザーが正しい組織にアクセスするための方法が必要です。組織のデフォルトアプリケーション（または app-built-in）の Org choice mode（組織選択モード）を使用すると、/login に組織ステップが追加されます。Input はテキストフィールドを表示し、Select はドロップダウンを表示します。ユーザーが選択した後、Casdoorは /login/<organization> にリダイレクトし、その組織固有のスタイルが適用されたページを表示します。ブラウザは最後の組織を localStorage に記憶するため、コンソールセッションの有効期限が切れたユーザーは再び自分のログインページに到達します。

テナント管理者が安全に変更できる内容​

すべての顧客が独自のログインページをスタイリングできるようにすると、明白な疑問が生じます: 組織管理者がパスワードをコピーするスクリプトや、入力された各文字を背景画像のリクエストを通じて漏洩させるCSSセレクタを追加することを何阻止するのか？ Casdoorはこれをサーバー側でチェックします。グローバル管理者ではない管理者がアプリケーションを追加または保存する際、変更されたすべてのカスタムHTMLおよびCSSフィールドが検証され、いずれかがルールに違反した場合、保存が拒否されます:

  • HTMLでは、div、span、p、見出し、リスト、リンク、画像、テーブル、style、基本的なSVG図形などのレイアウトおよびテキスト要素のみ使用できます。script、form、input、iframe、および on... イベントハンドラー、srcset、formaction、srcdoc などの属性は拒否されます。href は、相対URL、http、https、mailto、または tel URLを持つリンクでのみ許可されます。
  • CSSには、バックスラッシュ、<、image(、image-set( およびその他の一部の関数を含めることはできません。すべての url() は、相対URL、data: URL、または許可されたプレフィックス（Google Fonts、jsDelivr上のFontsource、Casdoor CDN、このCasdoor自身のオリジン、グローバルストレージプロバイダのドメイン、または formCssAllowedUrls のエントリ）で始まる必要があります。
  • @import は、インポートされたスタイルシート自体がチェックされないため、Google FontsとFontsourceからのみ許可されます。

テナントが独自ホストから画像を読み込めるようにするには、それを conf/app.conf に追加してください（Configuration を参照）。

formCssAllowedUrls = "https://img.example.com/"

保存時のチェックに加え、サインインページはレンダリング前にカスタムHTMLをサニタイズ（消毒）しますが、これはアプリケーションが built-in 組織に属する場合、またはグローバル管理者がそのアプリケーションに対して Enable custom scripts（カスタムスクリプトを有効化）をオンにした場合を除きます。このスイッチをオンにできるのはグローバル管理者のみであり、オンの間はそのアプリケーションのHTMLを変更できるのもグローバル管理者のみです。テナントがマーケットプレイステーマをインストールする場合も同じルールが適用されます。これらのルールに違反するテーマは、グローバル管理者によってのみインストールできます。

Signin HTML と Signup HTML は特別な注意が必要です: これらはフォームを含む組み込みページ全体を置き換えます。テナントはフォームやスクリプトを追加できないため、これら2つのフィールドは主にグローバル管理者向けです。ブランディングには、CSS、サイドパネル、フッターの方が適切なツールです。

ホストされたログインページか、独自UIか？​

CasdoorのAPIを使って独自のログイン画面を構築することもできますが、通常はホストされたページの方がより良い選択肢です。OAuth 2.0またはOpenID Connectを使用すると、ユーザーはパスワードをCasdoorのオリジンでのみ入力し、アプリケーションは認可コードを受け取りますが、認証情報を受け取ることはありません。CAPTCHA、MFA、ソーシャルおよびエンタープライズプロバイダ、パスワード紛失時の処理、サインアップ検証、組織ピッカーは、あなたの側のコードなしで動作し続け、Casdoorをアップグレードすると修正も受け続けます。カスタムUIではこれらのフローをそれぞれ再実装する必要があり、パスワードを独自サーバー経由で処理することになります。ホストされたページをアプリに接続するためのガイド: Spring Boot SSO with OIDC および Nginx SSO authentication。

他のホスト型プロバイダも同じトレードオフを取っています。例えば Idura Verify では、ダッシュボードからログインボックスの周囲にスタイルシートURLとカスタムHTMLを追加できますが、これはフォントと画像用のスタイルオリジンの明示的なリストを含む厳格なContent Security Policyの下で行われます。Casdoorの formCssAllowedUrls も同じ役割を果たしますが、Casdoorはオープンソースかつセルフホスト型であるため、あなたがリストを制御できるという点で異なります。

参考資料​