- Red Hat에서 개발한 오픈소스 Identity and Access Management(IAM) 솔루션입니다. 현대적인 애플리케이션과 서비스를 위한 인증 및 권한 부여 기능을 제공하는 인증 서버(Authentication Server)의 기능을 수행합니다.
- Keycloack에서는 여러 플랫폼에서 중앙 집중식 인증 서버로 동작을 합니다. 주요한 기능은 서로 다른 도메인에서 실행되는 애플리케이션 간의 SSO를 지원하거나 REST API 기반에 접근제어 토큰에 대한 인증 제공 및 세션 타임아웃, 동시 로그인 제한과 같은 다양한 세션 기능을 담당합니다.
https://www.keycloak.org/
2) 왜 Keycloak을 써야 할까?
💡 왜 Keycloak을 써야 할까?
- 오픈소스인 Keycloak을 통해서 사용자 관리를 해야 하는 이유에 대해 알아봅니다.
1. 중앙 집중식 인증 관리 - 여러 애플리케이션에 대한 인증을 한 곳에서 관리할 수 있어 보안 정책 적용과 유지보수가 용이합니다.
2. SSO(Single Sign-On) 지원 - 사용자가 한 번의 로그인으로 여러 애플리케이션에 접근할 수 있어 사용자 경험이 향상됩니다.
3. 다양한 인증 프로토콜 지원 - OpenID Connect, SAML 2.0 등 표준 프로토콜을 지원하여 다양한 시스템과의 통합이 가능합니다.
4. 소셜 로그인 통합 - Google, Facebook 등 소셜 로그인을 쉽게 구현할 수 있습니다.
5. 강력한 보안 기능 - 2단계 인증, 비밀번호 정책, 세션 관리 등 다양한 보안 기능을 제공합니다.
6. 오픈소스 - 무료로 사용 가능하며, 활발한 커뮤니티 지원과 지속적인 업데이트가 이루어집니다.
7. 확장성 - REST API를 통한 통합이 용이하며, 커스터마이징이 가능한 유연한 아키텍처를 제공합니다.
1. 관리자 페이지 내에서 관리하는 세션 관리
💡 관리자 페이지 내에서 관리하는 세션 관리
- 사용자가 로그인을 수행하면 사용자 인가를 받고 유지되는 세션에 대해서 관리를 할 때, JWT를 이용하여 데이터 통신을 수행하는 경우에는 토큰 내에 만료시간을 두어서 세션 관리를 했습니다.
💡 JWT를 이용하는 경우 - 기존의 JWT 기반의 인증 및 인가를 수행할 때, 토큰에 만료시간을 두어서 리소스에 접근할 수 있는 시간을 두었습니다. - 이를 토큰이 생성되는 소스코드 내에서 AccessToken, RefreshToken 형태로 일정 시간을 지정하였습니다.
- 아래와 같이 Keycloak에서는 사용자가 애플리케이션에게 로그아웃 동작을 요청하면, 애플리케이션에서는 keycloak으로 로그아웃을 실행합니다. - 이를 통해서, 특정 애플리케이션 내에 로그아웃뿐만 아니라 이와 연관된 애플리케이션에서 동시에 로그아웃을 수행할 수 있다는 장점이 있습니다.
- 기존의 내부 로그인 외에 외부 소셜 로그인을 수행하고자 할 때, 구성해야 하는 부분들이 많았습니다. - 예를 들면, 기존 내부 사용자 테이블과 별도의 소셜 로그인을 사용하기 위한 테이블도 매핑해서 구성해야 다시 로그인을 할 때, 같은 사용자임을 확인할 수 있는 과정이 필요했습니다.
💡 Keycloak을 사용하는 경우
- 복잡한 설정이 필요 없이 소셜 로그인의 제공자의 Client ID와 Secret만 설정하면 사용이 가능합니다. 또한, 소셜 로그인으로 받아온 사용자 정보를 Keycloak의 사용자 속성에 자동으로 매핑할 수 있기에 쉽게 사용이 가능합니다.
4. 편리한 서비스별 관리
💡 편리한 서비스별 관리
- Keycloak에서는 Realm과 Client를 통해 서비스를 논리적으로 분리하여 관리할 수 있습니다. - 예를 들어서, 개발/운영 환경별로 Realm을 분리하여 관리하고, 서비스의 특성에 따라 Client를 분리하여 관리할 수 있습니다. - 또한, 각 Client별로 독립적인 역할(Role) 및 권한 관리를 수행하며 Client별로 다른 세션 타임아웃 및 토큰 설정 적용이 가능합니다.
💡 아래와 같이 test-loc-realm이라는 공간 내에 Client를 분리하여서 사용합니다.
- 이를 통해서, 각각 관리하는 부분에 대해 중앙에서 관리가 가능하며, 세부적으로 서비스 별로도 관리가 가능하다는 장점이 있습니다.
💡 이외에도 다양한 장점들에 대해서는 아래의 주요 기능들을 통해 Keycloak에 대해 알아봅니다.
3) Keycloak 주요 기능
1. 단일 로그인(Single Sign-On, SSO), 단일 로그아웃(Single Sign-Out, SLO)
💡 단일 로그인(Single Sign-On, SSO), 단일 로그아웃(Single Sign-Out, SLO)
- 사용자는 Keycloak에 로그인을 하면 사용자는 한 번의 인증으로 여러 ‘서비스’나 ‘애플리케이션’에 접근할 수 있습니다. 이러한 접근은 ‘서로 다른 도메인’에서 실행되는 애플리케이션들 간에서도 적용이 됩니다. - 또한, 이러한 로그인과 같이 로그아웃에서도 적용이 됩니다. 즉, 사용자는 Keycloak을 사용하는 모든 애플리케이션에서 로그아웃하기 위해 한 번만 로그아웃을 하면 됩니다
- 이를 통해, 개발자는 각 애플리케이션마다 별도의 로그인 시스템을 구축할 필요 없이, Keycloak을 통해 인증을 통합 관리할 수 있습니다.
💡 최초 Keycloak에 로그인을 하게 되면, 이와 연결된 여러 서비스나 애플리케이션에 접근을 할 수 있습니다.
https://www.keycloak.org/
💡 Users > 사용자
- 사용자 별로 연결된 모든 세션에 대해서 단일 로그아웃을 수행할 수 있습니다. - 또한, Keycloak API를 통해서 일괄 로그아웃을 수행할 수 있습니다.
2. 인증 중계(Identity Brokering) 및 소셜 로그인 : Identity Brokering and Social Login
💡 인증 중계(Identity Brokering) 및 소셜 로그인 : Identity Brokering and Social Login
- 사용자는 인증 중계(Identity Brokering)를 하는 LDAP, OpenID Connect, SAML, Kerberos 등과 같은 사용자의 정보를 다루는 외부 인증 시스템과의 중계를 하는 기능을 제공합니다 - 소셜 로그인(Google, Facebook,..)을 통한 Keycloak 접근을 하는 기능을 제공해 줍니다.
- 이를 통해 사용자는 기존에 사용하던 계정으로 간편하게 로그인을 할 수 있습니다. 이러한 구성은 관리 콘솔을 통해 간단하게 소셜 로그인을 구성할 수 있으며, 애플리케이션 코드 변경이 필요하지 않습니다.
https://www.keycloak.org/
[ 더 알아보기 ] 💡 인증 중계(Identity Brokering)
- 외부 신원 공급자(Identity Provider)와 서비스 제공자(Service Provider) 사이에서 인증을 중개하는 프로세스입니다 사용자가 외부 Identity Provider(예: Google, Facebook)를 통해 로그인하면, Keycloak이 해당 인증을 검증하고 처리합니다. 성공적인 인증 후, Keycloak은 해당 사용자에 대한 새로운 세션을 생성하고 필요한 토큰을 발급합니다. - Keycloak은 외부 Identity Provider로부터 받은 사용자 정보를 내부 시스템에 매핑하여 관리합니다.
💡 [참고] 인증 중계(Identity Brokering) 및 소셜 로그인을 구성하는 관리자 페이지입니다. : Identity provider
- 위에서 이야기한 인증 중계(Identity Brokering)를 위한 User-defined로 “Keycloak OpenID Connect”, “OpenID Connect v1.0”, “SAML v2.0”을 확인해 볼 수 있습니다. - 또한, 소셜 로그인으로는 BitBucket, Facebook, GitHub 등을 통해서 로그인을 허용하는 기능으로 제공합니다.
3. 연동 방식 : User federation
💡 연동 방식 : User federation
- 기존 시스템의 사용자 데이터를 유지하면서 Keycloak의 고급 인증 및 권한 관리 기능을 활용할 수 있습니다. - LDAP(Lightweight Directory Access Protocol)을 통한 AD(Active Directory)와의 연동 및 관계형 데이터베이스와의 연동을 수행할 수 있습니다.
주요 키워드
설명
특징
LADP
네트워크상에서 디렉터리 서비스에 접근하기 위한 표준화된 프로토콜
- 사용자 데이터 실시간 동기화 - LDAP 속성과 Keycloak 사용자 속성 매핑 - 읽기/쓰기 모드 지원
AD
Microsoft에서 개발한 Windows 기반 디렉터리 서비스
- Windows 도메인 계정으로 인증 - AD 그룹/역할을 Keycloak에 매핑 - SSO(Single Sign-On) 지원
https://www.keycloak.org/
3.1. LDAP & AD 연동
💡 LDAP & AD 연동 : Use federation > Add LDAP Provider
- LDAP Provider를 통해서 Vendor를 지정할 수 있습니다. LDAP을 통해서 디렉터리 서비스(Active Driectory, Red Hat Directory Server 등)를 통해서 사용자 정보의 실시간 동기화를 수행합니다.
4. 세션 관리
💡 세션 관리
- Keycloak을 통해서 세션이 유지되는 시간을 결정(세션 타임아웃)하거나 동시에 동일한 아이디에 로그인을 하는 기능을 설정(동시 로그인 제한)하거나, 강제 로그아웃을 시키는 기능들을 제공합니다.
세션 유형
설명
SSO Session Settings
Single Sign-On 세션의 수명주기를 관리하는 중요한 설정입니다
Client Session Settings
각 클라이언트(애플리케이션)별로 세션을 독립적으로 관리하며, Realm의 전체 SSO 세션 설정과는 별개로 동작합니다
Offline Session Settings
사용자가 오프라인 상태에서도 애플리케이션에 접근할 수 있도록 하는 장기 세션 설정입니다
Login Settings
사용자의 로그인 과정과 관련된 시간 제한을 설정하는 기능입니다
2.1. SSO Session Settings
💡 SSO Session Settings
- Keycloak에서 Single Sign-On 세션의 수명주기를 관리하는 중요한 설정입니다.
설정
설명
SSO 세션 유휴 (Idle)
사용자가 아무런 활동을 하지 않을 때 세션이 유지되는 시간을 분 단위로 설정. 시간 경과 시 세션 만료
SSO 세션 최대 (Max)
사용자 활동과 관계없이 세션이 유지될 수 있는 최대 시간. 시간 경과 시 반드시 재로그인 필요
SSO 세션 유휴 기억하기 (Remember Me)
"Remember Me" 기능 사용 시 적용되는 유휴 시간. 일반 세션보다 더 긴 시간 설정 가능
SSO 세션 맥스 Remember Me
"Remember Me" 기능 사용 시의 최대 세션 유지 시간. 일반 세션보다 길게 설정하여 사용자 편의성 향상
2.2. Client session settings
💡 Client session settings
- 각 클라이언트(애플리케이션) 별로 세션을 관리하기 위한 설정입니다. 이러한 설정은 각 클라이언트별로 독립적으로 적용되며, Realm의 전체 SSO 세션 설정과는 별개로 동작합니다. 클라이언트별로 더 엄격하거나 유연한 세션 정책을 적용할 수 있습니다.
설정
설명
Client Session Idle
클라이언트 애플리케이션에서 사용자의 활동이 없을 때 세션이 유지되는 시간(분)을 설정합니다.
Client Session Max
사용자 활동과 관계없이 클라이언트 세션이 유지될 수 있는 최대 시간(분)을 설정합니다.
3.3. Offline session settings
💡 Offline session settings
- 사용자가 오프라인 상태에서도 애플리케이션에 접근할 수 있도록 하는 장기 세션 설정입니다.
설정
설명
Offline Session Idle
오프라인 세션의 유휴 시간을 일(Days) 단위로 설정합니다. 설정된 기간 동안 사용자 활동이 없으면 오프라인 세션이 만료됩니다.
Offline Session Max Limited
오프라인 세션의 최대 지속 시간 제한을 설정하는 옵션입니다. Disabled로 설정하면 시간 제한 없이 오프라인 세션이 유지됩니다.
3.4. Login settings
💡 Login settings
- 사용자의 로그인 과정과 관련된 시간제한을 설정하는 기능입니다.
설정
설명
Login timeout Minutes
사용자가 로그인 프로세스를 완료해야 하는 최대 시간을 설정합니다. 이 시간 내에 로그인을 완료하지 않으면 처음부터 다시 시작해야 합니다.
Login action timeout
특정 로그인 관련 작업(예: 비밀번호 재설정, 이메일 확인 등)을 완료해야 하는 시간을 설정합니다. 이 시간이 초과되면 해당 작업을 다시 시작해야 합니다.
5. 계정 관리 콘솔
💡 계정 관리 콘솔
- Keycloak에서는 관리자 콘솔은 웹 기반의 인터페이스로 관리가 됩니다. - 아래와 같은 주요한 기능들을 제공합니다.
기능
설명
사용자 관리
사용자 생성, 수정, 삭제 및 권한 부여
클라이언트 관리
애플리케이션 등록 및 설정, 클라이언트 스코프 정의
Realm 설정
보안 정책, 인증 흐름, 토큰 설정
Identity Provider 설정
소셜 로그인 및 외부 인증 제공자 연동
역할 관리
시스템 전체 및 클라이언트별 역할 정의
세션 관리
사용자 세션 모니터링 및 제어
5.1. 사용자 관리
💡 사용자 관리
- 아래와 같이 관리자 페이지 내에서 사용자를 생성했고, 각각 사용자 정보(profile)를 구성하였습니다. 이는 관리자 페이지에서 즉시 수정이 가능합니다.
💡 아래와 같이 비밀번호도 즉시 관리자 페이지 내에서 변경이 가능합니다.
4) Keycloak 구성요소
구성 요소
설명
Realm
사용자, 자격증명, 역할 및 그룹을 관리하는 논리적인 영역
Clients
Keycloak을 통해 보호되는 애플리케이션이나 서비스
Users
Keycloak에서 관리되는 최종 사용자
Groups
사용자들을 논리적으로 구성하고 관리하는 단위
Roles
사용자나 그룹에 할당할 수 있는 권한 단위
💡 Keycloak 기본 구조
- 기본적인 구조로 Keycloak에서는 realm1, realm2 형태로 분리가 되며, 각각의 realm1은 client1, client2, client3 형태로 분리가 된 구조를 가지고 있습니다. - 이는 Keycloak 환경에서 물리적인 realm을 분리하고 내부에 각각 애플리케이션이나 서비스를 의미하는 Client를 분리한 구조를 가집니다.
https://www.youtube.com/watch?v=dFPGO5jDHPY
1. Realm
💡 Realm
- 사용자, 자격증명, 역할 및 그룹을 관리하는 논리적인 영역을 의미합니다. 이를 통해 Relam 단위에 독립적인 환경이 구성되고 관리가 됩니다. - 하나의 애플리케이션에서 동일한 로그인 체계를 사용하는 경우, 이는 하나의 Realm 내에서 관리가 됩니다. 이를 통해서 독립적인 모든 사용자, 역할 그룹을 관리하게 됩니다.
[ 더 알아보기 ] 💡 여러 Realm을 사용하는 경우는 어떤 경우일까?
- 완전히 분리된 사용자 그룹을 관리해야 하는 경우 (예: 내부 직원용과 외부 고객용) - 서로 다른 보안 정책이나 인증 방식이 필요한 경우 - 다중 테넌트(Multi-tenant) 애플리케이션을 구현하는 경우
- 최초 Keycloak 설치 시 자동으로 생성되는 첫 번째 realm입니다. 해당 master realm내에는 '슈퍼 관리자 계정'이 포함되어 있습니다. 이 슈퍼 관리자 계정은 다른 realm들의 생성, 수정, 삭제와 같은 관리 작업을 수행할 수 있습니다.
- 보안상의 이유로 일반 사용자의 인증용으로는 사용하지 않는 것이 권장이 되며, 실제 서비스를 위해서는 별도의 realm에서 생성하고 사용해야 합니다.
1.2. realm
💡 realm
- 아래와 같이 로컬 환경에서의 ‘test-loc-realm’과 개발 환경에서의 ‘test-dev-realm’으로 물리적인 분리를 하여 물리적인 공간을 분리하여 realm으로 관리할 수 있습니다.
2. Clients
💡 Clients
- Keycloak을 통해 보호되는 애플리케이션이나 서비스를 의미합니다. 즉, 사용자가 인증을 요청할 수 있는 애플리케이션과 서비스를 의미합니다. - 각각에 Client는 자체적인 설정, 접근 정책, 권한등을 가질 수 있습니다.
2.1. Client 프로토콜
💡 Client 프로토콜
- keycloak이 클라이언트 애플리케이션과 통신하는 데 사용하는 데 사용하는 프로토콜을 선택합니다. - 주로 OpenID Connect와 SAML 두 가지 프로토콜을 지원하며, 각각의 프로토콜은 서로 다른 사용 사례와 장단점을 가지고 있습니다.
프로토콜
설명
OpenID Connect
OAuth 2.0을 기반으로 하는 인증 프로토콜로, JWT(JSON Web Token)를 사용하여 사용자 인증 정보를 안전하게 전달합니다. 주로 모던 웹/모바일 애플리케이션에서 사용됩니다.
SAML
Security Assertion Markup Language의 약자로, XML 기반의 보안 표준입니다. 주로 엔터프라이즈 환경에서 사용되며, 조직 간 SSO(Single Sign-On)를 구현하는 데 널리 활용됩니다.
2.2. OpenID Connect 프로토콜 인증 방식
💡 OpenID Connect 프로토콜 인증 방식
- OpenID Connect 프로토콜을 기반으로 인증 방식의 종류들을 확인해 봅니다.
인증 방식
설명
Standard Flow
OAuth 2.0의 Authorization Code Flow를 사용하는 전통적인 웹 애플리케이션에서 사용되는 표준 인증 방식입니다.
Direct Access Grants
사용자 이름과 비밀번호를 직접 사용하여 토큰을 얻는 방식으로, 신뢰할 수 있는 애플리케이션에서 사용됩니다.
Implicit Flow
브라우저 기반 애플리케이션을 위한 간소화된 OAuth 2.0 흐름입니다. 보안상의 이유로 현재는 권장되지 않습니다.
Service Accounts Roles
클라이언트 자체가 직접 API를 호출할 때 사용하는 인증 방식입니다.
OAuth 2.0 Device Authorization Grant
스마트 TV나 IoT 기기와 같이 제한된 입력 기능을 가진 디바이스를 위한 인증 흐름입니다.
OIDC CIBA Grant
Client Initiated Backchannel Authentication 흐름으로, 클라이언트가 사용자 장치를 통하지 않고 인증을 시작할 수 있게 합니다.
3.3. Client 활용 예시
💡 Client 활용 예시
- 아래와 같이 test-loc-realm 내에 두 개의 애플리케이션(test-a-app, test-b-app)에 대한 형태로 Client를 구성하여 각각 분리를 하였습니다. 또한, SSO 인증과 같이 별도 구성이 필요하는 경우 클라이언트로 구성을 합니다. - 아래와 같이 Google 로그인에 대해서는 sso-google-login으로 분리를 하였습니다.
3. Users
💡 Users - Keycloak에서 관리되는 최종 사용자(End Users)를 의미합니다. 각 사용자는 하나 이상의 Realm에 속하며 각각 다른 역할과 권한을 가질 수 있습니다.
- 사용자의 추가정보는 기본적인 프로필 정보(이름, 이메일 등)를 가지며, 관리자가 추가 속성을 정의하여 수집할 수 있습니다.
💡 사용자가 로그인을 할 때 필요로 하는 작업들(Required user actions)을 지정할 수 있습니다.
- 이러한 값은 필수는 아니고, 관리자가 필요에 따라 선택적으로 지정할 수 있습니다.
Required Action
설명
Configure OTP
- 2단계 인증을 위한 OTP(One Time Password) 설정을 요구합니다. 사용자는 인증 앱을 통해 OTP를 설정해야 합니다.- 모바일 비밀번호 생성기를 통해 생성이 됩니다.
Update Password
사용자에게 새로운 비밀번호를 설정하도록 요구합니다. 보안상의 이유나 비밀번호 만료 시 사용됩니다.
Update Profile
사용자의 프로필 정보(이름, 주소 등)를 업데이트하도록 요구합니다.
Verify Email
사용자의 이메일 주소가 유효한지 확인하기 위해 확인 이메일을 발송하고 인증을 요구합니다.
Webauthn Register
생체 인증이나 보안 키와 같은 WebAuthn 인증 수단을 등록하도록 요구합니다.
Webauthn Register Passwordless
비밀번호 없이 WebAuthn을 사용할 수 있도록 설정을 요구합니다.
Verify Profile
사용자 프로필의 특정 정보가 정확한지 확인하고 검증하도록 요구합니다.
Delete Credential
기존 인증 수단을 삭제하도록 요구합니다.
Update User Locale
사용자의 지역 설정(언어, 시간대 등)을 업데이트하도록 요구합니다.
💡 사용자의 기본 속성으로 username, email, firstName, lastName과 같은 사용자로부터 받을 수 있는 속성들에 대해서 추가하여서 사용자 정보를 더 수집할 수 있습니다.
4. Groups
💡 Groups
- Keycloak에서 사용자들을 논리적으로 구성하고 관리하기 위한 방법입니다. 그룹을 통해 여러 사용자에게 공통된 속성과 역할을 한 번에 할당할 수 있습니다. - 그룹은 계층 구조로 구성될 수 있어, 상위 그룹의 속성과 권한이 하위 그룹에 상속됩니다.
5. Roles
💡 Roles
- Keycloak에서 사용자나 그룹에 할당할 수 있는 권한 단위입니다. 역할을 통해 특정 리소스나 기능에 대한 접근 권한을 제어할 수 있습니다. - 역할은 크게 Realm Roles와 Client Roles로 구분됩니다.
구분
설명
Realm Roles
Realm 전체에서 사용되는 글로벌 역할입니다. 모든 클라이언트 애플리케이션에서 공통으로 사용됩니다.
Client Roles
특정 클라이언트(애플리케이션)에 한정된 역할입니다. 해당 클라이언트 내에서만 의미를 가집니다.
Group Roles
그룹에 할당되는 역할입니다. 그룹의 모든 멤버에게 자동으로 상속되며, 계층 구조에서 상위 그룹의 역할이 하위 그룹에 상속됩니다.
💡 Realm roles에 대해서 Realm 전체에 대한 글로벌 역할에 대한 예시
💡 Client roles에 대해서 Client 서비스 및 애플리케이션에 대한 역할에 대한 예시
💡 Group에 대해 역할을 지정하는 경우의 예시
5) Keycloak 로그인 과정
💡 Keycloak 인증 처리 과정
1. 연동 서비스 접근 : 사용자 → 연동서비스 - 사용자가 애플리케이션/서비스에 접근을 시도합니다.
2. 인증 요청 : 연동 서비스 → keycloak - 연동 서비스를 통해서 keycloak에 접근합니다.
3. 로그인 페이지 오픈 : Keycloak → 사용자 - 애플리케이션에서는 사용자를 Keycloak 로그인 페이지로 리다이렉트 합니다.
4. 로그인 정보 입력 : 사용자 → keycloak - 사용자는 자격 증명을 통해서 사용자의 인증을 수행합니다.
5. 외부 저장소 정보로 로그인 : Keycloak → 외부 저장소 → Keycloak - 인증 정보를 기반으로 외부 저장소로부터 자격 증명을 검증하고 성공적으로 인증되면 액세스 토큰을 발급합니다.
6. 인증 전달 : Keycloak → 인증 서비스 - 사용자는 발급받은 토큰과 함께 원래 요청했던 애플리케이션으로 리다이렉트 됩니다.
7. 연동 서비스 페이지 오픈 : 연동 서비스 → User - 애플리케이션은 토큰을 검증하고, 유효한 경우 요청한 리소스에 대한 접근을 허용합니다.
