keycloak-modern-login/README.md

75 lines
3.2 KiB
Markdown
Raw Normal View History

2023-02-19 02:02:36 +01:00
# A modern Keycloak login theme
2023-02-20 19:23:16 +01:00
keycloak-modern-login is a Keycloak login theme that's build using Tailwind CSS, Vue.js 3 and Typescript. It is easily extensible and bypasses the complexity of FreeMarker templates.
2023-02-19 02:02:36 +01:00
2023-02-19 22:36:52 +01:00
<details>
<summary>Screenshots</summary>
![](docs/login-form.jpg)
2023-02-21 21:54:02 +01:00
![](docs/select-authenticator.jpg)
2023-02-20 22:50:54 +01:00
![](docs/login-webauthn.jpg)
2023-02-19 22:36:52 +01:00
</details>
2023-02-19 02:02:36 +01:00
## State of this project
I wrote this project mainly for my own Keycloak instance. Since I don't have much time for that, only the pages I see in daily use are currently customized. For all other pages, Keycloak's default theme is used instead.
## Building a deployable JAR file
The project's development and building process are tested only on Linux. Node.js as well as Yarn must already be installed.
```bash
# Install dependencies
yarn install
# Build a deployable JAR file
yarn build
```
The final JAR (`theme.jar`) will be located inside the `dist` folder.
## Development
To be able to test the theme live during development, a Keycloak Docker container is used. The `dist` folder is mounted directly into the container without building a JAR. The theme is not cached, and changes are directly visible.
The compose file in the root directory starts a preconfigured Keycloak container. A realm named `test` is automatically imported, in which the theme is configured as the default login theme. The admin user in the `master` realm has `admin` as both its username and password.
```bash
# Install dependencies
yarn install
# Run fist dev build to create the folder structure
# Once Webpack has successfully compiled the project, you can cancel the process by pressing CTRL + C
yarn dev
# Start the development Keycloak instance
docker compose up -d
# Start Webpack in dev mode (which watches for changes and rebuilds the project automatically)
yarn dev
```
For testing, the account console of the test realm can be used to get a login window: [http://localhost:8080/realms/test/account](http://localhost:8080/realms/test/account)
### Adding new pages
If you want to add new pages, there are some things to be aware of.
- Create a new subfolder for the page in the `views` folder. The name of the new folder must match the name of the FTL file in the [Keycloak base theme](https://github.com/keycloak/keycloak/tree/main/themes/src/main/resources/theme/base/login).
- Copy the three `index.*` files of an existing page into the new folder. The page name also needs to be adjusted in the `index.ftl` file within the attribute `pageId` as well as in the path for the script.
- Add the new page in `webpack.config.js` in the upper part to the list `customPages`.
2023-04-16 21:33:06 +02:00
### Localization
If the browser language is supported, it will be loaded automatically. Otherwise, English is loaded by default.
To add new languages, the corresponding file must be added under `static/login/resources/locales`. Then the language must be added to `SUPPORT_LOCALES` in `functions/i18n.ts`.
2023-10-29 13:55:58 +01:00
### Credits
Special thanks to the following projects, without which the development of keycloak-modern-login would not be possible:
- [Keycloakify](https://github.com/keycloakify/keycloakify), from which the [`ftl_object_to_js_code_declaring_an_object`](src/static/login/baselayout.ftl) function and [Keycloak context type definitions](src/types/context.ts) are derived.