Keycloak이란? 로그인과 권한을 한 곳에서 관리하는 방법

서비스를 만들다 보면 “로그인”과 “권한” 문제가 꼭 생긴다.

로그인 화면과 비밀번호 정책
계정 잠금, 비밀번호 재설정 같은 사용자 관리
“누가 어떤 기능을 쓸 수 있는지” 권한 관리
여러 서비스에서 한 번만 로그인하는 기능(SSO, Single Sign-On)
추가 인증을 요구하는 보안 기능(MFA, Multi-Factor Authentication)
감사 로그 같은 보안 기록

이걸 서비스마다 직접 만들 수도 있지만, 시간도 많이 들고 실수하면 보안 문제가 생길 수 있다.

Keycloak은 이런 로그인과 권한 기능을 한 곳에서 처리해주는 서버다.
이런 범주의 도구를 보통 IAM(Identity and Access Management, 계정 및 접근 권한 관리) 솔루션이라고 부른다.

각 서비스는 Keycloak에 로그인을 맡기고, Keycloak이 발급한 토큰(token, 로그인 성공을 증명하는 값) 으로 사용자를 확인한다.

1) Keycloak 한 문장 요약

Keycloak은 로그인 확인(인증, Authentication)과 권한 확인(인가, Authorization)을 중앙에서 처리하는 서버다.
그래서 각 서비스는 “로그인 만들기” 대신 “토큰 확인”에 집중하면 된다.

3) 전체 흐름을 Mermaid로 보기

sequenceDiagram
  autonumber
  participant U as User(사용자)
  participant S as Service(내 서비스)
  participant K as Keycloak(로그인 서버)
  participant API as API(보호된 기능)

  U->>S: 보호된 기능 요청
  S->>K: 로그인 페이지로 이동
  U->>K: 로그인(아이디/비밀번호, 필요하면 MFA(Multi-Factor Authentication))
  K-->>U: 로그인 성공 + 토큰(token, 로그인 증명 값)
  U->>S: 토큰을 포함해서 다시 요청
  S->>API: 요청 + 토큰 전달
  API->>API: 토큰 확인(유효한지, 권한이 있는지)
  API-->>S: 허용 또는 거부
  S-->>U: 결과 응답

그림은 “로그인할 때 무슨 일이 일어나는지”를 순서대로 보여준다.
사용자는 먼저 Keycloak에서 로그인을 하고, Keycloak은 로그인했다는 증명인 토큰(token) 을 발급한다.
그 다음부터는 서비스와 API가 이 토큰을 확인해서 “진짜 로그인한 사람인지”와 “이 기능을 써도 되는지”를 판단한다.

4) Keycloak 도입의 장점

4.1 구현과 보안 책임을 분리한다

로그인 화면, 비밀번호 정책, 계정 잠금, 비밀번호 재설정, 추가 인증(MFA, Multi-Factor Authentication) 같은 기능을 각 서비스에서 따로 만들 필요가 줄어든다.

4.2 한 번 로그인으로 여러 서비스를 쓸 수 있다

한 번 로그인하면 연결된 다른 서비스에서 재로그인이 줄어든다(SSO, Single Sign-On).

4.3 표준 프로토콜을 지원해서 연동이 쉽다

Keycloak은 OAuth 2.0, OpenID Connect(OIDC), SAML 같은 표준을 지원한다.
그래서 많은 웹/백엔드 프레임워크에서 제공하는 기존 라이브러리를 그대로 써서, 설정만으로 로그인과 토큰 검증을 연결할 수 있다.

4.4 사용자와 권한을 중앙에서 관리한다

관리 콘솔에서 사용자, 그룹, 역할(Role), 접근 정책을 한 곳에서 관리할 수 있다.

5) Keycloak 도입의 tradeoff (반드시 알고 가야 할 것들)

장점만 보고 도입하면 운영에서 예상보다 손이 많이 갈 수 있다.

5.1 운영 복잡도 증가

Keycloak은 라이브러리가 아니라 서버다.
배포, 모니터링, 업그레이드, 백업/복구, 장애 대응까지 운영 책임이 생긴다.

5.2 로그인 서버가 멈추면 서비스도 영향을 받는다

Keycloak을 로그인 관문으로 쓰면, Keycloak에 문제가 생길 때 로그인이 안 되거나 일부 기능이 멈출 수 있다.
그래서 운영에서는 Keycloak을 여러 대로 운영해 한 대가 고장 나도 계속 동작하게 하거나, 장애 시 대응 방식(예: 기존 로그인 유지, 임시 우회 정책)을 미리 정해두는 게 좋다.

5.3 설정 실수가 곧 보안 사고로 이어질 수 있다

리다이렉트 주소, 토큰 설정, 권한 매핑 같은 설정을 잘못 잡으면 우회 로그인, 권한 과다 부여, 토큰 오용 같은 문제가 생길 수 있다.

5.4 토큰 방식에 익숙해져야 한다

토큰 기반으로 가면 “서버 세션”과 방식이 달라진다.

로그아웃을 어디까지 강제할지
토큰 만료 시간을 어떻게 잡을지
refresh token을 쓸지
같은 결정을 해야 한다.

5.5 커스터마이징 비용

로그인 UI, 동의 화면, 인증 흐름을 깊게 바꿀수록 유지보수 비용이 올라간다.
조직의 UX 요구사항이나 보안 정책이 특이할수록 비용이 커질 수 있다.

5.6 팀 학습 비용

Realm, Client, Role 설계와 OIDC 개념을 팀이 함께 이해해야 운영이 안정된다.
한 사람만 알고 있는 시스템이 되면 유지보수와 장애 대응이 위험해진다.

7) 언제 Keycloak이 잘 맞나, 아닐 수도 있나

잘 맞는 경우

로그인 대상 서비스가 여러 개라서 SSO가 필요하다
역할/권한이 복잡해지고 중앙 관리가 필요하다
추가 인증(MFA), 소셜 로그인 같은 보안 기능을 표준 방식으로 빠르게 도입하고 싶다
조직 차원에서 로그인과 권한 정책을 통일하고 싶다

오버스펙일 수 있는 경우

서비스가 1개이고 사용자/권한 요구사항이 단순하다
별도 서버를 운영하고 장애에 대응할 여력이 부족하다
요구사항이 너무 특수해서 커스터마이징이 과해질 가능성이 높다

마무리

Keycloak은 로그인과 권한이라는 중요한 기능을 서비스 밖으로 분리해 중앙에서 관리하게 해준다.
대신 운영 복잡도와 설계 결정, 설정 책임이 생긴다.
도입 전에 "우리가 이 로그인 서버를 운영할 준비가 되었는지"를 먼저 점검하는 게 좋다.

[🔓 Unlisted Post] - 보안 관련 개념

#Keycloak이란? 로그인과 권한을 한 곳에서 관리하는 방법

#1) Keycloak 한 문장 요약

#3) 전체 흐름을 Mermaid로 보기

#4) Keycloak 도입의 장점

#4.1 구현과 보안 책임을 분리한다

#4.2 한 번 로그인으로 여러 서비스를 쓸 수 있다

#4.3 표준 프로토콜을 지원해서 연동이 쉽다

#4.4 사용자와 권한을 중앙에서 관리한다

#5) Keycloak 도입의 tradeoff (반드시 알고 가야 할 것들)

#5.1 운영 복잡도 증가

#5.2 로그인 서버가 멈추면 서비스도 영향을 받는다

#5.3 설정 실수가 곧 보안 사고로 이어질 수 있다

#5.4 토큰 방식에 익숙해져야 한다

#5.5 커스터마이징 비용

#5.6 팀 학습 비용

#7) 언제 Keycloak이 잘 맞나, 아닐 수도 있나

#잘 맞는 경우

#오버스펙일 수 있는 경우

#마무리

#관련 글