🌱 Infra/KeyCloak

[keycloak 맛보기#8] 사용자 인증(Authentication)

mini_world 2025. 3. 9. 00:50
목차 접기

 

📌 개요

📎 공식문서 링크

인증은 Client(사람/기기/애플리케이션 등)의 신원을 검증하는것을 말한다.
Keycloak은 OAuth2.0 기반의 인증/인가 프로세스를 가지고 있고, Keycloak에서의 인증은 어떻게 사용할 수 있는지 어떤 기능이 있는지 살펴보고자 한다.

 

 

 

📌 인증 흐름 (Authentication flows) 

📎 공식문서 링크

 

인증 흐름이란?

인증 흐름이란 클라이언트가 시스템에 접근할 때 거치는 인증 단계의 순서와 방법을 정의한 것을 말한다.
Keycloak에서는 인증 흐름을 재사용 할 수 있도록 Template 형태로 정의할 수 있다.

Keycloak에서 인증을 어떻게 수행할지 그 방법과 순서를 Authentication Flow로 정의하고,
정의된 Authentication Flow를 특정 인증 상황에 연결(Bind)해서 사용할 수 있도록 한다.

Keycloak에서 사용할 수 있는 인증 흐름은 아래와 같다. 인증 Flow 탬플릿을 정의해서 Bind하여 사용할 수 있다.

  • Browser Flow: 웹 브라우저 기반 로그인을 처리하는 기본 흐름 (사용자명/비밀번호, OTP, WebAuthn 등)
  • Client Authentication: 클라이언트(애플리케이션) 인증 방식을 정의하는 흐름
  • Direct Grant Flow: 사용자 자격 증명을 직접 API로 전송하는 방식(REST API 인증용)
  • Docker Authentication: Docker 레지스트리 인증을 위한 특수 흐름
  • First Broker Login: 소셜 로그인이나 외부 IDP 최초 사용 시 계정 연결 방식 정의
  • Registration Flow: 새 사용자 등록 과정에서 사용되는 단계와 검증을 정의
  • Reset Credentials Flow: 비밀번호 재설정 프로세스를 관리하는 흐름

"재사용한다"는 의미를 정확히 이해할 수 있게 실습을 해보자.

 

[참고] OAuth2.0의 권한부여 유형(Grant Types)과 어떤 관계가 있는지?

이전 OAuth2.0 정리하는 포스팅에서 주요 권한 부여 유형에 대해 살펴 봤었는데, 이것과 어떤 관계인건지 확인하보자.

Keycloak은 OAuth 2.0/OIDC 프로토콜을 구현하는 제품이며, Grant Types를 구현하기 위해 Authentication Flow를 사용한다.
예를들면 아래와 같다. 

  • Authorization Code Grant: Browser Flow를 통해 구현 (사용자 로그인, 권한 동의 등의 단계 포함)
  • Client Credentials Grant: Client Authentication Flow를 통해 구현 (클라이언트 ID/시크릿 검증)
  • Resource Owner Password Grant: Direct Grant Flow를 통해 구현 (사용자 ID/비밀번호 직접 검증)
  • Device Authorization Grant: HTTP Challenge Flow를 통해 구현 (기기 인증 코드 검증)

즉, Grant Type은 OAuth2.0수준에서 정의된 프로토콜 수준의 명세이고, Keycloak의 Authentication Flow는 구현체인것이다.

 

인증 흐름 (Authentication flows) 실습해보기

이제 Keycloak을 실행해보자.
이전 포스팅에서 Docker로 실행하는것과 K8s(minikube) helm으로 실행하는것 모두 실습해보았는데, 실행 방법 편한 방법으로 하자.

# Docker로 실행하기
docker run -p 8080:8080 \
          -e KEYCLOAK_ADMIN=admin \
          -e KEYCLOAK_ADMIN_PASSWORD=admin \
          quay.io/keycloak/keycloak:24.0.4 \
          start-dev

# k8s(minikube) helm으로 실행하기
minikube start
helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak \
  --set auth.adminUser=admin \
  --set auth.adminPassword=admin \
  --set postgresql.auth.username=bn_keycloak \
  --set postgresql.auth.password=password \
  --set postgresql.auth.database=keycloak \
  --set postgresql.auth.postgresPassword=password
kubectl port-forward svc/keycloak 8082:80 &

새로운 Realm을 만든다. (my-Authentication)
개념만 이해할 예정이니 기존에 테스트 하던 Realm을 사용해도 상관없다. 

 

이제 테스트를 위해 사용자를 만들어보자.
나는 user01 사용자를 생성했다. 유저를 생성한 후에는 반드시 Credentials에서 비밀번호를 추가해주어야 한다.

사용자 로그인 테스트를 해보자.
왼쪽 네비게이션바 Clients에서 account home URL을 클릭하면 사용자 로그인 페이지로 들어갈 수 있다.

사용자 로그인 페이지에서 계정과 비밀번호를 입력하게 되어있고, 계정 정보를 입력하면 바로 로그인 할 수 있다.

 

이제 기본값으로 로그인을 했으니, 인증 방식을 변경해보자.

왼쪽 네비게이션바에서 `Authentication`을 클릭하자.
사용가능한 인증 Flow가 정의되어있다.

 

재사용 가능하다는것이 어떤 의미인지 테스트 해보자. 먼저 Browser Flow를 복제한다.

 

이제 이 폼을 좀 바꿔보자.
AS-IS, TO-BE를 확인하고 그대로 수정해도 좋고, 원하는 방식으로 수정해도 된다.
아래의 경우에는 UsernameForm 단계를 추가하고, OTP를 Required로 추가했다.

 

그리고 방금 수정한 Form을 Browser flow로 바인드 한다.

 

그럼 이제 다시한번 사용자 로그인을 통해 인증 방식이 어떻게 변경 되었는지 확인할 수 있다.
이전에는 계정 ID와 비밀번호를 한번에 입력한 후 바로 로그인 되었는데,
my-test-browser 탬플릿으로 변경한 후 ID입력창, PW입력창, OTP설정이 강제된것을 확인할 수 있다.

 

 

 

📌 인증 정책 (Authentication Policies) 

인증 정책은 인증 방식에 대한 정의이다.
위에서 설명했던 인증흐름이 "어떤 순서로 인증할것인가"에 대한 정의였다면, 
인증 정책은 "어떻게 동작해야 하는가"를 정의하는 것 이다.

 

인증 정책(Policies) 종류

Keycloak의 Authentication을 살펴보면 정말 다양한 인증 옵션을 제공하는것을 확인할 수 있다.

  • Password policy: 비밀번호 길이, 복잡성, 특수문자 요구사항 등 비밀번호 강도를 제어하는 설정
  • OTP Policy: 일회용 비밀번호 인증의 알고리즘, 자릿수, 유효기간 등을 설정
  • Webauthn Policy: 생체인증 등 FIDO2/WebAuthn 기반 2차 인증(MFA)을 위한 설정
  • Webauthn Passwordless Policy: 비밀번호 없이 WebAuthn만으로 인증할 수 있는 정책 설정
  • CIBA Policy: 클라이언트 주도 백채널 인증의 시간제한, 인증방식 등을 설정

특히 비밀번호 정책은 KISA홈페이지에만 가도 사용 가이드가 있으니, 자세한 내용은 패스한다.

 

 

 

[참고] WebAuthn(Web Authentication)이란?

📎 webauthn.guide

WebAuthn(Web Authentication)은 웹 상에서 비밀번호대신 공개키 방식의 로그인을 지원하는 인증 기술이며,
2019년 3월에 W3C(World Wide Web Consortium)와 FIDO 얼라이언스가 공동으로 개발하여 공식 웹 표준으로 승인되었다고 한다.

  • 작동 방식:
    • 사이트에 등록할 때:
      1. 사용자가 등록을 시작하면 웹사이트(Keycloak)가 브라우저를 통해 인증 요청을 전송한다.
      2. 인증기(Authenticator- iCloud 키체인, 휴대전화/태블릿의 보안 모듈, USB 보안키 등)가 고유한 암호화 키 쌍을 생성한다.
      2. 개인 키는 인증기(Authenticator) 내부에 안전하게 저장되고, 공개 키는 브라우저를 통해 웹사이트에 전송되어 사용자 계정과 연결된다.
    • 로그인할 때:
      1. 웹사이트는 브라우저를 통해 인증 요청(challenge)을 전송한다.
      2. 브라우저는 이 요청을 인증기(Authenticator)로 전달한다.
      3. 사용자가 지문, 얼굴 인식, PIN 코드 또는 버튼 터치 등으로 자신을 인증하면, 인증기는 저장된 개인 키를 사용하여 challenge에 서명하고 이 서명된 응답을 브라우저를 통해 웹사이트로 전송한다.
      4. 웹사이트는 등록된 공개 키로 서명을 검증하여 사용자를 인증한다.
  • 장점:
    • 피싱 방지: 가짜 웹사이트는 실제 웹사이트의 키를 복제할 수 없음
    • 비밀번호 없음: 기억할 비밀번호가 필요 없음
    • 편리함: 지문 하나로 빠르게 로그인
    • 강력한 보안: 비밀번호보다 훨씬 해킹하기 어려움
728x90
저작자표시 비영리 변경금지 (새창열림)

'🌱 Infra/KeyCloak'의 다른글

  • 현재글[keycloak 맛보기#8] 사용자 인증(Authentication)

관련글

티스토리툴바