Налаштування сторінки входу в Casdoor: кастомне стилізація інтерфейсу автентифікації без форкування
Так, Casdoor підтримує кастомну стилізацію свого інтерфейсу автентифікації, і вам не потрібно форкувати фронтенд для цього. У кожного додатка є вкладка UI Customization, де можна налаштувати логотип, favicon, зображення фону, кастомний CSS для десктопа та мобільних пристроїв, розташування форми, бічну панель, HTML футера та тему. Дві таблиці, Signin items та Signup items, визначають, які поля відображаються на сторінках входу та реєстрації, у якому порядку, з якими мітками та плейсхолдерами. Усе це зберігається в базі даних для кожного додатка окремо, тому один екземпляр Casdoor може обслуговувати багато брендів із різними сторінками входу, а адміністратори організацій можуть редагувати свої сторінки в межах безпечних обмежень.
Що змінити і де
| Що ви хочете змінити | Де в Casdoor | Документація |
|---|---|---|
| Основний колір, радіус кутів, темний або компактний стиль | Theme організації або додатка (якщо Follow organization theme вимкнено) | Налаштування теми |
| Повністю готовий вигляд | Identity → Marketplace, теми входу | Marketplace |
| Логотип, темний логотип, favicon, заголовок сторінки | Сторінка редагування додатка | Налаштування додатка |
| Зображення фону (десктоп і телефон) | Background URL, Background URL Mobile | Кастомізація UI |
| Вигляд форми | Custom CSS, Custom CSS Mobile | Кастомізація UI |
| Форма зліва, по центру чи справа, або поруч із панеллю | Form position, Side panel HTML | Кастомізація UI |
| Текст під формою | Footer HTML | Налаштування додатка |
| Які поля показує сторінка входу, порядок, плейсхолдери | Signin items | Таблиця елементів входу |
| Пароль, код, магічне посилання, WebAuthn, LDAP та їхній порядок | Signin methods | Методи входу |
| Поля реєстрації, обов'язкові прапорці, мітки, регулярні вирази | Signup items | Таблиця елементів реєстрації |
| Вибір мови | Елемент входу Languages, параметр Languages організації | Таблиця елементів входу |
| Дозволити користувачам вибирати або вводити свою організацію | Org choice mode | Вказати організацію для входу |
У китайській консолі вкладка називається 界面定制, а таблиця входу — 登录项, тому якщо ви шукаєте спосіб змінити 登录界面 додатка, почніть звідти.
Теми: організація, додаток і Marketplace
Найшвидша зміна — це тема. Тема в Casdoor — це невеликий об'єкт зі стилем (Default, Dark, Document або Blossom у редакторі), основним кольором, радіусом рамки та перемикачем компактного режиму. Її можна встановити на рівні організації, де вона застосовується до консолі для її учасників і до вхідних сторінок кожного додатка, який слідує темі організації, або на рівні окремого додатка, вимкнувши Follow organization theme. На сторінці редагування додатка є живий перегляд, тому ви можете побачити результат перед збереженням.
Якщо вам потрібно більше, ніж просто кольори, у Casdoor Marketplace є теми входу. Встановлення однієї теми записує дані теми, розташування форми, CSS форми для десктопа та мобільних пристроїв, HTML бічної панелі, HTML футера та URL фонового зображення одного додатка. Репозиторій casdoor-integrations наразі містить 24 теми, від Midnight і Split до Terminal, Nord і Solarized. Видалення теми відновлює попередні налаштування додатка, тому спроба нічого не коштує. Перегляньте їх на marketplace.casdoor.com.
Брендинг: логотип, favicon і фон
Кожен додаток має власні Logo, Favicon та Title, окремі від налаштувань організації. Одна організація може керувати кількома продуктами, які спільно використовують користувачів, але показують різні логотипи. Також є необов'язковий параметр 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 розміщує форму зліва, по центру або справа. Четвертий варіант, Enable side panel, центрально розташовує форму і додає поруч панель, вміст якої береться з Side panel HTML. Це поле приймає HTML, тому елемент style всередині нього теж працює.
Footer HTML відображається під формами входу та реєстрації. Якщо додаток є стандартним для своєї організації, його футер також замінює напис "Powered by Casdoor" в адміністративній консолі для користувачів цієї організації.
Коли вас задовольнить дизайн на стадії тестування, кнопка Export JSON внизу сторінки редагування додатка скопіює зовнішній вигляд (логотип, favicon, фони, CSS, розташування форми, бічну панель, тему та поля кастомного HTML) у буфер обміну, а Import JSON на тому самому додатку в іншому екземплярі застосує його. Експорт не містить секретів або провайдерів.
Поля, мітки та порядок
Таблиця Signin items перелічує кожен елемент сторінки входу: логотип, поля імені користувача та пароля, посилання "Забули пароль", чекбокс погодження, селектор мови, капчу, кнопки провайдерів тощо. Для кожного рядка можна налаштувати Visible, власний Placeholder, індивідуальний Custom CSS для елемента та правило, а також переміщувати його вгору або вниз. Також можна додавати власні елементи, мітка яких є HTML-кодом.
Кілька правил, які варто знати:
- Приховування Forgot password? вимикає скидання пароля також в API, а не лише посилання на інтерфейсі.
- Правило Captcha перемикає між спливаючою та вбудованою (inline) капчею. Якщо ви обираєте провайдера капчі, дивіться Порівняння провайдерів CAPTCHA для сторінок входу.
- Правило Languages перемикає між іконкою глобуса та селектором з підписом. Сам список обмежений значеннями Languages організації, тому організація, що обслуговує лише англомовних та японськомовних користувачів, покаже тільки ці дві мови.
Способи входу (пароль, код підтвердження, магічне посилання, WebAuthn, LDAP, Face ID та інші) знаходяться в окремій таблиці Signin methods, яка має власний порядок відображення та назви.
Таблиця Signup items робить те саме для реєстрації, з опціями Required, валідацією за Regex, власним Label та правилами, такими як "No verification" для email. POST /api/signup також очищає всі поля, елементи яких приховані, тому клієнти API не можуть встановити поля, які не відображаються у вашій формі. Prompted запитує у користувачів відсутні дані, такі як номер телефону, після того як вони увійшли через провайдера, який їх не надав.
Вказати організацію для входу
Якщо кілька організацій використовують один Casdoor, користувачам потрібен спосіб потрапити до правильної. Org choice mode у додатку за замовчуванням організації (або в app-built-in) додає крок вибору організації до /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. - CSS не може містити зворотні слеші,
<,image(,image-set(та кілька інших функцій. Коженurl()має бути відносним,data:URL або починатися з дозволеного префікса: Google Fonts, Fontsource на jsDelivr, CDN Casdoor, власний origin цього Casdoor, домени глобальних провайдерів сховища або запис ізformCssAllowedUrls. @importдозволено лише з Google Fonts та Fontsource, оскільки імпортований табличний стиль не перевіряється сам по собі.
Щоб дозволити орендарям завантажувати зображення з вашого хосту, додайте його до conf/app.conf (див. Конфігурація):
formCssAllowedUrls = "https://img.example.com/"
Окрім перевірки під час збереження, сторінки входу санітизують власний HTML перед рендерингом, якщо додаток не належить до організації built-in або глобальний адмін не увімкнув для нього Enable custom scripts. Лише глобальний адмін може увімкнути цей перемикач, і поки він увімкнений, лише глобальний адмін може змінювати HTML цього додатка. Ті самі правила діють, коли орендар встановлює тему з Marketplace: тема, яка порушує їх, може бути встановлена лише глобальним адміном.
Signin HTML та Signup HTML потребують окремої примітки: вони замінюють всю вбудовану сторінку, включно з формою. Оскільки орендарі не можуть додавати форми чи скрипти, ці два поля переважно для глобальних адміністраторів; для брендингу кращими інструментами є CSS, бічна панель та футер.
Хостингова сторінка входу чи власний UI?
Ви можете створити власний екран входу на основі API Casdoor, але хостингова сторінка зазвичай є кращим вибором. При використанні OAuth 2.0 або OpenID Connect користувачі вводять свій пароль лише на домені Casdoor, а ваш додаток отримує код авторизації, ніколи не бачачши облікові дані. Капча, MFA, соціальні та корпоративні провайдери, скидання пароля, валідація реєстрації та вибір організації продовжують працювати без написання коду на вашому боці, і вони отримують виправлення при оновленні Casdoor. Власний UI має повторно реалізувати кожен із цих процесів і пропускає паролі через ваші власні сервери. Посібники щодо інтеграції хостингової сторінки в додаток: Spring Boot SSO з OIDC та Nginx SSO authentication.
Інші хостингові провайдери роблять той самий вибір. Наприклад, Idura Verify дозволяє додати URL стилів та власний HTML навколо свого блоку входу з панелі керування, у межах суворої Content Security Policy з явним списком origin для шрифтів та зображень. formCssAllowedUrls Casdoor виконує ту ж роль, з різницею в тому, що Casdoor є open source та self-hosted, тому ви контролюєте цей список.