Keycloak 구축 및 AWS SAML 연동

1. Keycloak 개념

Keycloak은 Red Hat에서 개발한 오픈소스 IAM 솔루션입니다. OAuth 2.0 및 OpenID Connect와 같은 표준 프로토콜을 기반으로 사용자 인증ㆍ인가 기능과 SSO를 제공합니다.

기업에서 사용하는 무수히 많은 서비스에 대한 인증을 개별적으로 관리하는 것은 보안담당자 뿐만 아니라 사용자로서도 무척 불편한 부분입니다. 이런 불편함을 극복하고 중앙 집중식의 통합된 사용자 관리 기능을 Keycloak를 통해 달성할 수 있습니다. 

Keycloak을 이해하기 위해 필요한 개념은 다음과 같습니다.

 

Realm
애플리케이션 그룹을 "Realm"으로 정의합니다. 각 Realm은 독립된 사용자 그룹, 클라이언트 애플리케이션, 인증 및 접근 제어 설정을 가집니다.

클라이언트
애플리케이션 또는 서비스를 나타냅니다. 각 클라이언트는 고유한 클라이언트 ID와 시크릿 키를 가지며, 사용자 인증 및 접근 제어를 위해 Keycloak과 통신합니다.

사용자
애플리케이션에 접근하는 개별 계정을 의미합니다. 사용자는 Realm 내에서 관리되며, 그룹화, 역할 할당, 사용자 프로필 관리 등이 가능합니다.

---

2. Keycloak 구성

2.1. 설치

Keycloak을 구축할 수 있는 방법은 다양합니다. 도커 또는 K8s를 활용할 수 있고 설치형으로 직접 구축할 수 있습니다. 테스트를 위해 간편하게 설치하는 것이 목적이므로 도커를 활용하도록 하겠습니다. 다음 명령어를 통해 컨테이너를 실행합니다.

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=[admin_id] -e KEYCLOAK_ADMIN_PASSWORD=[admin_password] quay.io/keycloak/keycloak:21.1.1 start-dev

2.2. Realm 생성

Keycloak 어드민 페이지(http://localhost:8080/admin)로 접속하여 컨테이너 생성 시 설정한 계정 정보를 입력해 로그인 합니다. 왼쪽 드롭다운 메뉴에서 "Create Realm"을 클릭합니다. Realm 이름을 입력하고 Create를 클릭합니다.

2.3. 유저 생성

생성한 Realm에서 User - Create new user를 클릭합니다. Username을 비롯한 유저 정보를 입력합니다. Required user actions을 지정해 OTP 설정 패스워드 변경 등을 강제할 수 있습니다. 

Credentials - Set password를 클릭해 유저의 패스워드를 설정하고 저장합니다. Temporary 옵션을 활성화할 경우 유저가 최초로 로그인했을 때 패스워드 변경을 강제할 수 있습니다.

유저 계정 생성 후 사용자 페이지(http://localhost:8080/realms/[렐름이름]/account)로 접속해 "Sign in"을 클릭하여 정상적으로 로그인되는지 확인합니다.

---

3. AWS SAML 연동 

AWS와 Keycloak간에 SAML을 구성하여 별도의 AWS 어카운트 없이 IAM Role 기반으로 AWS 리소스에 접근할 수 있는 환경을 구성할 수 있습니다.

3.1. AWS IAM Role 생성

Realm settings 메뉴에서 SAML 2.0 Identity Provider Metadata를 다운로드 합니다.

AWS IAM 자격 증명 공급자에서 공급자를 추가합니다. 방금전 다운로드 받은 IdP metadata를 업로드 합니다.

SAML을 통해 AWS 리소스에 허용해주고자 하는 역할을 생성합니다.

3.2. Keycloak clients 생성

AWS의 SAML metada를 다운로드하고 Keycloak clients로 등록합니다.

curl -O https://signin.aws.amazon.com/static/saml-metadata.xml

3.2. Keycloak clients 설정

AWS의 SAML metada를 clients 설정에 추가해야 합니다. 조금전 생성한 clients(urn:amazon:webservices)에서 Home URL과 IDP URL을 설정합니다. 

AWS IAM Role과 맵핑할 clients의 Role을 생성합니다.

AWS clients의 scopes에서 role_list를 삭제합니다. 그리고 urn:amazon:webservices-dedicated을 클릭해 Scope 메뉴에서 Full scope allowed 설정을 off 합니다.

Mappers 메뉴로 돌아가 Add mapper를 클릭하고 By configuration을 선택 후 Role list를 추가합니다. 사진과 같이 값을 설정합니다.

Name : Session Role
Role attribute name : https://aws.amazon.com/SAML/Attributes/Role
Friendly Name : Session Role
Single Role Attribute : On

Mappers 메뉴로 돌아가 Add mapper를 클릭하고 By configuration을 선택 후 User Property를 추가합니다. 사진과 같이 값을 설정합니다.

Name : Session Name
Property : username
Friendly Name : Session Name
SAML attribute name : https://aws.amazon.com/SAML/Attributes/RoleSessionName

Mappers 메뉴로 돌아가 Add mapper를 클릭하고 By configuration을 선택 후 Hardcoded attribute를 추가합니다. 사진과 같이 값을 설정합니다.

Name : Session Duration
Friendly Name : Session Duration
SAML attribute name : https://aws.amazon.com/SAML/Attributes/SessionDuration
Attribute value : 43200

Mappers 메뉴로 돌아가 Add mapper를 클릭하고 By configuration을 선택 후 Role Name Mapper를 추가합니다. 사진과 같이 값을 설정합니다.

3.3. Keycloak Group 생성

Group을 만들고 2.3. 유저 생성 단계에서 생성한 유저를 추가합니다.

생성한 Group에 3.2. 단계에서 생성한 Role 맵핑합니다.

---

4. AWS SAML 접속

4.1. 콘솔 로그인

Clients 메뉴의 Target IDP initiated SSO URL로 접속합니다. 유저 정보를 입력하면 Keycloak 페더레이션 사용자로 로그인되는 것을 확인할 수 있습니다.

4.2. CLI 로그인

saml2aws를 다운로드 합니다.

CURRENT_VERSION=$(curl -Ls https://api.github.com/repos/Versent/saml2aws/releases/latest | grep 'tag_name' | cut -d'v' -f2 | cut -d'"' -f1)
$ wget -c https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz -O - | tar -xzv -C /usr/local/bin
$ chmod u+x /usr/local/bin/saml2aws

saml2aws configure를 설정합니다.

saml2aws login을 합니다. 

AWS 리소스에 정상적으로 접근되는지 확인합니다.

 

5. 참고

• https://www.keycloak.org/guides#getting-started
• https://wlsdn3004.tistory.com/category/Secret/Keycloak