From 044ec1a2daa432814e06795f0e218c537ebac5fe Mon Sep 17 00:00:00 2001 From: Joseph Garrone Date: Mon, 12 Apr 2021 02:24:11 +0200 Subject: [PATCH] Important readme update --- README.md | 185 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 112 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 72443bd6..900f3a41 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

- 🔏 Customize key cloak's pages as if they were part of your App 🔏 + 🔏 Build Keycloak theme with React 🔏

@@ -18,80 +18,110 @@ # Motivations -The problem: +Keycloak provides [theme support](https://www.keycloak.org/docs/latest/server_development/#_themes) for web pages. This allows customizing the look and feel of end-user facing pages so they can be integrated with your applications. +It involves, however, a lot of raw JS/CSS/[FTL]() hacking, and bundling the theme is not exactly straightforward. + +Beyond that, if you use Keycloak for a specific app you want your login page to be tightly integrated with it. +Ideally, you don't want the user to notice when he is being redirected away. + +Trying to reproduce the look and feel of a specific app in another stack is not an easy task not to mention +the cheer amount of maintenance that it involves.

- Without keycloakify:
+ Without keycloakify, users suffers from a harsh context switch, no fronted form pre-validation

-When we redirected to Keycloak the user suffers from a harsh context switch. -Keycloak does offer a way to customize theses pages but it requires a lot of raw HTML/CSS hacking -to reproduce the look and feel of a specific app. Not mentioning the maintenance cost of such an endeavour. -Wouldn't it be great if we could just design the login and register pages as if they where part of our app? -Here is `yarn add keycloakify` for you 🍸 +Wouldn't it be great if we could just design the login and register pages as if they were part of our app? +Here is `keycloakify` for you 🍸

- With keycloakify:
+ With keycloakify: +

-**TL;DR**: [Here](https://github.com/garronej/keycloakify-demo-app) is a Hello World React project with Keycloakify set up. +If you already have a Keycloak custom theme, it can be easily ported to Keycloakify. + +--- + - [Motivations](#motivations) - [How to use](#how-to-use) - [Setting up the build tool](#setting-up-the-build-tool) - - [Developing your login and register pages in your React app](#developing-your-login-and-register-pages-in-your-react-app) - - [Just changing the look](#just-changing-the-look) + - [Changing just the look of the default Keycloak theme](#changing-just-the-look-of-the-default-keycloak-theme) - [Changing the look **and** feel](#changing-the-look-and-feel) - [Hot reload](#hot-reload) -- [Terms and conditions](#terms-and-conditions) + - [Enable loading in a blink of an eye of login pages ⚡ (--external-assets)](#enable-loading-in-a-blink-of-an-eye-of-login-pages----external-assets) +- [Support for Terms and conditions](#support-for-terms-and-conditions) - [GitHub Actions](#github-actions) - [Requirements](#requirements) - [Limitations](#limitations) - [`process.env.PUBLIC_URL` not supported.](#processenvpublic_url-not-supported) - [`@font-face` importing fonts from the `src/` dir](#font-face-importing-fonts-from-thesrc-dir) - [Example of setup that **won't** work](#example-of-setup-that-wont-work) - - [Workarounds](#workarounds) + - [Possible workarounds](#possible-workarounds) - [Implement context persistence (optional)](#implement-context-persistence-optional) -- [API Reference](#api-reference) - - [The build tool](#the-build-tool) # How to use + +**TL;DR**: [Here](https://github.com/garronej/keycloakify-demo-app) is a Hello World React project with Keycloakify set up. ## Setting up the build tool +```bash +yarn add keycloakify +``` + [`package.json`](https://github.com/garronej/keycloakify-demo-app/blob/main/package.json) ```json -"homepage": "https://URL.OF/YOUR-APP" -"dependencies": { - "keycloakify": "^0.0.10" -}, "scripts": { "keycloak": "yarn build && build-keycloak-theme", }, ``` -`"homepage"` must be specified only if the url path is not `/` -(Onl `/YOUR-APP` matters `URL.OF` don't have to be the actual domain) -It is mandatory that you specify the url where your app will be available -using the `homepage` field. +```bash +yarn keycloak # generate a keycloak-theme.jar +``` -Once you've edited your `package.json` you can install your new -dependency with `yarn install` and build the keycloak theme with -`yarn keycloak`. +On the console will be printed all the instructions about how to load the generated theme in Keycloak -Once the build is complete instructions about how to load -the theme into Keycloak are printed in the console. +### Changing just the look of the default Keycloak theme -## Developing your login and register pages in your React app +The first approach is to only customize the style of the default Keycloak login by providing +your own class names. -### Just changing the look - -The first approach is to only arr/replace the default class names by your -own. +If you have created a new React project specifically to create a Keycloak theme and nothing else then +your index should look something like: +`src/index.tsx` ```tsx +import { App } from ".//App"; +import { + KcApp, + defaultKcProps, + kcContext +} from "keycloakify"; +import { css } from "tss-react"; +const myClassName = css({ "color": "red" }); + +reactDom.render( + + document.getElementById("root") +); +``` + +If you have a unique project for your app and the Keycloak theme, your index should look +more like this: + +`src/index.tsx` +```tsx import { App } from ".//App"; import { KcApp, @@ -118,24 +148,30 @@ reactDom.render( ); ``` -result:

- +result: +

+Example of a customization using only CSS: [here](https://github.com/InseeFrLab/onyxia-ui/blob/012639d62327a9a56be80c46e32c32c9497b82db/src/app/components/KcApp.tsx) +(the [index.tsx](https://github.com/InseeFrLab/onyxia-ui/blob/012639d62327a9a56be80c46e32c32c9497b82db/src/app/index.tsx#L89-L94) ) +and the result you can expect: + +//TODO ### Changing the look **and** feel -If you want to really re-implement the pages the best approach is to -create you own version of the [``](https://github.com/garronej/keycloakify/blob/develop/src/lib/components/KcApp.tsx). +If you want to really re-implement the pages, the best approach is to +create your own version of the [``](https://github.com/garronej/keycloakify/blob/develop/src/lib/components/KcApp.tsx). Copy/past some of [the components](https://github.com/garronej/keycloakify/tree/develop/src/lib/components) provided by this module and start hacking around. -You can find an example of a fancy customization [here](https://github.com/InseeFrLab/onyxia-ui/tree/master/src/app/components/KcApp). +You can find an example of such customization [here](https://github.com/InseeFrLab/onyxia-ui/tree/master/src/app/components/KcApp). + +And you can test the result in production by trying the login register page of [Onyxia](https://datalab.sspcloud.fr) + ### Hot reload -By default, in order to see your changes you will have to wait for -`yarn build` to complete which can takes sevrall minute. - +Rebuild the theme each time you make a change to see the result is not practical. If you want to test your login screens outside of Keycloak, in [storybook](https://storybook.js.org/) for example you can use `kcContextMocks`. @@ -147,7 +183,6 @@ import { } from "keycloakify"; reactDom.render( - kcContext !== undefined ?