NGINX Plus

Microsoft Active Directory FS를 사용한 Single Sign-On

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

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

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

목차

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

1. 전제 조건

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

  • On‑Premises 또는 Azure에서 실행 중인 AD FS 배포.
  • 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
  • 다음 지시문은 최상위(” mai”) 구성 컨텍스트인 /etc/nginx/nginx.conf에 포함되어 NGINX JavaScript 모듈을 로드합니다.
load_module modules/ngx_http_js_module.so;

2. AD FS 구성

NGINX Plus용 AD FS 애플리케이션을 만듭니다.

1. AD FS 관리 창을 엽니다. 왼쪽의 탐색 열에서 Application Groups 폴더를 마우스 오른쪽 버튼으로 클릭하고 드롭다운 메뉴에서 Add Application Group를 선택합니다.

Add Application Group Wizard 창이 열립니다. 왼쪽 탐색 열에는 애플리케이션 그룹을 추가하기 위해 완료해야 할 단계가 표시됩니다.

Welcome 단계의 Name 필드에 애플리케이션 그룹 이름을 입력합니다. 여기서는 ADFSSSO를 사용합니다. Template 필드에서 Standalone applications 아래에서 Server application을 선택합니다. Next > 버튼을 클릭합니다.

3. Server application 단계에서

1. Make a note of the value in the **Client Identifier** field. You will add it to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables).<br/>
2. In the **Redirect URI** field, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch**. Here we’re using <span style="white-space: nowrap; color:#666666; font-weight:bolder;">https://my-nginx.example.com:443/\_codexch</span>. Click the <span style="background-color:#e1e1e1; white-space: nowrap; font-weight: bolder"> Add </span> button.

   **Notes:** 

   * For production, we strongly recommend that you use SSL/TLS (port 443).
   * The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443).

3. Next  > 버튼을 클릭합니다.

4. Configure Application Credentials 단계에서 Generate a shared secret 확인란을 클릭합니다. Copy to clipboard 버튼을 클릭하고 클립보드 내용을 파일에 붙여넣어 AD FS가 생성하는 암호를 메모합니다. 이 암호는 NGINX Plus 구성의 4단계에서 NGINX Plus 구성에 추가합니다. Next > 버튼을 클릭합니다.

5. Summary 단계에서 정보가 정확한지 확인하고 이전 단계에서 필요한 사항을 수정한 후 Next > 버튼을 클릭합니다.

3. NGINX Plus 구성

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

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

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

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

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

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

$ curl https://<ADFS-server-address>/oidc/adfs/.well-known/openid-configuration | python -m json.tool
{
 ...
    "authorization_endpoint": "https://<ADFS-server-address>/oidc/adfs/auth",
    ...
    "jwks_uri": "https://<ADFS-server-address>/oidc/adfs/certs",
    ...
    "token_endpoint": "https://<ADFS-server-address>/oidc/adfs/token",
 ...
}

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

  • map $host $oidc_authz_endpoint – 3단계의 authorization_endpoint 값(이 가이드에서는 https://<ADFS-server-address>/oidc/adfs/auth)
  • map $host $oidc_token_endpoint – 3단계의 token_endpoint 값(이 가이드에서는 https://<ADFS-server-address>/oidc/adfs/token)
  • map $host $oidc_client – ADFS 구성 3단계의 Client ID 필드에 있는 값(이 가이드에서는 3e23f0eb-9329-46ff-9d37-6ad24afdfaeb)
  • map $host $oidc_client_secret – AD FS 구성 4단계의 Client secret 필드에 있는 값입니다(이 가이드에서는 NUeuULtSCjgXTGSkq3ZwEeCOiig4-rB2XiW_W).
  • 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. 설정된 $oidc_jwt_keyfile 지시문의 두 번째 매개변수를 3단계의 jwks_uri 필드에 보고된 값으로 변경합니다(이 가이드에서는 https://<ADFS-server-address>/oidc/adfs/certs).
  • NGINX Plus R16 이하 버전에서는 JWK 파일이 로컬 디스크에 있어야 합니다. (원하는 경우 NGINX Plus R17 이상에서도 이 방법을 사용할 수 있습니다.)
    1. 3단계의 jwks_uri 필드에 있는 JWK 파일(이 가이드에서는 https://<ADFS-server-address>/oidc/adfs/certs)의 JSON 콘텐츠를 로컬 파일(예: /etc/nginx/my_adfs_jwk.json)로 복사합니다.
    2. /etc/nginx/conf.d/frontend.conf에서 설정된 $oidc_jwt_keyfile 지시문의 두 번째 매개변수를 로컬 파일 경로로 변경합니다.

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

4. 테스트

브라우저에서 NGINX Plus 인스턴스의 주소를 입력하고 애플리케이션에 액세스할 수 있는 사용자의 자격 증명을 사용하여 로그인을 시도합니다.