keycloak-theme-react/README.md

🚀 A starter/demo project for Keycloakify v7 🚀



Authenticated React SPA

Introduction

This repo constitutes an easily reusable setup for a standalone Keycloak theme project OR for a SPA React App that generates a Keycloak theme that goes along with it.
If you are only looking to create a theme (and not a theme + an App) there are a lot of things that you can remove from this starter: Please read this section of the README.

❗️ WARNING ❗️: Don't waste time trying to setup Keycloakify in a Vite project.
Currently Keycloakify only works with Webpack. If you want Vite support join the conversation.

Quick start

yarn
yarn build-keycloak-theme # Build the theme one time (some assets will be copied to 
              # public/keycloak_static, they are needed to dev your page outside of Keycloak)
yarn start # See the Hello World app
# Uncomment line 15 of src/keycloak-theme/login/kcContext, reload https://localhost:3000
# You can now develop your Login pages. (Don't forget to comment it back when you're done)

# Think your theme is ready? Run
yarn build-keycloak-theme
# Read the instruction printed on the console to see how to test
# your theme on a real Keycloak instance.

# For customizing other pages at the component level
npx eject-keycloak-page # Then select the page you want

# For initializing your email theme
npx initialize-email-theme

# For downloading the default theme
npx download-builtin-keycloak-theme

The CI workflow

• You need to manually allow GitHub Action to push on your repositroy. For this reason the initial setup will fail. You need to enabled permission and re-run failed job: see video.
• This CI is configured to publish the app on GitHub Pages and on DockerHub (as a Ngnix based docker image). In practice you probably want one or the other but not both... or neither if you are just building a theme (and not a theme + an app).
  If you want to enable the CI to publish on DockerHub on your behalf go to repository Settings tab, then Secrets you will need to add two new secrets: DOCKERHUB_TOKEN, you Dockerhub authorization token.
  DOCKERHUB_USERNAME, Your Dockerhub username. We deploy the demo app at starter.keycloakify.dev using GitHub page on the branch gh-pages (you have to enable it).
  To configure your own domain name please refer to this documentation.
• To release don't create a tag manually, the CI do it for you. Just update the package.json's version field and push.
• The .jar files that bundle the Keycloak theme will be attached as an asset with every GitHub release. Example. The permalink to download the latest version is: https://github.com/USER/PROJECT/releases/latest/download/keycloak-theme.jar. For this demo repo it's here
• The CI publishes the app docker image on DockerHub. <org>/<repo>:main for each commit on main, <org>/<repo>:<feature-branch-name> for each pull-request on main and when releasing a new version: <org>/<repo>:latest and <org>/<repo>:X.Y.Z See on DockerHub

If you want an example of an app that put that setup in production checkout onyxia-ui: the repo, the login, the app.

Standalone vs --external-assets

The CI creates two jars

• keycloak-theme.jar: Generated with npx keycloakify --external-assets, the assets, located static/**/*, like for example static/js/main.<hash>.js will be downloaded from https://starter.keycloakify.dev/static/js/main.<hash>.js (starter.keycloakify.dev is specified in the package.json.
• standalone-keycloak-theme.jar: Generated with npx keycloakify, this theme is fully standalone, all assets will be served by the Keycloak server, for example static/js/main.<hash>.js will be downloaded from an url like http://<your keycloak url>/resources/xxxx/login/keycloakify-starter/build/static/js/main.<hash>.js.

More info on the --external-assets build option here.

Docker

docker build -f Dockerfile -t codegouvfr/keycloakify-starter:test .
#OR (to reproduce how the image is built in the ci workflow):
yarn && yarn build && tar -cvf build.tar ./build && docker build -f Dockerfile.ci -t codegouvfr/keycloakify-starter:test . && rm build.tar

docker run -it -dp 8083:80 codegouvfr/keycloakify-starter:test

Standalone keycloak theme

If you are only looking to create a keycloak theme, you can run theses few commands after clicking to refactor the template and remove unnecessary files.

rm -r src/App
rm src/keycloak-theme/login/valuesTransferredOverUrl.ts
mv src/keycloak-theme/* src/
rm -r src/keycloak-theme

cat << EOF > src/index.tsx
import { createRoot } from "react-dom/client";
import { StrictMode, lazy, Suspense } from "react";
import { kcContext as kcLoginThemeContext } from "./login/kcContext";
import { kcContext as kcAccountThemeContext } from "./account/kcContext";

const KcLoginThemeApp = lazy(() => import("./login/KcApp"));
const KcAccountThemeApp = lazy(() => import("./account/KcApp"));

createRoot(document.getElementById("root")!).render(
    <StrictMode>
        <Suspense>
            {(()=>{

                if( kcLoginThemeContext !== undefined ){
                    return <KcLoginThemeApp kcContext={kcLoginThemeContext} />;
                }

                if( kcAccountThemeContext !== undefined ){
                    return <KcAccountThemeApp kcContext={kcAccountThemeContext} />;
                }

                throw new Error(
                  "This app is a Keycloak theme" +
                  "It isn't meant to be deployed outside of Keycloak"
                );

            })()}
        </Suspense>
    </StrictMode>
);

EOF

rm .dockerignore Dockerfile Dockerfile.ci nginx.conf

cat << EOF > .github/workflows/ci.yaml
name: ci
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:

  build:
    runs-on: ubuntu-latest
    if: github.event.head_commit.author.name != 'actions'
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2.1.3
      with:
        node-version: '16'
    - uses: bahmutov/npm-install@v1
    - run: yarn build
    - run: npx keycloakify
    - uses: actions/upload-artifact@v2
      with:
        name: standalone_keycloak_theme
        path: build_keycloak/target/*keycloak-theme*.jar
    - uses: actions/upload-artifact@v2
      with:
        name: build
        path: build

  check_if_version_upgraded:
    name: Check if version upgrade
    runs-on: ubuntu-latest
    needs: build
    outputs:
      from_version: \${{ steps.step1.outputs.from_version }}
      to_version: \${{ steps.step1.outputs.to_version }}
      is_upgraded_version: \${{ steps.step1.outputs.is_upgraded_version }}
    steps:
    - uses: garronej/ts-ci@v1.1.7
      id: step1
      with: 
        action_name: is_package_json_version_upgraded

  create_github_release:
    runs-on: ubuntu-latest
    needs: 
      - check_if_version_upgraded
    # We create a release only if the version have been upgraded and we are on a default branch
    # PR on the default branch can release beta but not real release
    if: |
      needs.check_if_version_upgraded.outputs.is_upgraded_version == 'true' &&
      (
        github.event_name == 'push' ||
        needs.check_if_version_upgraded.outputs.is_release_beta == 'true'
      )
    steps:
    - run: mkdir jars
    - uses: actions/download-artifact@v2
      with:
        name: standalone_keycloak_theme
    - run: mv *keycloak-theme*.jar jars/standalone-keycloak-theme.jar
    - uses: softprops/action-gh-release@v1
      with:
        name: Release v\${{ needs.check_if_version_upgraded.outputs.to_version }}
        tag_name: v\${{ needs.check_if_version_upgraded.outputs.to_version }}
        target_commitish: \${{ github.head_ref || github.ref }}
        generate_release_notes: true
        files: |
          jars/standalone-keycloak-theme.jar
        draft: false
        prerelease: \${{ needs.check_if_version_upgraded.outputs.is_release_beta == 'true' }}
      env:
        GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}

You can also remove jwt-decode, keycloak-js, powerhooks and tsafe from your dependencies.