KEYCLOAK - 3.(인증)_따라하기

0. 인증 개요

• Keycloak은 <인증>과 <인가>를 위한 도구로써 먼저는 <인증>과 관련한 Keycloak 설정 및 Application 설정과 관련하여 방법을 간단히 기술한다.

  • Keycloak version : 26.1.3
  • 작성일 : 2025년 5월 5일
  • Keycloak을 활용한 인증 기능의 개념을 잡고 싶으면 아래 링크를 먼저 참고한다.
    KEYCLOAK - (인증) 개념잡기

1. Authentication (인증) 따라하기

• Keycloak 인증을 적용하기 위해 Realm 생성부터 진행한다.
• admin으로 로그인 후 아래 순서에 따라 Realm을 생성한다.

  [ Realm 정의 ]

  • Realm 이란, '영역', '범위'로 해석 되며, Keycloak을 활용하여 SSO나 권한제어를 적용하고자하는 공간을 말한다.

1) Realm Create 하기

• Master login > Create realm 선택
• Realm name 입력 (예:SSO_TEST)
• Create 눌러 Realm을 생성한다.
  

2) Client create

• 같은 Realm에 여러 client 를 등록할 수 있다.
• 같은 Realm에 생성된 client 들은 서로 SSO가 자동으로 수행된다.

  [ Client 정의 ]

  • Client란 Keycloak을 적용하고자 하는 Web site, Application을 말한다.

2.1) Client 생성순서

• Realm 선택 : 예) SSO_TEST
• client > create client
• client id :예)sso-test-site1
• Name : 예)sso-test-site1
• Display : 예)sso-test-site1
• Client authentication : ON
• Home URL : 예) https://www.test.com (Keycloak 적용할 Site URL)
• Valid rediret URIs : 예) https://www.test.com/*
• Web origins : 예) https://www.test.com (CORS 오류 방지를 위함)
• Save
  

3) Application 설정

• springboot 위주로 설명한다.
• 2)번 Client create에서 등록한 client에 대해서 해당 Application의 application.properties를 아래와 같이 keycloak.client-id와 keycloak.client-secret 값을 설정한다.
• keycloak.provider ~ keycloak.issuer-uri 및 jwt.issuer-uri 까지 아래 sample 설정을 참고하여 설정한다.

# application.proprerties file
# keycloak
spring.security.oauth2.client.registration.keycloak.client-id=sso-test-site1
spring.security.oauth2.client.registration.keycloak.client-secret=HgHj1kJulpFQ1pUl95YSNG7Cq902sMls
spring.security.oauth2.client.registration.keycloak.provider=keycloak
spring.security.oauth2.client.registration.keycloak.scope=openid,profile,email
spring.security.oauth2.client.registration.keycloak.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.keycloak.redirect-uri={baseUrl}/login/oauth2/code/{registrationId}
spring.security.oauth2.client.provider.keycloak.issuer-uri=https://www.test.com:30000/realms/SSO_TEST
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://www.test.com:30000/realms/SSO_TEST

---

4) Keycloak - 회원 가입하기

• Keycloak 에서 같은 Realm에 속한 Application은 같은 사용자(User)를 공유한다.
• 이를 위해 Keycloak이 제공하는 <공통 로그인 화면>을 제공하고 이 로그인 화면을 통해서 회원가입을 할 수 있다.
• 회원가입과 관련한 Keycloak 설정은 아래와 같다.

• Realm 선택 : 예) SSO_TEST
• 왼쪽 메뉴에서 Realm settings 선택 > Login 탭 선택
• [ Login screen customization 에서 ]
  • User registration : ON
  • Forgot password : ON
  • Remember me : ON
• [ Email settings 에서 ]
  • Duplicate emails : ON
  • Verify email : ON

• 위와 같이 Login 설정을 하면 아래 처럼 Keycloak 에서 제공하는 <공통 로그인 화면> 하단에 '가입하기(Register)' Link가 나타난다.
• 이 가입하기 Link를 누르면 아래와 같이 회원가입을 할 수 있다.
• 회원가입과 더불어 <비밀번호 찾기>, <로그인 상태유지(Remember me)> 링크도 활성화 시킬 수 있다.

5) 회원가입 - Email인증

• 회원 가입 시 본인 여부를 Email 을 통해서 <본인확인>을 수행할 수 있다.
  • SMS 본인확인은 미지원
• 회원 가입 시 Email 을 통해 본인 확인을 완료해야만 계정이 활성화 되게 할 수 있다. (Verify email : ON)
  • 또한 하나의 Email 로 여러번 회원가입을 하게 할 수 있다. (Duplication emails: ON)
• 이를 위해 아래과 같이 설정하면 회원가입시 입력한 Email 계정으로 <본인확인>을 위한 Email을 발송된다.
• 이 Verify email 을 개봉하여 링크를 누르면 Email 본인인증을 수행 후 자동으로 Site에 로그인이 된다.

• Realm 선택 : 예) SSO_TEST
• 왼쪽 메뉴에서 Realm settings 선택 > Login 탭 선택
• [ Email settings 에서 ]
  • Duplicate emails : ON
  • Verify email : ON
  • Email as username : ON 으로 하면
    • 가입할 때 username이 -> email로 변경된다.

6) Keycloak - SMTP 설정

• 앞에서 회원 가입 시 Email 본인 인증을 수행하기 위해서는 먼저 SMTP 를 설정해야 한다.
• SMTP는 Simple Mail Transfer Protocol로 아래과 같이 SMTP 설정을 하면 Keycloak이 등록한 정보를 이용해서 <Email 본인인증>과 <비밀번호 찾기>를 수행할 때 Email을 발송 한다.
• SMTP 설정하기

  1. Realm 선택 : 예) SSO_TEST
  2. Realm settins > Email 탭 선택
     • From : 보내는자 이메일 예) admin@gmail.com
     • From display name : 송신자 이름, 예) KEYALOAK_ADMIN
  3. Connection & Authentication
     • Host : SMTP IP (예: smtm.gmail.com)
     • Port : SMTP Port (예: 465 )
     • Encryption : Enable SSL ON
     • Authentication : Enalbled
       • ID : SMTP Login ID : (예: gmail ID)
       • PW : SMTP Login PW : (예: 구글의 경우 '앱 비밀번호' 를 입력해야 함)
  4. 등록 후 Test connection을 누르면 Test 메일이 오면 연결 성공
     • (예:확인메일 제목) [KEYCLOAK] - SMTP test message

---

7) 2차 인증(2FA) 적용

• 2차 인증이란 ID/PW 로그인 후 OTP(One Time Password)로 한번 더 인증하는 과정을 말한다. 즉 2번째 인증하는 단계를 말한다.
• Keycloak에서 특정 Application(Site)에 대해서 2차 인증을 적용하기 위하여 Login 과정에서 OTP 과정을 수행하게 Flow를 변경해 주면 된다.
• 2차 인증 적용은 Application Flow를 통해서 구현된다.

7.1) OTP Flow 정의

1.Realm 선택 : 예) SSO_TEST
2.왼쪽 메뉴에서 Authentication 선택 > Flow 탭 선택
3.Built-in Flow 중에서 > browser flow (Browser based authentication) 선택
4.Built-in Flow는 수정할 수 없고 우측 상단의 Action > Duplicate를 선택
5.Built-in Flow를 my-otp-browser로 복사
6.Autentication > my-otp-browser 로 들어가서 수정

• 불필요한 flow 삭제
• Identity Provider Redirector : OFF
• Username / Password ~ OTP Form 까지 : 모두 ON

7.2) OTP 적용하기

• 특정 Application에 OTP를 적용하기 위하여 위에서 OTP flow를 정의하였다.
• 이 OTP flow를 Application(client)에 적용해 주면 해당 Site를 로그인할 때 2차 인증 단계(Flow)를 타게 된다.
• 2차 인증 적용하기

1.Realm 선택 : 예) SSO_TEST
2.Clients 선택 : 예) sso-test-site1
3.Advanced 탭 선택
4.Advanced 최하단 'Authentication flow overrides'에서 앞에서 정의한 OTP flow 선택
5.Save

7.3) 로그인시 OTP 등록

• 특정 Site(Application/Client)에 2차 인증을 적용하면 사용자가 해당 Site에 로그인 시 아래와 같이 OTP 등록을 하도록 안내 화면이 나타난다.
• 아래 그림에서 보는 바와 같이 지원하는 OTP 프로그램으로는
  • FreeOTP
  • Google Authenticator
  • MS Autenticator 3개를 지원한다.
• Authenticator App 에 등록 순서는 아래와 같다.

  1.ID / PWD 인증을 하면 최초 OTP 기기등록 하는 단계가 나타난다.
  2.위에 3개중의 하나를 App스토어에서 Authenticator App을 다운 받아 설치하고
  3.아래 QR코드를 스캔하여 등록한다.
  4.이후 ID/PWD 1차 인증 후 -> 2단계로 OTP 입력화면이 나타난다.
  5.이때 앞에서 등록한 Authenticator App에서 해당 계정의 OTP를 입력하면 Login 할 수 있다.

---

8) 소셜 로그인 (OIDC 설정)

• 소셜 로그인은 회원가입을 <Google 계정으로 로그인> <Facebook 계정으로 로그인> 처럼 소셜 계정을 통해서 회원가입과 로그인을 수행 할 수 있게 하는 기능이다.
• 이를 위하여
  • Keycloak 의 IdP 설정과
  • Google cloud에서는 프로젝트를 생성과 Client를 정보를 상호간에 등록해 주면서 설정이 마무리 된다.

8.1) Google 계정으로 로그인 설정하기 (Google 설정)

• 아래 링크를 눌러 Google cloud 에 접속한다.
  Google Cloud : https://console.developers.google.com

• [STEP-1] Google Cloud 화면 오른쪽에 [프로젝트 만들기]를 선택한다.
  

• [STEP-2] 새 프로젝트 화면에서 [프로젝트 이름]을 입력하고 <만들기>를 선택한다.

  • 프로젝트 이름 : 예) keycloak-google-idp
    

• [STEP-3] 생성된 프로젝트 메뉴에서 [사용자 인증정보]를 선택한다.
  

• [STEP-4] Google 인증 플랫폼 메뉴에서 <시작하기>를 선택한다.
  

• [STEP-5] 시작하기에서 아래와 같이 1~4단계까지 진행한다.

  • 앱 정보를 입력 : 예: keycloak
  • 사용지 지원 이메일 입력 : 예) <본인이메일>@gmail.com

• [STEP-6] 대상을 아래와 같이 <외부>로 선택한다.
  

• [STEP-7] 연락처 이메일을 입력한다.
  

• [STEP-8] 완료단계에서 <Google API 서비스 사용자 데이터 정책>에 동의를 체크하고 만들기를 선택한다.
  

• [STEP-9] 만들기를 선택하면 하단에 <OAuth 구성 생성됨>이란 toast 메시지가 나타나고, 아래와 같이 측정항목에서 <OAuth 클라이언트 만들기>를 선택한다.
  

• [STEP-10] OAuth 클라이언트 ID만들기 화면에서 아래와 같이 정보를 입력하고 만들기를 선택한다.

  • 애플리케이션 유형 : 예) '웹 애플리케이션' 선택
  • 이름 : 예) keycloak 입력
  • 승인된 리디렉션URI : <Keycloak 과 연동하고자하는 IdP URL 입력>

• [STEP-11] 앞에서 만들기를 누르면 아래와 같이 와 이 생성된다. 이 2개의 값을 Keycloak의 Identity providers > Google 에 입력한다.

• 확인을 누르면 아래와 같이 client 목록이 나타나고 Google에서의 설정은 마무리 된다.

8.2) Google 계정으로 로그인 설정하기 (Keycloak 설정)

• Google cloud 에서 OAuth Client를 등록했으면 그 정보를 Keycloak에서도 상호 등록을 해주어야 한다.
• [STEP-1] 아래 화면처럼 Identity providers > Google을 선택한다.
  • Social 목록에 없는 IdP와 연결을 하려면 User-defined > OpenId Connect v1.0 메뉴를 선택해서 진행할 수 있다. (예: 아래 Gitea 설정 참고)

• [STEP-2] 8.1 파트에서 등록한 Google cloud > OAuth Client를 생성하면서 생성된 client-id와 client-secret 정보를 아래와 같이 Keycloak에 등록하고 [Add]를 선택하면 Keycloak에서의 설정도 마무리가 된다.
  • Client ID : <Google cloud에서 생성된 client-id값>
  • ClientSecret : <Google cloud에서 생성된 client-secret값>

8.3) Google 계정으로 로그인 하기

• Google과 Keycloak 양쪽의 설정이 완료되면 아래와 같이 <Keycloak 공통 로그인 화면>에 <Google 계정으로 로그인> 아이콘이 나타난다.

• <Google 계정으로 로그인> 아이콘을 선택하면 아래과 같이 Google 사이트로 넘어가면서 로그인할 계정을 선택하도록 화면이 제공된다.
• 여기서 선택한 Google 계정정보 중에 ID와 이메일 등이 해당 Site 회원가입 시 제공된다.

• Google 계정을 선택을 완료하면 선택된 계정으로 <이메일 본인확인>을 위한 Verify 메일이 발송되며,
• Google 계정 메일함에서 Verify 메일의 Confirm 링크를 누르면 로그인을 완료 할 수 있다.

---

(참고) (Gitea) OAuth2 Application 추가

# Gitea 에 root (관리자) 로그인
# 설정(Settings) > Application 선택
# OAuth2 애플리케이션 관리
  - Application Name : Keycloak
  - Redirect URIs : (Keycloak Add IdP 에서 등록한 endpoint)
    ex) https://keycloak.test.com/realms/SSO_TEST/broker/gitea/endpoint
# 값을 등록 후 Create Application 생성

• Application 등록하면 client_id / client_secreat이 새엉된다.
• 이 값을 다시 Keycloak IdP 등록화면에 넣어 준다.

(Keycloak) Identity Provider 추가

• IdP를 추가하면 Login 시 "Gitea 계정으로 로그인"과 같은 링크가 로그인 페이지에 생긴다.
• 이 경우 Gitea 사이트 로그인으로 인증을 수행한다.

# Realm 선택 : ex) SSO_TEST
# Identity Providers > Add provider 선택
# OpenID Connect v1.0 선택
  - Redirect URI : IdP 인중 후 다시 돌아 Keycloak endpoint
    (Alias를 등록하면 자동으로 endpoint가 구성 됨)
    (ex: https://keycloak.test.com/realms/SSO_TEST/broker/gitea/endpoint
  - Alias : gitea
  - Discovery endpoint : Gitea의 epenid-configuration URL  지정
    (이 값을 지정하면 아래 항목이 자동으로 구성됨)
    : https://gitea.test.com/login/oauth/authorize
    : https://gitea.test.com/login/oauth/access_token
    : https://gitea.test.com/login/userinfo
    : https://gitea.test.com
  - Client ID : (Gitea에서 생성된 client_id)
  - Client Secret : (Gitea에서 생성된 client_secret)