[Keycloak] keycloakify로 테마 커스텀 - 초기 설정

 

 

 

버전 정보

• keycloak: v20.0.3
• keycloakify: v6

 

 

로그인 테마 커스텀

 

사실 keycloak의 테마는 이쁘지 않다...

꾸민 느낌 내려고 배경에 그라데이션 도형을 넣은게 더 열 받는다.

 

이를 극복하기위해 직접 freeMaker. 즉, .ftl 확장자 파일을 수정해야 한다.
freeMarker가 어떤 코드인지 확인하기 위해 keycloak 깃허브에서 .ftl 확장자를 찾아보면 아래와 같이 되어있다.

짧은 코드라 읽히긴 하지만, 이 코드 양이 많아지거나 커스텀 로직을 추가해야 한다고 생각하면 쉽지 않다.

 

저 위의 빨간 에러는 뭔데... jsp 하던 때로 돌아간 것 같다.

 

이를 위해 Joseph Garrone라는 개발자분이 React로도 개발이 가능하도록 (React로 개발 후에 빌드하면 ftl파일로 변화된다) keycloakify라는 라이브러리를 만들었다.

 

Keycloakify 설치

 

keycloakify-advanced-starter(https://github.com/garronej/keycloakify-advanced-starter) 에서 프로젝트를 clone 한 후에 Quick Start에 쓰여있는 순서에 맞춰서 작업을 진행한다.

$ yarn
$ yarn keycloak # 빌드를 한번 한다. (몇몇 assets 들은 public/keycloak_static 폴더에 복사되며
               # 이는 keycloak 외의 커스텀 페이지를 개발하기 위해 필요하다.)
$ yarn start # Hello World 페이지가 나온다.

# src/KcApp/kcContext.ts 파일의 15번째 줄의 주석을 제거하고, https://localhost:3000에 접속하면
# 이제 로그인 페이지를 개발할 수 있다.

# 테마를 완성하고 $yarn keyclock를 하여 표시되는 콘솔 문구들을 통해 테스트 하면된다.
$ yarn keycloak

src/KcApp 폴더에 있는 kcContext.ts 파일의 15번째 라인의 주석을 해제하자

import { getKcContext } from "keycloakify/lib/getKcContext";

export const { kcContext } = getKcContext<
    // NOTE: A 'keycloakify' field must be added 
    // in the package.json to generate theses pages
    // https://docs.keycloakify.dev/build-options#keycloakify.extrapages
    | { pageId: "my-extra-page-1.ftl"; } 
    | { pageId: "my-extra-page-2.ftl"; someCustomValue: string; }
    // NOTE: register.ftl is deprecated in favor of register-user-profile.ftl
    // but let's say we use it anyway and have this plugin enabled: https://github.com/micedre/keycloak-mail-whitelisting
    // keycloak-mail-whitelisting define the non standard ftl global authorizedMailDomains, we declare it here.
    | { pageId: "register.ftl"; authorizedMailDomains: string[]; }
>({
    // Uncomment to test the login page for development.
    "mockPageId": "login.ftl",     // <=============== 이 부분의 주석을 제거한다.
    "mockData": [
        {
            "pageId": "login.ftl",
            "locale": {
                //When we test the login page we do it in french
                "currentLanguageTag": "fr", 
            },

$ yarn start 를 실행하면 로그인 페이지가 잘 나온다. 이제 $ yarn keycloak 을 하면 많은 콘솔이 출력되는데 하나씩 뜯어보자.

🔏 Building the keycloak theme...⌚
🫶 Let keycloakify do its thang

# 생성된 테마는 도커이미지의 컨테이너의 "/opt/keycloak/providers" 폴더에 위치된다.
✅ Your keycloak theme has been generated and bundled into ./build_keycloak/target/keycloakify-advanced-starter-keycloak-theme-1.0.8.jar 🚀
It is to be placed in "/opt/keycloak/providers" in the container running a quay.io/keycloak/keycloak Docker image.

...
# 테스트를 하기위해서 keycloak docker를 띄우자. 아래 커맨트를 이용하면 20.0.1 keycloak을 설치할 수 있다.
To test your theme locally you can spin up a Keycloak 20.0.1 container image with the theme pre loaded by running:

👉 $ ./build_keycloak/start_keycloak_testing_container.sh 👈
# 버전을 다르게 하고 싶으면 start_keycloak_testing_container.sh 파일을 수정하면 된다.
Test with different Keycloak versions by editing the .sh file. see available versions here: https://quay.io/repository/keycloak/keycloak?tab=tags

# 컨테이너가 올라가면 아래 순서대로 적용한다.
Once your container is up and running: 
- Log into the admin console 👉 http://localhost:8080/admin username: admin, password: admin 👈
- Create a realm named "myrealm"
- Create a client with ID: "myclient", "Root URL": "https://www.keycloak.org/app/" and "Valid redirect URIs": "https://www.keycloak.org/app/*"
- Select Login Theme: keycloakify-advanced-starter (don't forget to save at the bottom of the page)
- Go to 👉 https://www.keycloak.org/app/ 👈 Click "Save" then "Sign in". You should see your login page


# 이 프로세스를 시연한 데모 영상이다. 
Video demoing this process: https://youtu.be/N3wlBoH4hKg

그럼 순서대로 작업해보자.
우선 현재 기준 최신버전인 20.0.3으로 바꾸려고 한다.

$ vim ./build_keycloak/start_keycloak_testing_container.sh 를 통해 버전만 변경해 준다.

 

 

이제 $ ./build_keycloak/start_keycloak_testing_container.sh 를 하면 20.0.3 버전으로 keycloak-testing-container 컨테이너 이름을 가진 keycloak 도커가 실행된다.
이제 아래 순서대로 진행하면 된다.

1. http://localhost:8080/admin에 접속
2. 아이디: admin, 비밀번호: admin로 로그인
3. 'myrealm'라는 이름의 realm 생성
4. 'myrealm'내에서 'myclient'라는 이름의 client 생성
5. "Root URL": "https://www.keycloak.org/app/" 로 설정 "Valid redirect URIs": "https://www.keycloak.org/app/*" 로 설정
6. Login Theme을 keycloakify-advanced-starter로 설정
7. save 버튼 꼭 누르기!

 

 

 

 

• 여기서 Root URL은 이후 상대 경로들을 간편하게 작성하기 위해 default로 정의한 경로다.
• 예를 들어 위의 경우 Valid redirect URIs, Admin URL를 설정할 때 앞에 'https://www.keycloak.org/app/'을 따로 적어주지 않아도 된다.
• Valid redirect URIs는 로그인 성공 후에 redirect 되는 URI를 제한한다.
• 위의 뜻을 해석하자면 https://www.keycloak.org/app/ 하위 주소(ex: https://www.keycloak.org/app/a, https://www.keycloak.org/app/b 등)가 아닌 다른 주소로 redirect 된다면 에러가 발생한다는 뜻이다.
• Invalid parameter: redirect_uri 에러가 발생한다.

위와 같이 저장 후에 https://www.keycloak.org/app 에 접속하여 그대로 'save' 버튼을 누른 후에 'Sign in' 버튼을 누르면 아래와 같이 커스텀 된(?) 화면이 나온다.

 

커스텀 테마 덕분에 로그인 화면이 화사해졌다.

 

아이디: admin, 비밀번호: admin로 로그인을 시도해보자.
안된다. admin은 myRealm내의 가입된 사용자가 아니기 때문이다.

아래 포스트를 따라서 myRealm에 사용자를 생성하자. (18버전이라 화면이 살짝 다르지만 그대로 따라 하면 된다.)

[Keycloak] Realm, Client, User 생성 (Quarkus, 17버전 이후)

이제 로그인이 가능하다!

 

반년 전만 해도 이런 식으로 테스트를 할 수 없었다. (keycloakify 라이브러리의 docs 페이지도 없었다.)
지금 이렇게 실제 적용하는 것과 비슷하게 테스트할 수 있도록 만들어주신 걸 보니, 어떻게 하면 사용자들이 쉽게 이해할 수 있을지 고민한 흔적들이 많이 보인다.
대단한 개발자라고 생각한다. 나도 열심히 실력을 키워서 이번 생에 이런 프로젝트 하나 이상은 꼭 만들어야지.

기초 작업은 끝났다! 다음 포스팅부터 본격적으로 로그인, 회원가입 화면들을 만들예정이다.