NGINX Plus

Okta를 사용한 Single Sign-On

NGINX Plus 에서 Rroxy하는 애플리케이션에 대해 Okta로 Single Sign-On(SSO)을 활성화하는 방법을 알아보세요.

이 문서는 NGINX Plus R15 이상에 적용됩니다.

NGINX Plus 를 Okta 및 OpenID Connect와 함께 사용하여 Proxy된 애플리케이션에 대해 Single Sign-On(SSO)을 활성화할 수 있습니다. 이 가이드의 단계에 따라 OpenID Connect를 인증 메커니즘으로, Okta를 IdP( identity provider)로, NGINX Plus를 신뢰 당사자로 사용하여 SSO를 설정하는 방법을 배우게 됩니다.

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

목차

1. 전제 조건
2. NGINX Plus 및 NJS 모듈 설치
3. Okta 구성
3-1. 웹 앱 연동 설정
3-2. Okta 앱 클라이언트 자격 증명 얻기
3-3. Okta 애플리케이션 액세스 관리
4. NGINX Plus 설정
4-1. NGINX OpenID Connect 구성
4-2. JSON Web Key 인증 설정
4-3. 로컬 파일을 사용하여 JWK 인증 설정하기
5. 설정 테스트

1. 전제 조건

이 가이드의 단계를 완료하려면 다음 사항이 필요합니다.

  • Okta 관리자 계정이 필요합니다.
  • NGINX Plus 구독이 활성화되어 있어야 합니다.
  • NGINX JavaScript 모듈(njs) – njs 모듈은 NGINX Plus와 Okta 간의 상호 작용을 처리합니다.
  • NGINX Plus를 설치한 호스트 머신에 jq를 설치합니다.

2. NGINX Plus 및 NJS 모듈 설치

1. 아직 NGINX Plus를 설치하지 않은 경우, NGINX Plus 관리자 가이드의 단계에 따라 설치하세요.

2. njs 설치 가이드의 단계에 따라 NGINX JavaScript 모듈을 설치합니다.

3. NGINX Plus 구성의 최상위(“main”) 구성 컨텍스트(/etc/nginx/nginx.conf)에 다음 지시문을 추가하여 njs 모듈을 로드합니다.

load_module modules/ngx_http_js_module.so;

3. Okta 구성

이 섹션의 단계에 따라 NGINX Plus용 새 애플리케이션을 생성하세요.

Note: 이 섹션에는 발행 시점의 Okta 웹 인터페이스 상태를 반영하는 이미지가 포함되어 있습니다. 실제 Okta GUI는 여기에 표시된 예와 다를 수 있습니다. 이 가이드를 참조로 삼아 필요에 따라 현재 Okta GUI에 맞게 지침을 조정하세요.

이 섹션에서는 Okta Workforce Identity SSO 제품에 대해 설명합니다. 이 작업을 완료하려면 Okta에서 조직에 대한 관리자 액세스 권한이 필요합니다. Okta Customer Identity 제품을 사용하는 경우 환경이 다소 다를 수 있습니다.

새 Okta 웹 애플리케이션 생성

1. okta.com에서 Okta에 로그인하세요.

2. 사용자 이름 옆에 있는 Admin 버튼을 선택하여 관리자 콘솔에 액세스합니다.

3. 관리자 대시보드의 왼쪽 탐색 메뉴에서 Applications을 선택합니다.

4. Applications 페이지에서 Create App Integration 버튼을 선택합니다.

5. Create a new app integration 창에서 다음 값을 정의한 후 Next을 선택합니다.

  • Sign-in method: OIDC – OpenID Connect
  • Application type: Web Application
image showing the Create a new app integration window in the Okta UI, with OIDC and Web Application options selected

3-1. 웹 앱 연동 설정

Okta 웹 인터페이스의 New Web App Integration 페이지에서 다음 정보를 입력한 다음 Save을 선택합니다.

필드설명Example Value
App integration nameOpenID Connect 신뢰 당사자의 이름입니다. Okta에서는 이를 “애플리케이션”이라고 합니다.NGINX-Plus
Sign-in redirect URIs포트 번호를 포함하여 /_codexch로 끝나는 NGINX Plus 인스턴스의 URI입니다.https://my-nginx.example.com:443/_codexch
Sign-out redirect URIsThe URI to redirect users to after logging out.
This is an optional field with a default value of http://localhost:8080.
⠀∙  HTTP(80) 또는 HTTPS(443)의 기본 포트를 사용하더라도 포트는 항상 필수입니다.
⠀∙  Production 환경에서는 SSL/TLS(443)를 사용할 것을 강력히 권장합니다.		예제에서는 기본값을 제거했습니다.
Controlled access 애플리케이션에 액세스할 수 있는 사용자를 제어합니다.“조직의 모든 사람이 액세스할 수 있도록 허용”
사용 사례에 적합한 값을 선택해야 합니다.
Okta Create OpenID Connect Integration

3-2. Okta 앱 클라이언트 자격 증명 얻기

신청서 작성을 완료하면 Okta 신청서 페이지가 표시됩니다. 여기에서 Okta 애플리케이션의 클라이언트 자격 증명을 확인할 수 있습니다.

Image showing the application landing page in Okta, which contains the Client Credentials for the application.

나중에 이 정보를 찾아야 하는 경우, 위에 설명된 대로 Okta 관리자 계정에 로그인하고 왼쪽 메뉴에서 Applications을 선택한 다음 해당 애플리케이션을 선택하세요.

애플리케이션의 Client ID와 Client secret을 기록해 두세요. NGINX Plus를 구성할 때 이 값이 필요합니다.

3-3. Okta 애플리케이션 액세스 관리

Okta 애플리케이션에 액세스할 수 있는 사용자 및 그룹을 변경하려면 다음과 같이 하세요.

1. 위에서 설명한 대로 관리자로 Okta에 로그인합니다.

2. 왼쪽 메뉴에서 Applications을 선택한 다음 애플리케이션을 선택합니다.

3. 애플리케이션의 Assignments 탭을 선택합니다.

여기에서 조직에서 이 애플리케이션에 대한 액세스 권한이 부여된 사용자를 관리할 수 있습니다.

4. NGINX Plus 설정

이 섹션의 단계를 수행하여 NGINX Plus를 OpenID Connect 신뢰 당사자로 설정합니다.

4-1. NGINX OpenID Connect 구성

1. nginx-openid-connect GitHub Repository를 Clone하거나 Repo 파일을 다운로드합니다.

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

2. 다음 파일을 NGINX Plus가 설치된 호스트 머신의 /etc/nginx/conf.d 디렉터리에 복사합니다.

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

3. Okta 구성에서 권한 부여 Endpoint, 토큰 Endpoint 및 JSON Web Key(JWK) 파일에 대한 URL을 가져옵니다.

터미널에서 다음 curl 명령을 실행합니다.

Tip: 전체 구성을 쉽게 읽을 수 있는 형식으로 출력하려면 출력을 jq로 Pipe하는 것이 좋습니다.

아래 예제의 출력은 관련 필드만 표시하도록 축약된 것입니다.

curl https://<username>-admin.okta.com/.well-known/openid-configuration | jq
...
{
    "authorization_endpoint": "https://<username>.okta.com/oauth2/v1/authorize",
    ...
    "jwks_uri": "https://<username>.okta.com/oauth2/v1/keys",
    ...
    "token_endpoint": "https://<username>.okta.com/oauth2/v1/token",
 ...
 }

4. OpenID Connect 구성 파일(/etc/nginx/conf.d/openid_connect_configuration.conf)에 IdP에 대한 올바른 값을 추가합니다.

이 파일에는 map{ } 블록에 있는 하나 이상의 IdP에 대한 기본 구성이 포함되어 있습니다. IdP 구성에 맞게 map…$oidc_ 블록을 적절히 수정해야 합니다.

  • 이전 단계에서 반환된 정보를 사용하여 $oidc_authz_endpoint, $oidc_token_endpoint 및 $oidc_jwt_keyfile 값을 정의합니다.
  • map…$oidc_logout_redirect에 정의된 URI를 클라이언트가 /logout 위치를 요청한 후 표시해야 하는 리소스(예: 홈페이지)의 URI로 변경합니다.
  • $oidc_hmac_key에 고유하고 길며 안전한 문구를 설정하여 Nonce 값을 예측할 수 없도록 하세요.

4-2. JSON Web Key 인증 설정

NGINX Plus는 이전 섹션에서 실행한 curl 명령의 출력에 jwks_uri로 보고된 URL에서 직접 JWK 파일을 읽을 수 있습니다.

Note: NGINX Plus R16 이하 버전을 사용하는 경우 로컬 파일을 사용하여 JWK 권한 부여 설정을 참조하세요.

다음 단계에 따라 URI를 사용하여 JWK 파일에 액세스하도록 NGINX Plus를 설정합니다.

1. /etc/nginx/conf.d/frontend.conf 파일에서 auth_jwt_key_file 지시문을 제거(또는 주석 처리)합니다.

2. auth_jwt_key_request 지시문의 주석 처리를 해제합니다.

매개변수 /_jwks_uri는 OpenID Connect 구성 파일(/etc/nginx/conf.d/openid_connect_configuration.conf)에서 이미 설정한 $oidc_jwt_keyfile 변수의 값을 참조합니다.

4-3. 로컬 파일을 사용하여 JWK 인증 설정하기

NGINX Plus R16 및 이전 버전에서는 NGINX Plus가 URI를 통해 JWK 파일에 액세스할 수 없습니다. 대신 JWK 파일이 로컬 디스크에 있어야 합니다.

로컬 파일을 사용하여 JWK 인증을 설정하려면 아래 단계를 따르세요.

1. jwks_uri 필드에 있는 JWK 파일의 JSON 콘텐츠를 로컬 파일로 복사합니다. 예: /etc/nginx/my_okta_jwk.json

2. /etc/nginx/conf.d/frontend.conf에서 설정된 $oidc_jwt_keyfile 지시문의 두 번째 매개변수를 JWK 파일의 로컬 파일 경로로 변경합니다.

3. 일반적으로 /etc/nginx/nginx.conf에 있는 NGINX Plus 구성의 user 지시문로 지정된 사용자에게 JWK 파일에 대한 읽기 권한이 있는지 확인합니다.

5. 설정 테스트

1. 브라우저에서 NGINX Plus 인스턴스의 주소를 입력합니다. 아래 예시와 같이 okta 로그인 페이지로 이동합니다.

2. 조직에 속한 사용자의 자격 증명을 사용하여 로그인해 보세요.

Note: 사용자 그룹에 대한 액세스를 제한한 경우 애플리케이션에 액세스할 수 있는 사용자를 선택해야 합니다.