NGINX Plus

Amazon Cognito를 사용한 Single Sign-On

Amazon Cognito를 IdP(ID 공급자)로 사용하여 NGINX Plus 에서 Proxy하는 애플리케이션에 대해 OpenID Connect 기반 Single Sign을 사용하도록 설정합니다.

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

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

목차

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

1. 전제 조건

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

  • AWS 계정.
  • 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. Amazon Cognito 구성

Note: 다음 절차는 발행 시점의 Cognito GUI를 반영하고 있지만, GUI는 변경될 수 있습니다. 이 가이드를 참조로 사용하고 필요에 따라 현재 Cognito GUI에 맞춰 조정하세요.

Cognito GUI에서 NGINX Plus용 애플리케이션을 새로 생성합니다.

1. AWS 계정에 로그인하고, AWS 관리 콘솔(console.aws.amazon.com)을 열고, Cognito 대시보드로 이동합니다(예: Services 드롭다운 메뉴의 Security, Identity, & Compliance 섹션에서 Cognito를 클릭).

2. Cognito 대시보드에서 Manage User Pools를 클릭하여 Your User Pools  창을 엽니다. Create a user pool 버튼 또는 강조 표시된 문구를 클릭합니다.

3. Create a user pool 창이 열리면 Pool name 필드에 값을 입력한 다음(이 가이드에서는 nginx-plus-pool), Review defaults 버튼을 클릭합니다.

4. Review 탭이 열리면 하단의 App clients 필드에서 Add app client…를 클릭합니다.

5. App clients 탭이 열리면 Add an app client를 클릭합니다.

6. Which app clients will have access to this user pool? 창이 열리면 App client name 필드에 값(이 가이드에서는 nginx-plus-app)을 입력합니다. Generate client secret 확인란이 선택되어 있는지 확인한 다음 Create app client 버튼을 클릭합니다.

7. 확인 페이지가 열리면 Return to pool details를 클릭하여 Review 탭으로 돌아갑니다. 해당 탭에서 하단의 Create pool 버튼을 클릭합니다. (4단계의 스크린샷에 해당 버튼이 표시되어 있습니다.)

8. 새 사용자 풀이 성공적으로 생성되었는지 확인하기 위해 열리는 세부 정보 페이지에서 Pool Id 필드의 값을 기록해 두었다가 NGINX Plus구성 3단계의 NGINX Plus구성에 추가합니다.

'General settings' tab in Amazon Cognito GUI

9. 왼쪽 탐색 열에서 Users and groups을 클릭합니다. 인터페이스가 열리면 Groups 탭에서 NGINX Plus가 Proxy하는 애플리케이션에 대해 SSO를 사용할 수 있는 사용자(또는 사용자 그룹)를 지정합니다. 자세한 내용은 사용자 만들기, 사용자 가져오기 또는 그룹 추가에 대한 Cognito 설명서를 참조하세요.

'Users and groups' tab in Amazon Cognito GUI

10. 왼쪽 탐색 모음에서 App clients를 클릭합니다. 탭이 열리면 애플리케이션 클라이언트 이름(이 가이드에서는 nginx-plus-app)이 표시된 상자의 Show Details 버튼을 클릭합니다.

'App clients' tab in Amazon Cognito GUI

11. 세부 정보 페이지가 열리면 App client id 및 App client secret 필드의 값을 기록합니다. 이 값은 NGINX Plus구성 3단계에서 NGINX Plus 구성에 추가합니다.

12. 왼쪽 탐색 열에서 App client settings을 클릭합니다. 탭이 열리면 다음 단계를 수행합니다.

  1. Enabled Identity Providers 섹션에서 Cognito User Pool 체크박스를 클릭합니다(모든 선택 상자가 자동으로 선택됨).
  2. Sign in and sign out URLs Callback URL(s) 필드에 포트 번호를 포함하여 /_codexch로 끝나는 NGINX Plus인스턴스의 URI를 입력합니다. 여기서는 https://my-nginx-plus.example.com:443/_codexch 을 사용합니다.

    Note:
    • Production 환경에서는 SSL/TLS(포트 443)를 사용할 것을 강력히 권장합니다.
    • 포트 번호는 HTTP(80) 또는 HTTPS(443)의 기본 포트를 사용하는 경우에도 필수 입력 사항입니다.
  3. OAuth 2.0 섹션에서 Allowed OAuth Flows 아래의 Authorization code grant 체크박스를 클릭하고 Allowed OAuth Scopes 아래의 email, openid 및 profile 체크박스를 클릭합니다.
  4. Save changes 버튼을 클릭합니다.

13. 왼쪽 탐색 열에서 Domain name을 클릭합니다. 탭이 열리면 Amazon Cognito domain 아래의 Domain prefix 필드에 도메인 접두사(이 가이드에서는 my-nginx-plus)를 입력합니다. Save changes 버튼을 클릭합니다.

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

3. 선호하는 텍스트 편집기에서 /etc/nginx/conf.d/frontend.conf를 엽니다. 다음 각 set 지시문의 두 번째 매개변수를 지정된 값으로 변경합니다.

변수는 Amazon Cognito 구성 13단계의 Domain prefix 필드에 있는 전체 값입니다. 이 가이드에서는 https://my-nginx-plus.auth.us-east-2.amazoncognito.com 입니다.

  • set $oidc_authz_endpoint – <My-Cognito-Domain-Name>/oauth2/authorize
  • set $oidc_token_endpoint – <My-Cognito-Domain-Name>/oauth2/token
  • set $oidc_client – Amazon Cognito 구성 11단계의 App client id 필드에 있는 값(이 가이드에서는 2or4cs8bjo1lkbq6143tqp6ist)
  • set $oidc_client_secret - Amazon Cognito 구성 11단계의 App client secret 필드에 있는 값(이 가이드에서는 1k63m3nrcnu...)
  • set $oidc_hmac_key – 고유하고 길며 안전한 문구를 설정합니다.

4. JWK 파일을 구성합니다. 파일의 URL은 다음과 같습니다.

https://cognito-idp.region.amazonaws.com/User-Pool-ID/.well-known/jwks.json

where

  • Region은 3단계에서 사용한 <My-Cognito-Domain-Name> 변수에 있는 것과 동일한 AWS 지역 이름입니다.
  • User-Pool-ID는 Amazon Cognito 구성 8단계의 Pool Id 필드에 있는 값입니다.

이 가이드에서 URL은 다음과 같습니다.

https://cognito-idp.us-east-2.amazonaws.com/us-east-2_mLoGHJpOs/.well-known/jwks.json.

JWK 파일을 구성하는 방법은 사용 중인 NGINX Plus 버전에 따라 다릅니다.

  • NGINX Plus R17 이상에서는 NGINX Plus가 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 지시문의 두 번째 매개변수를 JWK 파일의 URL(https://cognito-idp.../.well-known/jwks.json)로 변경합니다.
  • NGINX Plus R16 이하 버전에서는 JWK 파일이 로컬 디스크에 있어야 합니다. (원하는 경우 NGINX Plus R17 이상에서도 이 방법을 사용할 수 있습니다.)
    1. JWK 파일(https://cognito-idp…/.well-known/jwks.json)의 JSON 콘텐츠를 로컬 파일(예: /etc/nginx/my_cognito_jwk.json)로 복사합니다.
    2. etc/nginx/conf.d/frontend.conf에서 set $oidc_jwt_keyfile 지시문의 두 번째 매개변수를 로컬 파일 경로로 변경합니다.

5. 게시 시점에 Cognito는 OpenID offline_access 범위를 지원하지 않습니다. 텍스트 편집기에서 /etc/nginx/conf.d/openid_connect.server_conf를 열고 10줄의 범위 목록에서 +offline_access를 제거하여 다음과 같이 표시되도록 합니다.

return 302 "$oidc_authz_endpoint?response_type=code&scope=openid+profile+email&client_id=$oidc_clientaws...;

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

4. 테스트

브라우저에서 NGINX Plus 인스턴스의 주소를 입력하고 애플리케이션에 할당된 사용자의 자격 증명을 사용하여 로그인을 시도합니다(Amazon Cognito 구성의 9단계 참조). 스크린샷에 표시된 NGINX 로고는 Cognito UI customization 탭에 추가되었습니다(이 가이드에는 표시되지 않음).