NGINX Plus

Keycloak을 사용한 Single Sign-On

Keycloak을 IdP(identity provider)로 사용하여 NGINX Plus에서 Proxy하는 애플리케이션에 대해 OpenID Connect 기반 Single-Sign을 사용하도록 설정합니다.

이 가이드에서는 NGINX Plus에서 Proxy되는 애플리케이션에 대해 Single Sign-On(SSO)을 사용하도록 설정하는 방법을 설명합니다. 이 솔루션은 인증 메커니즘으로 OpenID Connect를 사용하며, Keycloak을 IdP(identity provider)로, NGINX Plus를 신뢰 당사자로 사용합니다.

GitHub 프로젝트의 Repo에서 NGINX Plus OpenID Connect 통합에 대한 자세한 정보를 확인할 수 있습니다.

목차

1. 전제 조건
2. Keyclloak 구성
3. NGINX Plus 구성
4. 테스트

1. 전제 조건

이 지침은 다음과 같은 사항이 있다고 가정합니다.

  • 실행 중인 Keycloak 서버. 설치 및 구성 지침은 Keycloak 문서를 참조하세요.
  • NGINX Plus 구독 및 NGINX Plus R15 이상. 설치 지침은 NGINX Plus 관리자 가이드를 참조하세요.
  • NGINX Plus와 IdP 간의 상호 작용을 처리하는 데 필요한 NGINX JavaScript 모듈(njs)입니다. NGINX Plus를 설치한 후 운영 체제용 명령어로 모듈을 설치합니다.

Debian 및 Ubuntu의 경우:

$ sudo apt install nginx-plus-module-njs

CentOS, RHEL 및 Oracle Linux의 경우:

$ sudo yum install nginx-plus-module-njs
  • 다음 지시문은 최상위(“main”) 구성 컨텍스트인 /etc/nginx/nginx.conf에 포함되어 NGINX JavaScript 모듈을 로드합니다.
load_module modules/ngx_http_js_module.so;

2. Keyclloak 구성

Note: 다음 단계는 게시 시점의 Keycloak GUI를 반영하지만 GUI는 변경될 수 있습니다. 이 가이드를 참조로 사용하고 필요에 따라 현재 Keycloak GUI에 적응하세요.

Keycloak GUI에서 NGINX Plus용 Keycloak 클라이언트를 생성합니다.

1. Keycloak 관리자 콘솔(http://keycloak-server-address:8080/auth/admin/)에 액세스하여 로그인합니다.

2. 왼쪽 탐색 열에서 Clients를 클릭합니다. Clients 페이지가 열리면 오른쪽 위 모서리에 있는 Create 버튼을 클릭합니다.

3. Add Client 페이지가 열리면 다음 값을 입력하거나 선택한 다음 Save 버튼을 클릭합니다.

  • Client ID – SSO를 사용하도록 설정하는 애플리케이션의 이름입니다(Keycloak에서는 이를 “client”라고 합니다). 여기서는 NGINX-Plus를 사용합니다.
  • Client Protocol – openid-connect.

4. NGINX Plus 페이지가 열리면 Settings 탭에서 이 값을 입력하거나 선택합니다.

Note:

  • Production 환경에서는 SSL/TLS(포트 443)를 사용할 것을 강력히 권장합니다.
  • 포트 번호는 HTTP(80) 또는 HTTPS(443)의 기본 포트를 사용하는 경우에도 필수 입력 사항입니다.

5. Credentials 탭을 클릭하고 Secret 필드에 값을 메모합니다. 이 값을 NGINX Plus 구성하기 4단계의 NGINX Plus 구성 파일에 복사합니다.

6. Roles 탭을 클릭한 다음 열리는 페이지의 오른쪽 상단에 있는 Add Role 버튼을 클릭합니다.

7. Add Role 페이지가 열리면 Role Name 필드에 값을 입력하고(여기서는 nginx-keycloak-role입니다) Save 버튼을 클릭합니다.

8. 왼쪽 탐색 열에서 Users를 클릭합니다. Users 페이지가 열리면 기존 사용자의 이름을 클릭하거나 오른쪽 위 모서리에 있는 Add user 버튼을 클릭하여 새 사용자를 만듭니다. 전체 지침은 Keycloak 설명서를 참조하세요.

9. 사용자(여기서는 user01)에 대한 관리 페이지에서 Role Mappings 탭을 클릭합니다. 페이지가 열리면 Client Roles 드롭다운 메뉴에서 NGINX-Plus를 선택합니다. Available Roles 상자에서 nginx-keycloak-role을 클릭한 다음 상자 아래의 선택한 Add selected 버튼을 클릭합니다. 그러면 스크린샷과 같이 Assigned Roles 및 Effective Roles 상자에 역할이 나타납니다.

3. NGINX Plus 구성

NGINX Plus를 OpenID Connect 신뢰 당사자로 구성합니다.

1. nginx-openid-connect GitHub Repository의 Clone을 생성합니다.

$ git clone https://github.com/nginxinc/nginx-openid-connect

2. Clone에서 /etc/nginx/conf.d로 아래 파일들을 복사합니다.

  • frontend.conf
  • openid_connect.js
  • openid_connect.server_conf
  • openid_connect_configuration.conf

3. Keycloak 구성에서 권한 부여 Endpoint, 토큰 Endpoint 및 JSON Web Key(JWK) 파일에 대한 URL을 가져옵니다. 터미널에서 다음 curl 명령을 실행하여 출력을 지정된 python 명령으로 Pipe하여 전체 구성을 읽기 쉬운 형식으로 출력합니다. 관련 필드만 표시되도록 출력을 요약했습니다.

$ curl https://<keycloak-server-address>/auth/realms/master/.well-known/openid-configuration | python -m json.tool
...
{
    "authorization_endpoint": "https://<keycloak-server-address>/auth/realms/master/protocol/openid-connect/auth",
    ...
    "jwks_uri": "https://<keycloak-server-address>/auth/realms/master/protocol/openid-connect/certs",
    ...
    "token_endpoint": "https://<keycloak-server-address>/auth/realms/master/protocol/openid-connect/token",
 ...
 }

4. 선호하는 텍스트 편집기를 사용하여 /etc/nginx/conf.d/openid_connect_configuration.conf를 엽니다. 다음 map 지시문 각각의 “default” 매개변수 값을 지정된 값으로 변경합니다.

  • map $host $oidc_authz_endpoint – 3단계의 authorization_endpoint 값(이 가이드에서는 https: lhttps://<keycloak-server-address>/auth/realms/master/protocol/openid-connect/auth)입니다.
  • map $host $oidc_token_endpoint – 3단계의 token_endpoint 값(이 가이드에서는 https: https://<keycloak-server-address>/auth/realms/master/protocol/openid-connect/token)입니다.
  • map $host $oidc_client – Keycloak 구성 3단계의 Client ID 필드에 있는 값입니다(이 가이드에서는 NGINX Plus).
  • map $host $oidc_client_secret – Keycloak 구성 5단계의 Secret 필드에 있는 값(이 가이드에서는 w4b32c4b0-f4b3-41d9-a345-2bc0fbfcaaba)
  • map $host $oidc_hmac_key – 고유하고 길며 안전한 문구를 입력합니다.

5. JWK 파일을 구성합니다. 절차는 사용 중인 NGINX Plus 버전에 따라 다릅니다.

  • NGINX Plus R17 이상에서는 3단계에서 jwks_uri로 보고된 URL에서 직접 JWK 파일을 읽을 수 있습니다. etc/nginx/conf.d/frontend.conf를 다음과 같이 변경합니다.
    1. auth_jwt_key_file 지시문을 주석 처리(또는 제거)합니다.
    2. auth_jwt_key_request 지시문의 주석 처리를 해제합니다. (해당 매개변수인 /_jwks_uri는 다음 단계에서 설정한 $oidc_jwt_keyfile 변수의 값을 참조합니다.)
    3. map $host $oidc_jwt_keyfile 지시문의 “default” 매개변수를 3단계의 jwks_uri 필드에 보고된 값으로 변경합니다(이 가이드에서는 https://<keycloak-server-address>/auth/realms/master/protocol/openid-connect/certs).
  • NGINX Plus R16 이하 버전에서는 JWK 파일이 로컬 디스크에 있어야 합니다. (원하는 경우 NGINX Plus R17 이상에서도 이 방법을 사용할 수 있습니다.)
    1. 3단계의 jwks_uri 필드에 있는 JWK 파일(이 가이드에서는 https://<keycloak-server-address>/auth/realms/master/protocol/openid-connect/certs)의 JSON 콘텐츠를 로컬 파일(예: /etc/nginx/my_keycloak_jwk.json)로 복사합니다.
    2. etc/nginx/conf.d/openid_connect_configuration.conf에서 $host $oidc_jwt_keyfile map 지시문의 “default” 매개 변수를 로컬 파일 경로로 변경합니다.

6. NGINX Plus 구성에서 user 지시문으로 지정된 사용자(관례에 따라 /etc/nginx/nginx.conf에 있음)가 JWK 파일에 대한 읽기 권한을 가지고 있는지 확인합니다.

4. 테스트

브라우저에서 NGINX Plus 인스턴스의 주소를 입력하고 NGINX Plus의 역할에 매핑된 사용자의 자격 증명을 사용하여 로그인을 시도합니다(‘Keycloak 구성하기’ 9단계 참조).