홈랩 서비스가 늘어나면서 로그인도 여러 곳에 흩어졌습니다. 일부 서비스는 이미 authentik과 연결해 사용하고 있었지만, WordPress나 Gitea처럼 별도 계정으로 로그인하는 서비스도 남아 있었습니다. 이번에는 Gitea, Open WebUI, Homarr, PowerDNS-Admin, WordPress의 OIDC 연결을 정리했습니다.
조건은 기존 계정과 설정을 유지하는 것이었습니다. 특히 GitOps 저장소를 제공하는 Gitea는 authentik 장애 때도 독립적으로 로그인할 수 있어야 했습니다. 2026년 10월 9일에 WordPress의 issuer 오류와 Homarr 계정 연결까지 마무리하고 GitOps 반영을 확인했습니다.
앱이 직접 처리하는 SSO부터 선택하기
먼저 현재 배포한 이미지와 코드에서 지원하는 연결 방식을 확인했습니다. OIDC를 앱이 직접 처리하면 앱의 계정과 외부 인증 정보를 연결할 수 있습니다. 인증 프록시를 앞에 두는 방식도 있지만, 그 경우 앱 자체의 로그인과 어떤 관계가 되는지 서비스마다 따로 확인해야 합니다.
| 서비스 | 이번 연결 방식 |
|---|---|
| Gitea | 내장 OIDC 인증 소스 추가 |
| Open WebUI | 내장 OIDC 사용 |
| Homarr | 배포 버전의 OIDC 기능과 기존 계정 연결 |
| PowerDNS-Admin | 내장 OIDC 사용 |
| WordPress | OpenID Connect Generic Client와 로컬 설정 코드 |
앱마다 provider와 client를 분리하고, redirect URI와 scope를 맞췄습니다. 기능이 있다는 사실과 현재 배포한 버전에서 설정이 어떻게 작동하는지는 따로 확인해야 했습니다.
앱에서 OIDC 로그인 시작
→ authentik에서 사용자 인증
→ 앱의 callback으로 복귀
→ 외부 식별자를 앱의 기존 계정과 연결
→ 기존 데이터와 권한으로 사용기존 계정에 연결하기
SSO를 붙인 뒤 새 계정이 생기면 기존 데이터가 남아 있어도 사용자는 다른 계정으로 들어가게 됩니다. 관리자 권한, 대시보드 설정, 앱 내부 사용자 ID도 달라질 수 있습니다. 그래서 새 계정 자동 생성보다 기존 계정과 외부 식별자를 연결하는 데 초점을 맞췄습니다.
WordPress에는 기존 관리자 한 명을 그대로 유지했습니다. OpenID Connect Generic Client를 설치한 뒤, 지정한 authentik 사용자 식별자를 그 관리자에게 연결하는 설정 코드를 사용했습니다. 이메일이 일치하는 사용자를 무조건 관리자에게 연결하거나, 미등록 사용자를 자동 생성하는 설정은 사용하지 않았습니다.
이 부분은 제 단일 관리자 블로그에 맞춘 연결입니다. 여러 사용자가 로그인하는 사이트라면 사용자별 식별자와 역할을 별도로 설계해야 합니다. 실제 연결에서는 기존 관리자 ID와 관리자 수가 유지됐는지도 확인했습니다.
관리자 로그인을 바꾸는 것과 사이트 전체의 공개 읽기를 제한하는 것은 별도 설정입니다. 블로그의 글은 계속 공개로 읽을 수 있게 두었습니다. 사용자 연결·신규 생성·전체 사이트 접근 제한 옵션을 한꺼번에 켜는 방식은 사용하지 않았습니다.
Homarr도 기존 계정과 대시보드 설정을 유지하면서 OIDC 계정을 연결했습니다. 연결 대상을 먼저 확인하고 적용한 뒤, 사용하던 세 도메인에서 authentik으로 이동하는 동작을 확인했습니다.
WordPress issuer 오류 확인하기
WordPress에서는 인증 후 돌아왔는데 토큰 발급자 주소가 맞지 않는 오류가 발생했습니다. 처음에는 캐시를 의심했지만, 실제 수정 대상은 OIDC의 issuer 설정이었습니다.
OIDC의 iss는 토큰을 발급한 주체를 나타냅니다. authorization endpoint와 token endpoint가 맞아도 앱이 기대하는 issuer와 토큰의 issuer가 다르면 검증에 실패할 수 있습니다. 이 설정에서 빠져 있던 WordPress provider의 issuer를 명시적으로 맞췄습니다.
아래는 주소를 예시 도메인으로 바꾼 형태입니다. 해당 provider의 discovery 문서에 표시되는 issuer와 일치해야 합니다.
Discovery URL
https://sso.example.com/application/o/wordpress/.well-known/openid-configuration
이번 설정에서 맞춘 issuer
https://sso.example.com/application/o/wordpress/issuer 설정을 수정한 뒤 기존 관리자 로그인을 확인했고, 최종 GitOps 설정에 반영했습니다. authentik의 WordPress 연동 안내도 같은 플러그인을 사용하며 discovery 문서로 설정을 불러오는 방법을 설명합니다. 실제 redirect URI는 WordPress 설치 경로와 플러그인에 표시되는 값을 기준으로 맞춰야 합니다.
같은 오류를 만나면 discovery 문서의 issuer, ID token의 iss, 앱이 기대하는 issuer를 비교하면 됩니다. callback은 scheme·host·path와 필요한 query까지 플러그인이 안내하는 주소에 맞춰야 합니다. authentik의 issuer mode 설명처럼 provider마다 issuer가 달라질 수 있어 서버 루트 주소만 보고 값을 추측하지 않는 편이 좋습니다.
Gitea의 독립 로그인 유지하기
Gitea는 기존 ID·비밀번호 로그인을 유지하고 authentik 로그인 버튼을 추가하는 방식으로 연결했습니다. OIDC로 자동 이동하도록 강제하지 않았으며, GitOps가 저장소를 읽는 기존 인증도 유지했습니다.
새 클러스터를 복구할 때 Gitea에 접속해 설정을 가져와야 하는데, Gitea 로그인에 authentik부터 필요하면 인증 서비스의 설정을 복구하는 과정이 꼬일 수 있습니다. 그래서 Gitea는 authentik이 준비되기 전에도 접근할 수 있는 경로를 남겼습니다.
반면 WordPress와 Homarr는 연결을 확인한 뒤 자체 비밀번호 로그인을 비활성화했습니다. 모든 서비스를 같은 로그인 정책으로 바꾸기보다, 저장소처럼 복구에 필요한 서비스의 역할을 따로 고려했습니다.
Fleet의 배포 의존성도 함께 정리하기
로그인 연결과 함께 Fleet의 bundle 의존성도 확인했습니다. 스토리지와 CRD, DB처럼 후속 리소스 생성에 꼭 필요한 기반은 Ready까지 기다리도록 했습니다. authentik과 웹 앱의 관계에서는 매니페스트가 적용된 후 진행하되, 모든 앱 배포가 authentik Pod의 Ready를 기다리도록 강제하지는 않았습니다.
당시 사용하는 Fleet 0.16.2에서는 bundle 간 순서를 숫자 우선순위 annotation으로 정하는 방법이 확인되지 않았습니다. dependsOn과 acceptedStates로 필요한 상태를 구분했습니다. 설정 구조는 Fleet의 fleet.yaml 설명에서 확인할 수 있습니다.
스토리지·CRD·DB
→ 필요한 기반이 Ready인지 확인
→ authentik 리소스 적용
→ 웹 앱 리소스 적용
Gitea
→ authentik이 준비되기 전에도 기존 로그인 가능이렇게 해도 authentik이 준비되기 전에는 앱의 SSO가 작동하지 않습니다. 차이는 앱의 배포 자체와 외부 인증의 준비 상태를 하나의 대기 조건으로 묶지 않는다는 점입니다.
설정 적용과 로그인 결과를 따로 확인하기
OIDC client secret은 앱별 Secret으로 제공하고, Git에는 SealedSecret을 반영했습니다. WordPress의 관리자·공개용 배포에도 같은 인증 설정을 제공했습니다. 설정을 적용한 후에는 인증 진입 경로와 기존 계정 연결을 점검했습니다.
중간 점검에서 Fleet가 72/72 Ready여도 WordPress의 issuer 오류나 Homarr의 계정 연결은 남아 있었습니다. 배포 도구의 Ready는 실제 사용자 로그인이 완료됐다는 의미가 아니었습니다. 그 문제들을 해결한 뒤 최종 설정을 push했고, WordPress와 Homarr의 연결을 마무리했습니다.
| 확인 항목 | 당시 기록으로 확인한 범위 |
|---|---|
| 다섯 앱의 OIDC 설정 | provider·client와 앱 설정 적용, 기존 계정 연결 설정 |
| WordPress | 지정 subject를 기존 관리자에 연결, 관리자 1명 유지, issuer 수정 후 관리자 로그인 확인 |
| Homarr | 기존 계정·대시보드 보존, 사용하던 세 도메인의 authentik 연결 확인 |
| Gitea | authentik 로그인 추가, 독립 ID·비밀번호 로그인 및 GitOps 인증 유지 |
| 최종 배포 상태 | 설정 push 후 Fleet 72/72 Ready |
| 전체 앱의 로그인·권한·로그아웃 | 모두 완료했다고 판단할 검증 기록은 확보하지 않음 |
중간 왕복 검사에는 authentik의 인증 입력 단계에서 멈춘 결과와 Open WebUI의 404 결과도 있습니다. 이를 다섯 앱 전체의 로그인 성공 근거로 사용하지 않았습니다. 이 작업의 완료 범위는 다섯 앱의 SSO 설정 적용과 기존 계정 연결, WordPress의 확인된 관리자 로그인 및 issuer 수정, Homarr의 후속 계정 설정입니다. 전체 앱에서 실제 로그인 후 권한과 로그아웃·계정 비활성화까지 확인한 시험과는 구분합니다.
이번 통합에서 챙긴 것은 로그인 버튼 수를 줄이는 일뿐 아니라 기존 사용자 ID, 관리자 권한, 앱 설정, 그리고 GitOps 복구 경로였습니다. 인증을 한곳으로 모을수록 그 인증 서비스가 준비되지 않았을 때 어떻게 복구할지도 같이 생각하게 됩니다.
답글 남기기