Important readme update
This commit is contained in:
Joseph Garrone
parent
46ec832767
commit
044ec1a2da
185
README.md
185
README.md
@ -2,7 +2,7 @@
|
||||
<img src="https://user-images.githubusercontent.com/6702424/109387840-eba11f80-7903-11eb-9050-db1dad883f78.png">
|
||||
</p>
|
||||
<p align="center">
|
||||
<i>🔏 Customize key cloak's pages as if they were part of your App 🔏</i>
|
||||
<i>🔏 Build Keycloak theme with React 🔏</i>
|
||||
<br>
|
||||
<br>
|
||||
<img src="https://github.com/garronej/keycloakify/workflows/ci/badge.svg?branch=develop">
|
||||
@ -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.
|
||||
|
||||
<p align="center">
|
||||
<i>Without keycloakify:</i><br>
|
||||
<i>Without keycloakify, users suffers from a harsh context switch, no fronted form pre-validation</i><br>
|
||||
<img src="https://user-images.githubusercontent.com/6702424/108838381-dbbbcf80-75d3-11eb-8ae8-db41563ef9db.gif">
|
||||
</p>
|
||||
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 🍸
|
||||
|
||||
<p align="center">
|
||||
<i>With keycloakify:</i><br>
|
||||
<i> <a href="https://datalab.sspcloud.fr">With keycloakify:</a> </i>
|
||||
<br>
|
||||
<img src="https://github.com/InseeFrLab/keycloakify/releases/download/v0.3.8/keycloakify_after.gif">
|
||||
</p>
|
||||
|
||||
**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 "./<wherever>/App";
|
||||
import {
|
||||
KcApp,
|
||||
defaultKcProps,
|
||||
kcContext
|
||||
} from "keycloakify";
|
||||
import { css } from "tss-react";
|
||||
|
||||
const myClassName = css({ "color": "red" });
|
||||
|
||||
reactDom.render(
|
||||
<KcApp
|
||||
kcContext={kcContext}
|
||||
{...{
|
||||
...defaultKcProps,
|
||||
"kcHeaderWrapperClass": myClassName
|
||||
}}
|
||||
/>
|
||||
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 "./<wherever>/App";
|
||||
import {
|
||||
KcApp,
|
||||
@ -118,24 +148,30 @@ reactDom.render(
|
||||
);
|
||||
```
|
||||
|
||||
<i>result:</i>
|
||||
|
||||
<p align="center">
|
||||
<img src="https://user-images.githubusercontent.com/6702424/110261408-688d6280-7fb0-11eb-9822-7003d268b459.png">
|
||||
<i>result:</i>
|
||||
<img src="https://user-images.githubusercontent.com/6702424/114326299-6892fc00-9b34-11eb-8d75-85696e55458f.png">
|
||||
</p>
|
||||
|
||||
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 [`<KcApp />`](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 [`<KcApp />`](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 ?
|
||||
<KcApp
|
||||
kcContext={kcContextMocks.kcLoginContext}
|
||||
{...defaultKcProps}
|
||||
@ -156,15 +191,28 @@ reactDom.render(
|
||||
);
|
||||
```
|
||||
|
||||
then `yarn start` ...
|
||||
Then `yarn start`, you will see your login page.
|
||||
|
||||
Checkout [this concrete example](https://github.com/garronej/keycloakify-demo-app/blob/main/src/index.tsx)
|
||||
|
||||
## Enable loading in a blink of an eye of login pages ⚡ (--external-assets)
|
||||
|
||||
*NOTE: keycloak-react-theming was renamed keycloakify since this video was recorded*
|
||||
[](https://youtu.be/xTz0Rj7i2v8)
|
||||
By default the theme generated is standalone. Meaning that when your users
|
||||
reach the login pages all scripts, images and stylesheet are downloaded from the Keycloak server.
|
||||
If you are specifically building a theme to integrate with an app or a website that allows users
|
||||
to first browse unauthenticated before logging in, you will get a significant
|
||||
performance boost if you jump through those hoops:
|
||||
|
||||
# Terms and conditions
|
||||
- Provide the url of your app in the `homepage` field of package.json. [ex](https://github.com/garronej/keycloakify-demo-app/blob/7847cc70ef374ab26a6cc7953461cf25603e9a6d/package.json#L2)
|
||||
- Build the theme using `npx build-keycloak-theme --external-assets` [ex](https://github.com/garronej/keycloakify-demo-app/blob/7847cc70ef374ab26a6cc7953461cf25603e9a6d/.github/workflows/ci.yaml#L21)
|
||||
- Enable [long-term assets caching](https://create-react-app.dev/docs/production-build/#static-file-caching) on the server hosting your app.
|
||||
- Make sure not to build your app and the keycloak theme separately
|
||||
and remember to update the Keycloak theme every time you update your app.
|
||||
- Be mindful that if your app is down your login pages are down as well.
|
||||
|
||||
Checkout a complete setup [here](https://github.com/garronej/keycloakify-demo-app#about-keycloakify)
|
||||
|
||||
# Support for Terms and conditions
|
||||
|
||||
[Many organizations have a requirement that when a new user logs in for the first time, they need to agree to the terms and conditions of the website.](https://www.keycloak.org/docs/4.8/server_admin/#terms-and-conditions).
|
||||
|
||||
@ -187,41 +235,41 @@ Tested with the following Keycloak versions:
|
||||
- [12.0.4](https://hub.docker.com/layers/jboss/keycloak/12.0.4/images/sha256-67e0c88e69bd0c7aef972c40bdeb558a974013a28b3668ca790ed63a04d70584?context=explore)
|
||||
|
||||
This tool will be maintained to stay compatible with Keycloak v11 and up, however, the default pages you will get
|
||||
(before you customize it) will always be the ones of the Keycloak v11.
|
||||
(before you customize it) will always be the ones of Keycloak v11.
|
||||
|
||||
This tools assumes you are bundling your app with Webpack (tested with 4.44.2) .
|
||||
This tool assumes you are bundling your app with Webpack (tested with 4.44.2) .
|
||||
It assumes there is a `build/` directory at the root of your react project directory containing a `index.html` file
|
||||
and a `build/static/` directory generated by webpack.
|
||||
|
||||
**All this is defaults with [`create-react-app`](https://create-react-app.dev)** (tested with 4.0.3=)
|
||||
|
||||
- For building the theme: `mvn` (Maven) must be installed
|
||||
- For development (testing the theme in a local container ): `rm`, `mkdir`, `wget`, `unzip` are assumed to be available
|
||||
and `docker` up and running.
|
||||
|
||||
NOTE: This build tool has only be tested on MacOS.
|
||||
**All this is defaults with [`create-react-app`](https://create-react-app.dev)** (tested with 4.0.3)
|
||||
|
||||
- For building the theme: `mvn` (Maven) must be installed (but you can build the theme in the CI)
|
||||
- For testing the theme in a local Keycloak container (which is not mandatory for development):
|
||||
`rm`, `mkdir`, `wget`, `unzip` are assumed to be available and `docker` up and running.
|
||||
# Limitations
|
||||
|
||||
## `process.env.PUBLIC_URL` not supported.
|
||||
|
||||
You won't be able to [import things from your public directory in your JavaScript code](https://create-react-app.dev/docs/using-the-public-folder/#adding-assets-outside-of-the-module-system). (This isn't recommended anyway).
|
||||
You won't be able to [import things from your public directory **in your JavaScript code**](https://create-react-app.dev/docs/using-the-public-folder/#adding-assets-outside-of-the-module-system).
|
||||
(This isn't recommended anyway).
|
||||
|
||||
## `@font-face` importing fonts from the `src/` dir
|
||||
|
||||
If you are building the theme with [--external-assets](#enable-loading-in-a-blink-of-a-eye-of-login-pages-)
|
||||
this limitation doesn't apply, you can import fonts however you see fit.
|
||||
|
||||
### Example of setup that **won't** work
|
||||
|
||||
- We have a `fonts/` directory in `src/`
|
||||
- We import the font like this [`src: url("/fonts/my-font.woff2") format("woff2");`(https://github.com/garronej/keycloakify-demo-app/blob/07d54a3012ef354ee12b1374c6f7ad1cb125d56b/src/fonts.scss#L4) in a `.scss` a file.
|
||||
|
||||
### Workarounds
|
||||
### Possible workarounds
|
||||
|
||||
If it is possible, use Google Fonts or any other font provider.
|
||||
|
||||
If you want to host your font recommended approach is to move your fonts into the `public`
|
||||
- Use [`--external-assets`](#enable-loading-in-a-blink-of-a-eye-of-login-pages-).
|
||||
- If it is possible, use Google Fonts or any other font provider.
|
||||
- If you want to host your font recommended approach is to move your fonts into the `public`
|
||||
directory and to place your `@font-face` statements in the `public/index.html`.
|
||||
Example [here](https://github.com/InseeFrLab/onyxia-ui/blob/0e3a04610cfe872ca71dad59e05ced8f785dee4b/public/index.html#L6-L51).
|
||||
|
||||
You can also [use your explicit url](https://github.com/garronej/keycloakify-demo-app/blob/2de8a9eb6f5de9c94f9cd3991faad0377e63268c/src/fonts.scss#L16) but don't forget [`Access-Control-Allow-Origin`](https://github.com/garronej/keycloakify-demo-app/blob/2de8a9eb6f5de9c94f9cd3991faad0377e63268c/nginx.conf#L17-L19).
|
||||
- You can also [use non relative url](https://github.com/garronej/keycloakify-demo-app/blob/2de8a9eb6f5de9c94f9cd3991faad0377e63268c/src/fonts.scss#L16) but don't forget [`Access-Control-Allow-Origin`](https://github.com/garronej/keycloakify-demo-app/blob/2de8a9eb6f5de9c94f9cd3991faad0377e63268c/nginx.conf#L17-L19).
|
||||
|
||||
# Implement context persistence (optional)
|
||||
|
||||
@ -281,12 +329,3 @@ keycloakInstance.init({
|
||||
If you really want to go the extra miles and avoid having the white
|
||||
flash of the blank html before the js bundle have been evaluated
|
||||
[here is a snippet](https://github.com/InseeFrLab/onyxia-ui/blob/a77eb502870cfe6878edd0d956c646d28746d053/public/index.html#L5-L54) that you can place in your `public/index.html` if you are using `powerhooks/useGlobalState`.
|
||||
|
||||
# API Reference
|
||||
|
||||
## The build tool
|
||||
|
||||
Part of the lib that runs with node, at build time.
|
||||
|
||||
- `npx build-keycloak-theme`: Builds the theme, the CWD is assumed to be the root of your react project.
|
||||
- `npx download-sample-keycloak-themes`: Downloads the keycloak default themes (for development purposes)
|
||||
Loading…
x
Reference in New Issue
Block a user