DEVOCEAN

SSO 연동 샘플 애플리케이션 구성하기: 실전 가이드

이번 글에서는 Keycloak을 활용하여 SSO(Single Sign-On) 기능을 연동할 수 있는 샘플 애플리케이션을 구성하는 방법을 자세히 안내하겠습니다.

이전 가이드에서 Keycloak의 설치와 기본 설정을 완료하셨다면, 이번에는 실제 애플리케이션과 Keycloak을 연동하여 SSO 환경을 구축하는 과정을 함께 살펴보겠습니다.

[연재순서]

1. eksctl로 손쉽게 시작하는 Kubernetes 클러스터 및 노드그룹 생성 방법

2. 완벽한 HTTPS 보안: Ingress 컨트롤러와 Let's Encrypt으로 무료 인증서 설정하기

3. Keycloak 설치부터 설정까지: SSO를 위한 첫걸음

4. SSO 연동 샘플 애플리케이션 구성하기: 실전 가이드

5. SSO 연동 테스트: Keycloak과 애플리케이션의 완벽한 통합

샘플 애플리케이션

SSO(Single Sign-On)를 성공적으로 구현하려면 Keycloak과 연동할 애플리케이션을 미리 준비해야 합니다.

이번 예제에서는 간단한 웹 애플리케이션을 사용하여 Keycloak의 인증 기능을 연동하는 방법을 살펴보겠습니다.

본 가이드에서는 Keycloak 공식 문서에서 제공하는 샘플 중 Node.js로 구성된 샘플 애플리케이션을 활용하여 SSO 연동 테스트 환경을 구성하겠습니다.

이를 통해 Keycloak과 애플리케이션 간의 인증 흐름을 보다 쉽게 이해하고 실습할 수 있도록 안내드리겠습니다.

git clone https://github.com/keycloak/keycloak-quickstarts.git
cd keycloak-quickstarts/nodejs/resource-server

샘플 애플리케이션에서는 기본적으로 3개의 Endpoint가 오픈되어 있습니다.

• http://localhost:3000/public - 인증이 필요하지 않습니다.

• http://localhost:3000/secured User 이 있는 사용자가 호출할 수 있습니다.

• http://localhost:3000/admin Admin 역할 이 있는 사용자가 호출할 수 있습니다.

keycloak.json 파일 수정

KEYCLOAK_AUTH_SERVER : Keycloak 인증 서버의 주소를 입력 (ex: https://keycloak.cloudradar.kr)

KEYCLOCK_CLIENT_SECRET : Keycloak > Reamls 선택(quickstart) > Client (nodejs-app) > Credentials

{
  "realm": "quickstart",
  "auth-server-url": "<< KEYCLOAK_AUTH_SERVER >>",
  "ssl-required": "external",
  "resource": "nodejs-app",
  "credentials": {
    "secret": "<< KEYCLOCK_CLIENT_SECRET >>"
  },
  "confidential-port": 0,
  "policy-enforcer": {}
}

Client Credentials 가져오기

이전 가이드에서 생성한 클라이언트의 Secret을 복사하여 keycloak.json 파일에 << KEYCLOCK_CLIENT_SECRET >> 부분을 대체합니다.

app.js 내용 추가

Keycloak은 인증이 필요한 요청을 처리할 때 세션 데이터를 사용합니다. 이 데이터는 다음과 같은 정보를 포함합니다.

• 사용자의 인증 상태

• 액세스 토큰 및 리프레시 토큰

• 인증 과정에서 발생하는 임시 데이터 (ex: CSRF 토큰)

memoryStore 는 이러한 세션 데이터를 애플리케이션 서버의 메모리에 저장하는 간단한 방식입니다.

keycloak-connect 라이브러리는 세션 관리를 필요로 하며, 이를 위해 Express 애플리케이션과 함께 세션 저장소를 설정해야 합니다.

Keycloak은 세션 저장소를 활용하여 사용자가 로그인한 상태를 추적하고, 매번 Keycloak 서버로 인증 요청을 보내지 않도록 효율적으로 관리합니다.

....
const memoryStore = new session.MemoryStore();
app.use(session({
  secret: 'some-random-secret', // 세션에 사용할 임의의 키
  resave: false,
  saveUninitialized: true,
  store: memoryStore,
}));

const keycloak = new Keycloak({ store: memoryStore });
....

이제 설정을 완료하였습니다. 애플리케이션을 가동해볼 차례입니다.

npm install
npm start
> keycloak-resource-server@1.0.0 start
> node app.js
Listening on port 3000.

Protecting resources (참고자료)

리소스 액세스를 위한 권한 인증은 다양한 방식으로 구성할 수 있습니다.

샘플 애플리케이션에 URL 경로를 추가하여 권한 인증을 직접 설정하고 테스트해보세요.

간단한 인증

리소스에 액세스하기 전에 사용자를 인증해야 하도록 하려면 keycloak.protect()의 파라미터 없는 버전을 사용하면 됩니다.

    app.get( '/complain', keycloak.protect(), complaintHandler );

역할 기반 권한 부여

현재 앱에 대한 애플리케이션 역할로 리소스를 보호하려면:

    app.get( '/special', keycloak.protect('special'), specialHandler );

다른 앱 의 애플리케이션 역할로 리소스를 보호하려면 :

    app.get( '/extra-special', keycloak.protect('other-app:special'), extraSpecialHandler );

영역 역할이 있는 리소스를 보호하려면:

    app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );

리소스 기반 권한 부여

리소스 기반 권한 부여를 사용하면 리소스와 해당 특정 메서드/작업을 보호할 수 있습니다.

Keycloak에서 정의된 정책 집합을 기반으로 하여 애플리케이션에서 권한을 외부화합니다.

이는 리소스를 보호하는 데 사용할 수 있는 keycloak.enforcer 메서드를 노출하여 달성됩니다.

    app.get('/apis/me', keycloak.enforcer('user:profile'), userProfileHandler);

keycloak-enforcer방법은 response_mode 구성 옵션 값에 따라 두 가지 모드로 작동합니다.

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), userProfileHandler);

response_mode로 설정된 경우 token, 애플리케이션에 전송된 베어러 토큰으로 표현된 주체를 대신하여 서버에서 권한을 얻습니다.

이 경우, Keycloak에서 서버에서 부여한 권한을 사용하여 새 액세스 토큰을 발급합니다. 서버가 예상 권한을 포함하는 토큰으로 응답하지 않으면 요청이 거부됩니다.

이 모드를 사용하는 경우 다음과 같이 요청에서 토큰을 얻을 수 있어야 합니다.

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), function (req, res) {
        const token = req.kauth.grant.access_token.content;
        const permissions = token.authorization ? token.authorization.permissions : undefined;

        // show user profile
    });

애플리케이션이 세션을 사용하고 서버에서 이전 결정을 캐시하고 새로 고침 토큰을 자동으로 처리하려는 경우 이 모드를 선호합니다.

이 모드는 클라이언트 및 리소스 서버 역할을 하는 애플리케이션에 특히 유용합니다.

response_mode(기본 모드) 로 설정된 경우 permissions서버는 새 액세스 토큰을 발급하지 않고 부여된 권한 목록만 반환합니다.

새 토큰을 발급하지 않는 것 외에도 이 방법은 request다음과 같이 서버에서 부여한 권한을 노출합니다.

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'permissions'}), function (req, res) {
        const permissions = req.permissions;

        // show user profile
    });

response_mode사용 여부와 관계없이 keycloak.enforcer방법은 먼저 애플리케이션에 전송된 베어러 토큰 내의 권한을 확인하려고 시도합니다.

베어러 토큰이 이미 예상 권한을 가지고 있는 경우 결정을 얻기 위해 서버와 상호 작용할 필요가 없습니다.

이는 클라이언트가 보호된 리소스에 액세스하기 전에 예상 권한이 있는 액세스 토큰을 서버에서 얻을 수 있는 경우 특히 유용하므로

증분 권한 부여와 같은 Keycloak Authorization Services에서 제공하는 일부 기능을 사용하고 keycloak.enforcer리소스에 대한 액세스를 시행할 때 서버에 대한 추가 요청을 피할 수 있습니다.

기본적으로 정책 시행자는 client_id애플리케이션에 정의된 것을 사용하여(예: 를 통해 keycloak.json) Keycloak Authorization Services를 지원하는 Keycloak의 클라이언트를 참조합니다.

이 경우 클라이언트는 실제로 리소스 서버이므로 공개될 수 없습니다.

테스트해보기

권한이 설정된 페이지 접근

http:/로컬호스트:3000/secured

로그인이 정상적으로 처리되면 다음과 같은 화면을 확인할 수 있습니다.

CLI 로 테스트 해보기

앞서 확인한 것 같이 브라우저를 통해 테스트 해볼 수 있으며, 간단하게 CLI를 통해서도 확인이 가능합니다.

<< KEYCLOAK_SERVER >>: ex) keycloak.cloudradar.kr

<< CLIENT_ID >> : ex) nodejs-app

<< CLIENT_SECRET >> : ex) wXgY2LodZLGfXXX5X4u2gZIQkXzy9T5o

<< USER_NAME >> : alice

<< USER_PASSWORD >> : password

export access_token=$(\curl -X POST https://<< KEYCLOCK_SERVER >>/realms/quickstart/protocol/openid-connect/token \-H 'content-type: application/x-www-form-urlencoded' \-d 'client_id=<< CLIENT_ID >>&client_secret=<< CLIENT_SECRET >>' \-d 'username=<< USER_NAME >>&password=<< USER_PASSWORD >>&grant_type=password' | jq --raw-output '.access_token' \

curl http://localhost:3000/secured -H "Authorization: Bearer "$access_token

결과적으로 서비스에서 다음과 같은 응답이 표시됩니다.

{"message":"secured"}

마무리

이번 가이드에서는 Keycloak을 연동하여 샘플 애플리케이션에서 SSO(Single Sign-On) 기능을 구현하고, 실제로 로그인 과정을 통해 동작을 확인해보았습니다.

Keycloak이 제공하는 강력한 인증 및 권한 관리 기능을 활용하여, 중앙 인증 서버로서 애플리케이션과의 통합을 간단하게 구성할 수 있다는 점을 살펴보셨습니다.

다음 가이드에서는 SSO를 지원하는 다양한 오픈소스 애플리케이션과 Keycloak을 연동해보고,

한 번의 로그아웃으로 모든 애플리케이션에서 세션이 종료되는 Single Sign-Out 기능을 설정하는 방법을 다뤄보겠습니다.

실전 환경에서 더욱 유용하게 활용할 수 있는 내용을 준비했으니 많은 기대 부탁드립니다!

1. eksctl로 손쉽게 시작하는 Kubernetes 클러스터 및 노드그룹 생성 방법

2. 완벽한 HTTPS 보안: Ingress 컨트롤러와 Let's Encrypt으로 무료 인증서 설정하기

3. Keycloak 설치부터 설정까지: SSO를 위한 첫걸음

4. SSO 연동 샘플 애플리케이션 구성하기: 실전 가이드

5. SSO 연동 테스트: Keycloak과 애플리케이션의 완벽한 통합