Keycloak 인증 후 어떤 정보가 반환되나요? 😋

100===Dev Ops/SSO

Keycloak 인증 후 어떤 정보가 반환되나요? 😋

블로글러 2025. 2. 3. 22:49

Keycloak으로 로그인 과정을 거치면, 성공적으로 인증되었다는 증거인 토큰과 사용자 정보를 다양한 방식으로 활용할 수 있습니다.
일반적으로 OpenID Connect(OIDC) 또는 OAuth2를 통해 Access Token, ID Token(선택적으로 Refresh Token)이 발급되며, 이를 통해 사용자 정보나 세션 ID 등을 확인할 수 있습니다.

아래에서 Keycloak 인증 흐름을 다시 간단히 짚은 뒤, 어떤 정보를 확인할 수 있는지 구체적으로 살펴보겠습니다.

1. Keycloak 로그인(인증) 흐름 간단 요약

사용자가 클라이언트 애플리케이션(웹/모바일 등)에 접근
인증이 필요한 상황이면, 애플리케이션은 Keycloak으로 인증 요청을 보냄 (리디렉션)
Keycloak 로그인 폼에서 사용자 아이디/비밀번호 입력 (또는 MFA)
인증 성공 시, Keycloak은 토큰(Access Token, ID Token 등)을 애플리케이션에게 반환
애플리케이션은 토큰을 검증하거나 UserInfo Endpoint 등을 통해 사용자 정보를 조회해 세션을 생성

이 때, 애플리케이션은 토큰을 가지고 사용자 세션에 필요한 정보를 담아둘 수도 있고, SPA처럼 클라이언트가 직접 토큰을 저장할 수도 있습니다.

2. Keycloak이 반환하는 주요 정보

Keycloak은 기본적으로 OIDC 표준에 맞춰 다양한 정보를 담은 토큰을 제공합니다. 예를 들어:

Access Token
- 발급 목적: API 호출 시 권한 검증(인가) 용도로 사용
- 내용:
  - sub: 사용자 식별자(주로 UUID). ‘subject’라는 의미
  - aud: 이 토큰이 유효한 리소스 서버(클라이언트 ID 등)
  - iss: 토큰 발급자(issuer), 보통 https://<keycloak-host>/realms/<realm-name>
  - exp, iat: 만료 시각, 발급 시각
  - 사용자 역할(roles), 권한(scope) 등이 포함될 수 있음
- 만료 시간: 보통 짧게 설정 (예: 5분 ~ 15분)
ID Token (OIDC 사용 시)
- 발급 목적: 사용자 인증 완료를 알리는 신분(Identity) 토큰
- 내용:
  - sub: 사용자 식별자
  - name, email 등 프로필 정보
  - preferred_username, given_name, family_name 등의 표준 클레임
  - sid: 세션 ID(서버 세션 식별), Keycloak이 생성한 세션을 나타낼 수 있음
  - acr: 인증 수단 레벨(예: MFA 사용 여부)
- 만료 시간: Access Token보다는 조금 길 수 있으나, 일반적으로 5분 ~ 15분 정도로 설정
Refresh Token (선택적으로 발급)
- 발급 목적: Access Token 만료 시, 다시 로그인을 요구하지 않고 새로운 Access Token을 발급받기 위함
- 내용: Access Token보다는 사용 정보가 적고, 주로 만료 시간과 리프레시를 위한 식별자 정보가 담겨 있음
- 만료 시간: 보통 더 길게 설정 (예: 30분 ~ 24시간 등)

User Info Endpoint (OIDC 표준)

동작 원리: Access Token을 가지고 Keycloak의 /realms/{realm-name}/protocol/openid-connect/userinfo 엔드포인트에 요청을 보내면, 사용자 정보 JSON을 반환

반환 내용(예시):

{
  "sub": "12345678-90ab-cdef-1111-222233334444",
  "email": "user@example.com",
  "preferred_username": "user",
  "name": "홍길동",
  "given_name": "길동",
  "family_name": "홍"
  // 추가 클레임이 있을 수 있음
}

✨ 정리하면, Keycloak 인증 후 애플리케이션에 돌아올 때 주로 토큰과 (토큰 안에 있는) 사용자 정보를 얻게 됩니다.

사용자 ID(sub)나 Email, Username, Roles 등
세션 ID(sid) 또는 session_state라는 클레임(세션 식별자)
클라이언트 측 또는 서버 측 세션을 어떻게 구성하느냐에 따라 사용자가 애플리케이션 안에서 최종적으로 어떤 세션 정보를 갖고 있는지는 달라짐

3. 세션 ID와 사용자 정보는 어디서 확인할 수 있나요?

1) 토큰 내부 클레임

ID Token 안에 sid, sub, name, email 등의 정보가 들어 있습니다.
Access Token에도 sub(사용자 식별자), preferred_username, roles 같은 정보가 포함될 수 있습니다.

2) Spring Security (예: Spring Boot 환경)에서의 세션

Keycloak으로부터 받은 토큰을 검증 후, SecurityContext나 HttpSession에 사용자 정보를 저장합니다.
- 예: SecurityContextHolder.getContext().getAuthentication() 를 통해 Principal 정보 조회 가능
- Principal 안에는 username, authorities(역할/권한) 등이 들어 있으며, 이는 ID Token/Access Token 정보를 바탕으로 매핑된 것입니다.
이 세션 ID는 애플리케이션 내부 세션 ID(예: JSESSIONID)로 관리됩니다.
- Keycloak의 세션 ID(토큰 내 sid)와는 별도일 수 있습니다(혼동 주의).

3) Keycloak Admin 콘솔에서의 세션

Keycloak Admin 콘솔 → Sessions 메뉴에서 사용자가 발급받은 세션 목록을 확인할 수 있습니다.
여기에는 Keycloak 자체가 관리하는 Session ID, User 정보, Client(애플리케이션) 정보 등이 표시됩니다.

4. 실제 예시 코드 (간단 스니펫)

아래는 Spring Boot에서 Keycloak으로 인증 후, 컨트롤러에서 사용자 정보를 꺼내보는 예시입니다.

@RestController
public class UserController {

    @GetMapping("/user-info")
    public Map<String, Object> getUserInfo(Principal principal) {
        // principal에는 인증된 사용자 정보가 들어 있음
        // Spring Security와 Keycloak Adapter 연동 시, KeycloakPrincipal 객체일 수 있음.

        if(principal instanceof KeycloakPrincipal) {
            KeycloakPrincipal<KeycloakSecurityContext> kp = (KeycloakPrincipal<KeycloakSecurityContext>) principal;
            KeycloakSecurityContext context = kp.getKeycloakSecurityContext();

            // Access Token
            AccessToken token = context.getToken();

            // 사용자 기본 정보
            String username = token.getPreferredUsername();
            String email = token.getEmail();
            String userId = token.getSubject();  // sub

            // 세션 ID
            String sessionId = token.getSessionState(); // session_state

            Map<String, Object> userInfo = new HashMap<>();
            userInfo.put("username", username);
            userInfo.put("email", email);
            userInfo.put("userId", userId);
            userInfo.put("sessionId", sessionId);
            return userInfo;
        }

        // principal 타입이 다를 경우
        return Collections.singletonMap("message", "Not a KeycloakPrincipal");
    }
}

token.getSessionState()로 가져오는 값이 Keycloak 세션 상태(session_state)이며, 이는 Keycloak이 내부적으로 발급하는 세션 식별자입니다.

session_state: Keycloak 토큰에서 세션을 나타내는 값 (OIDC 표준 sid 클레임과 다르게, Keycloak 자체 필드)
sid: OIDC 스펙에 정의된 sid 클레임으로, Keycloak 8.x 이후 버전에서는 sid 클레임도 함께 활용됩니다.

5. 주의할 점 ⚠️

토큰 내부 정보 vs. 서버 세션 정보
- Keycloak의 ID Token, Access Token에 들어있는 sid(또는 session_state)는 Keycloak 측 세션 식별자
- Spring 등 애플리케이션 세션은 별도의 세션 ID(JSESSIONID)를 가질 수 있음 → 이 둘을 혼동하지 않도록 주의
보안 고려
- 토큰은 민감한 정보를 담고 있으므로, HTTPS를 사용하고, 토큰 탈취 방지에 유의
- Refresh Token 취급 시 만료 정책, 저장 위치 등을 신중하게 다뤄야 함
사용자 정보(UserInfo) 활용
- 토큰에 포함되지 않는 커스텀 속성은 UserInfo Endpoint 또는 Keycloak Custom Mapper(클레임 매퍼) 기능을 통해 넣을 수 있음
- 필요에 따라 Keycloak Admin 콘솔에서 User Attributes를 정의하고, 클라이언트에서 매핑 설정 가능

6. 마치며 🎁

정리하자면, Keycloak 인증 후에는 Access Token과 ID Token(그리고 필요하면 Refresh Token)을 통해 사용자 정보, 세션 식별자, 역할/권한 등을 얻을 수 있습니다.

ID Token 안에는 사용자 프로필 정보(sub, name, email)와 sid(세션 식별자) 같은 클레임이 포함됩니다.
Access Token에는 권한/역할, 만료 시간 등의 정보가 담겨 API 호출 권한 검증에 활용됩니다.
애플리케이션은 이 정보를 이용해 자체적으로 세션을 구성하고, 사용자의 인증 상태를 관리합니다.

이 모든 과정을 통해 사용자 편의성과 보안을 동시에 달성할 수 있습니다.
Keycloak은 토큰 기반 인증(SSO)의 핵심 요소와 OIDC 표준을 잘 구현하고 있으므로, 다양한 확장과 커스터마이징이 가능합니다.
"한 번의 인증으로 사용자에게 원활한 로그인 경험을 제공하고, 중앙 집중형으로 보안과 계정을 관리"하는 데 Keycloak이 큰 도움을 줄 것입니다!

🔗 참고 자료

728x90

저작자표시 비영리 변경금지

'100===Dev Ops > SSO' 카테고리의 다른 글

SSO(Single Sign-On) 구축 😋 (0)	2025.02.03
Keycloak SSO 연동 방법 😋 (0)	2025.02.03

현재글Keycloak 인증 후 어떤 정보가 반환되나요? 😋

메모리허브