home..

BookStack Keycloak으로 연동하기

July 2023 (497 Words, 3 Minutes)

kubernetes msa mont-kim aws eks bookstack keycloak oidc openid openidconnect

Bookstack Keycloak 연동하기

이번에는 배포했던 BookStack의 로그인을 Keycloak으로 연동하는 과정을 다룬 문서입니다.

KeyCloak 설정

Untitled

작업을 진행할 Realm 안에서 BookStack에 관련된 권한을 부여하는 BookStack Client를 생성합니다.

Client ID	bookstack
Client Protocol	openid-connect
Access Type	confidential
Valid Redirect URIs	https://bookstack.mont-kim.com/*
Base URL	https://bookstack.mont-kim.com/

해당 정보로 Client를 등록하고나면 Credential 탭에 “Client and Secret” 항목으로 Secret이 생성됩니다.

해당 Secret 토큰으로 다음 과정에서 bookstack 서비스에 등록을 진행합니다

편의성 생성된 Secret 토큰은 @@@@@ 로 부르겠습니다.

ENV

기존에 Bookstack을 Helm으로 배포할때, env를 별도로 선언해 custom value로 선언해 설치를 진행했었습니다.

env를 선언할 때 다음과 같이 선언을 했었습니다. 하지만 추가적인 데이터들을 추가하기위해 구조를 조금 변경했습니다.

env:
  DB_HOST: bookstack-mariadb
  DB_USER: bookstack
  DB_PASS: bookstack
  DB_DATABASE: bookstack
  APP_URL: https://bookstack.mont-kim.com

해당 형식을 key/value 형태로 변환하면 다음과 같은 설정이 됩니다.

env:
  - name: DB_HOST
    value: bookstack-mariadb
  - name: DB_USER
    value: bookstack
  - name: DB_PASS
    value: bookstack
  - name: DB_DATABASE
    value: bookstack
  - name: APP_URL
    value: https://bookstack.mont-kim.com

이제 여기에 keycloak관련 설정을 추가해주려 합니다.

Keycloak에서 제공하는 SAML 형태로 연동도 가능하고, OpenID Connect로도 연동이 가능합니다.

OpenID Connect Authentication

그중에서 OpenID Connect 를 기준으로 문서를 작성해보았습니다.

env:
  - name: DB_HOST
    value: bookstack-mariadb
  - name: DB_USER
    value: bookstack
  - name: DB_PASS
    value: bookstack
  - name: DB_DATABASE
    value: bookstack
  - name: APP_URL
    value: https://bookstack.mont-kim.com
  - name: AUTH_METHOD
    value: oidc
  - name: AUTH_AUTO_INITIATE
    value: "true"
  - name: OIDC_NAME
    value: Keycloak
  - name: OIDC_DISPLAY_NAME_CLAIMS
    value: name
  - name: OIDC_CLIENT_ID
    value: bookstack
  - name: OIDC_CLIENT_SECRET
    valueFrom:
      secretKeyRef:
        name: bookstack-oidc
        key: OIDC_CLIENT_SECRET
  - name: OIDC_ISSUER
    value: https://keycloak.mont-kim.com/realms/mont
  - name: OIDC_ISSUER_DISCOVER
    value: "true"

여기서 OIDC_CLIENT_SECRET은 keycloak에서 생성한 bookstack client에 대한 secret 토큰입니다.

다만 이 토큰을 명시적으로 helm의 value 파일에 명시하기보다 별도로 secret으로 생성을 해 해당값을 일도록 했습니다.

Secret

bookstack 배포를 포함한, 다른 addon들을 설치 할 때도 민감하게 관리 해야 할 정보는 helm의 value 파일에 직접 명시하는 것이 아닌 별도의 secret 파일을 생성해 관리하는 경우가 일반적입니다.

secret은 namespace별로 구분되기 때문에 bookstack을 배포한 “bookstack” namespace안에서 secret을 새로 생성해줍니다.

다만, secret은 base64로 인코딩한 데이터를 사용하기 때문에, 위에서 발급한 토큰 @@@@@를 base64로 인코딩해야 합니다

echo -n '@@@@@' | base64

위 결과를 편의상 #####으로 하겠습니다.

생성할 secret.yaml파일은 다음과 같습니다.

apiVersion: v1
kind: Secret
metadata:
  name: bookstack-oidc
  namespace: bookstack
type: Opaque
data:
  OIDC_CLIENT_SECRET: ######

위의 ENV에서 해당 secret을 사용 할 수 있게 설정해둔 코드를 보겠습니다

  - name: OIDC_CLIENT_SECRET
    valueFrom:
      secretKeyRef:
        name: bookstack-oidc
        key: OIDC_CLIENT_SECRET

bookstack-oidc라는 secret에서 OIDC_CLIENT_SECRET 값을 읽어 사용하겠다는 코드입니다.

값을 디코딩 하여 @@@@@의 토큰을 받아와 해당 keycloak 주소로 secret을 보냅니다.

배포

해당 secret을 생성하고, 수정한 ENV 값을 갖는 value 파일로 다시 bookstack을 helm 배포합니다.

Untitled

이제 로그인창에 Keycloak 소셜 계정으로 로그인 메뉴가 떴습니다.

로그인 버튼을 누르면 Keycloak 로그인 창이뜨고, 해당 주소에서 로그인을 하게되면 서비스에 접속이 가능해집니다.

이상으로 Bookstack - Keycloak 연동방법을 알아보았습니다.