PHP 애플리케이션 연동

Keycloak과 PHP 애플리케이션을 연동하면 OpenID Connect 또는 OAuth 2.0을 활용해 인증·인가 기능을 간편하게 구현할 수 있다. 이 장에서는 Keycloak에서 PHP 애플리케이션을 위한 클라이언트를 설정하고, PHP 코드 측에서 인증 흐름을 처리하는 기본 절차를 다룬다.

Keycloak 클라이언트 설정

Keycloak에서 PHP 애플리케이션을 연동하려면, 먼저 Keycloak 관리자 콘솔에서 클라이언트를 생성해야 한다.

• 클라이언트 생성 시 프로토콜을 openid-connect로 설정한다.

• 클라이언트 ID는 PHP 애플리케이션에 대응되는 임의의 문자열을 사용한다.

• ‘공개(Open Access Type)’ 또는 ‘기밀(Confidential)’ 설정을 선택한다.

  • 웹 서버에서 클라이언트 시크릿(secret)을 안전하게 보관할 수 있다면 기밀(Confidential) 클라이언트를 사용할 수 있다.

• 유효한 리디렉션 URI(Valid redirect URIs)를 PHP 애플리케이션의 콜백 경로와 일치하도록 설정한다. 예를 들어, https://example.com/callback 형태로 지정한다.

• 로그인 흐름에 필요한 인증 방식을 선택한다. 일반적으로 OAuth 2.0 표준의 Authorization Code Flow를 사용한다.

설정 완료 후, 필요한 경우 클라이언트 시크릿도 확인한다. 이는 PHP 애플리케이션에서 토큰을 교환하거나 검증할 때 사용된다.

PHP 라이브러리 선택

PHP 애플리케이션 측에서는 Keycloak을 직접 구현하기보다는 OpenID Connect 또는 OAuth 2.0 표준을 지원하는 라이브러리를 사용하는 것이 편리하다. 대표적으로 다음과 같은 라이브러리가 있다.

• jumbojett/OpenID-Connect-PHP

• keycloak-php (커뮤니티에서 관리하는 비공식 라이브러리)

• 기타 OAuth 2.0 호환 라이브러리

이 중 OpenID-Connect-PHP 라이브러리를 예시로 들어 설명한다.

PHP 애플리케이션 구성

PHP 애플리케이션에서 Keycloak 인증을 적용하기 위해 다음 단계를 거친다.

라이브러리 설치

Composer를 사용해 OpenID-Connect-PHP 라이브러리를 설치한다.

composer require jumbojett/openid-connect-php

환경 설정

.env 파일이나 별도의 환경 설정 파일에 Keycloak 서버 정보 및 클라이언트 정보를 지정한다. 예시는 다음과 같다.

KEYCLOAK_BASE_URL=https://my-keycloak-server.example.com
KEYCLOAK_REALM=myrealm
KEYCLOAK_CLIENT_ID=my-php-client
KEYCLOAK_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
KEYCLOAK_REDIRECT_URI=https://my-php-app.example.com/callback

로그인 흐름 구현

아래 예시 코드는 OpenID-Connect-PHP 라이브러리를 사용해 Keycloak 로그인을 처리하는 간단한 방식을 보여준다.

<?php
require_once 'vendor/autoload.php';

use Jumbojett\OpenIDConnectClient;

session_start();

$oidc = new OpenIDConnectClient(
    getenv('KEYCLOAK_BASE_URL') . '/realms/' . getenv('KEYCLOAK_REALM'),
    getenv('KEYCLOAK_CLIENT_ID'),
    getenv('KEYCLOAK_CLIENT_SECRET')
);

$oidc->setRedirectURL(getenv('KEYCLOAK_REDIRECT_URI'));
$oidc->addScope('openid profile email'); // 필요한 범위(scope) 설정

// 로그인 처리
if (!isset($_SESSION['user_logged_in'])) {
    // 사용자가 아직 로그인하지 않았다면 인증 요청
    $oidc->authenticate();
    
    // 인증 성공 후 액세스 토큰과 유저 정보 확인
    $accessToken =$oidc->getAccessToken();
    $userInfo =$oidc->requestUserInfo();
    
    // 세션에 로그인 상태 저장
    $_SESSION['user_logged_in'] = true;
    $_SESSION['user_email'] =$userInfo->email;
    $_SESSION['access_token'] =$accessToken;
}

// 이미 로그인된 상태라면 이후 비즈니스 로직 처리
echo "안녕하라, " . $_SESSION['user_email'] . "님!";

1. OpenIDConnectClient 객체를 생성할 때 Keycloak 서버 및 클라이언트 정보를 설정한다.

2. 사용자 인증이 필요하면 authenticate() 메서드를 통해 Keycloak 로그인 페이지로 리다이렉트한다.

3. 사용자가 성공적으로 로그인하면, 콜백 URL에서 액세스 토큰을 획득하고 사용자 정보를 가져온다.

4. 세션에 사용자 상태를 저장한 뒤, 애플리케이션 내부에서 인증된 사용자에게 서비스를 제공한다.

콜백 처리

위 예시에서는 authenticate() 내부적으로 자동으로 콜백을 처리하지만, 상황에 따라 콜백 경로를 별도로 구현해야 할 수도 있다. 그런 경우, 콜백 PHP 파일에서 다음과 같은 로직을 추가한다.

<?php
require_once 'vendor/autoload.php';

use Jumbojett\OpenIDConnectClient;

session_start();

$oidc = new OpenIDConnectClient(
    getenv('KEYCLOAK_BASE_URL') . '/realms/' . getenv('KEYCLOAK_REALM'),
    getenv('KEYCLOAK_CLIENT_ID'),
    getenv('KEYCLOAK_CLIENT_SECRET')
);

$oidc->setRedirectURL(getenv('KEYCLOAK_REDIRECT_URI'));
$oidc->addScope('openid profile email');

// Keycloak에서 콜백이 들어왔을 때 토큰 교환
$oidc->authenticate();

// 사용자 정보를 가져와 세션에 저장
$userInfo =$oidc->requestUserInfo();
$_SESSION['user_logged_in'] = true;
$_SESSION['user_email'] =$userInfo->email;
$_SESSION['access_token'] =$oidc->getAccessToken();

// 이후 리다이렉트 혹은 다음 로직 처리
header('Location: /');
exit();

토큰 검증

Keycloak에서 발급된 ID 토큰이나 액세스 토큰을 서버 측에서 검증하려면 다음 사항을 확인한다.

• 토큰에 서명된 키가 Keycloak 서버의 공개 키(Realm Public Key)와 일치하는지 확인한다.

• 토큰의 iss, aud, exp 등 표준 클레임이 정상적인 값인지 확인한다.

• 필요에 따라 토큰의 특정 클레임(예: roles)을 점검해 접근 권한을 제어한다.

오픈소스 라이브러리를 사용하면 이러한 검증 로직이 대부분 자동 처리된다. 하지만 민감 정보 보호나 보안 검증을 위해, 내부적으로 어떠한 검증이 이뤄지는지 파악해 두는 것이 중요하다.

역할(Role) 기반 접근 제어

Keycloak에서 사용자를 특정 역할(Role)에 할당한 뒤, PHP 애플리케이션은 토큰의 realm_access 클레임 내에 있는 역할 정보를 읽어 접근을 제어할 수 있다. 예시로, 관리자 권한이 필요한 페이지라면 다음과 같은 방식으로 검사한다.

if (!isset($_SESSION['access_token'])) {
    // 로그인이 필요
    header('Location: /login.php');
    exit();
}

$decoded = json_decode(base64_decode(explode('.',$_SESSION['access_token'])[1]), true);

if (!in_array('admin', $decoded['realm_access']['roles'])) {
    // 권한 없음
    http_response_code(403);
    echo "권한이 없다.";
    exit();
}

// 관리자 권한이 있는 경우에만 이후 로직 실행
echo "관리자 페이지에 접근하였다.";

이런 식으로 토큰의 페이로드를 확인해 사용자가 적절한 역할을 보유하고 있는지 검증한 뒤, 각 역할별 리소스 접근을 제한할 수 있다.

세션 및 자동 로그아웃 관리

Keycloak 세션은 Keycloak 서버가 관리하고, PHP 세션은 PHP 애플리케이션에서 관리한다. Keycloak에서 로그아웃이 일어났을 때 애플리케이션에도 이를 반영하려면 백채널 로그아웃(Backchannel Logout)이나 프론트채널 로그아웃(Frontchannel Logout)을 설정해야 한다.

단순히 서버 측 세션을 종료하는 방식을 쓰려면, 로그아웃 요청 시 Keycloak에 세션 종료를 알리고, PHP 애플리케이션 세션도 함께 파기한다. 예시로, 로그아웃 동작을 처리하는 코드는 다음과 같다.

<?php
session_start();
session_destroy();

$keycloakLogoutUrl = getenv('KEYCLOAK_BASE_URL')
    . '/realms/' . getenv('KEYCLOAK_REALM')
    . '/protocol/openid-connect/logout'
    . '?redirect_uri=' . urlencode('https://my-php-app.example.com');

header('Location: ' . $keycloakLogoutUrl);
exit();

정리

PHP 애플리케이션과 Keycloak을 연동하면 OpenID Connect, OAuth 2.0 표준에 기반한 안전하고 확장성 있는 인증 인프라를 갖출 수 있다. Keycloak 관리자 콘솔에서 설정한 클라이언트 정보를 PHP 라이브러리에 전달하고, 로그인·콜백·로그아웃 흐름을 코드에 반영하면 전반적인 로그인 프로세스를 쉽게 구성할 수 있다. 토큰 검증과 역할 기반 접근 제어 같은 추가 보안 설정을 통해, PHP 애플리케이션 전반의 보안 수준을 크게 높일 수 있다.