NGINX Ingress Controller Okta 연동 API 인증 구현 가이드

이 포스트는 NGINX Plus Ingress Controller 와 Okta 를 연동하여 API 인증을 구현하는 절차를 다룹니다. 이러한 인증 방식을 통해 NGINX Plus Ingress Controller(이하 NGINX Ingress Controller)를 통해 연결되는 클러스터의 엔드포인트에, Okta를 통해 인증된 사용자만 접근할 수 있도록 구성할 수 있습니다.

NGINX Ingress Controller와 Okta를 연동한 API 인증 구현은 OIDC(OpenID Connect)를 활용한 방식으로, NGINX Plus 전용 기능입니다.

목차

1. Okta란?
 1-1. OIDC란?
2. NGINX Ingress Controller 연동을 위한 Okta 구성
3. NGINX Ingress Controller 및 Okta 연동 구성
4. 결론

1. Okta란?

Okta는 클라우드 기반 Identity-as-a-Service(IDaaS) 솔루션으로, 사용자 인증, 인가 등 ID 관리 및 보안을 제공하는 솔루션입니다. Okta는 다음과 같은 특징을 가지고 있습니다.

  • SSO(Single Sign-On): 한 번의 로그인으로 여러 애플리케이션에 접근 가능
  • 다중 인증(MFA, Multi-Factor Authentication): 비밀번호 외에도 앱, SMS, 이메일 등 추가 인증 단계를 거치도록 구성
  • 중앙화된 사용자 관리
  • 다양한 ID 제공자 및 애플리케이션과의 통합
  • OIDC, SAML, OAuth 2.0과 같은 프로토콜 지원

1-1. OIDC란?

OIDC는 인증(Authentication)을 위한 간단하고 안전한 프로토콜로, OAuth 2.0 프로토콜을 기반으로 사용자 인증을 지원하며, ID 토큰을 활용해 사용자 정보(claims)를 제공합니다. ID 토큰은 JWT를 사용하여 사용자 정보를 안전하고 검증 가능한 방식으로 전달합니다.

OIDC 인증 방식의 주요 구성 요소는 다음과 같습니다.

  • 인증 서버: Okta와 같은 ID 제공자
  • 클라이언트: 인증을 요청하는 애플리케이션 (NGINX Ingress Controller)
  • 사용자: 서비스에 접근하려는 사용자

일반적인 OIDC 인증 흐름은 다음과 같습니다.

사용자 > 클라이언트(NGINX Ingress Controller) > 인증 서버(Okta) > 사용자 인증(로그인) > 토큰 발급 > 서비스 접근
  1. 사용자가 클라이언트(웹 애플리케이션, 모바일 앱 등)에 접근합니다.
  2. 클라이언트는 사용자가 인증되지 않았음을 감지하고, 인증을 위해 인증 서버에 리다이렉션합니다.
  3. 인증 서버는 사용자에게 로그인 화면을 제공하고, 사용자가 인증 정보를 제출하면 이를 검증하여 사용자 인증을 수행합니다.
  4. 인증이 성공하면, 인증 서버는 ID 토큰을 발급합니다.
  5. 발급된 토큰을 받은 사용자는 해당 토큰을 사용하여 클라이언트를 통해 서비스에 접근합니다.

2. NGINX Ingress Controller 연동을 위한 Okta 구성

Okta developer에서 계정을 생성 후 진행했습니다.

1. Okta developer 대시보드 좌측의 Applications 항목으로 이동합니다.

2. Create App Integration 버튼을 클릭하여 진행합니다.

NGINX Ingress Controller 연동 Okta 설정
NGINX Ingress Controller 연동 Okta 설정

원하는 이름을 작성합니다.

NGINX Ingress Controller 연동 Okta redirect URI 설정

Sign-in redirect URIs 항목을 NGINX Ingress Controller의 URI 및 /_codexch 경로로 프로토콜, 포트 번호와 함께 작성합니다.
Sign-out redirect URIs 항목은 로그아웃 시 리다이렉트 될 URI로, 기본값은 http://localhost:8080로 설정되어 있으나, 이 포스트에서는 제거했습니다.
Assignments 항목은 Okta의 특정 그룹의 사용자에게만 접근을 허용해야 할 경우 필요에 따라 설정합니다. 이 포스트에서는 Okta의 모든 사용자가 접근할 수 있도록 구성했습니다.

3. 생성 후 클라이언트 ID와 secret을 확인합니다. 이후 Policy/Secret 리소스 생성에 필요합니다.

NGINX Ingress Controller Okta 클라이언트 ID/Secet

3. NGINX Ingress Controller 및 Okta 연동 구성

NGINX Ingress Controller가 배포된 환경에서 진행합니다.
NGINX Ingress Controller의 Deployment 구성 시 OIDC 활성화를 위한 enable-oidc, Okta 도메인의 DNS 조회를 위한 nginx-configmaps Command-line arguments를 활성화합니다.

spec.template.spec.containers:
...
        args:
          - -nginx-plus
          - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
          - -enable-oidc

DNS resolver 설정을 위해 아래 ConfigMap을 사용했습니다. 아래와 같이 구성 시 NGINX Ingress Controller 내부 nginx.conf 파일의 http, stream 블록에 해당 resolver 지시문이 구성됩니다.

nginx-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
  namespace: nginx-ingress
data:
  resolver-addresses: "8.8.8.8"

예시에 사용된 NGINX Ingress Controller Deployment의 전체 yaml 파일 예시는 NGINX STORE GitHub에서 확인하세요.

$ kubectl get po,svc -n nginx-ingress

NAME                                      READY   STATUS    RESTARTS   AGE
pod/nginx-plus-ingress-769f96476f-kgcv9   1/1     Running   0          5d22h

NAME                         TYPE           CLUSTER-IP       EXTERNAL-IP       PORT(S)                      AGE
service/nginx-ingress-lb   LoadBalancer   10.104.142.51    175.196.***.***   80:32169/TCP,443:32643/TCP   6d15h

위와 같이 NGINX Ingress Controller를 Deployment로 배포하고, LoadBalancer 타입 Service로 구성했습니다.

1. Okta에서 확인한 클라이언트 secret을 통해 Kubernetes Secret 리소스를 생성합니다.
Okta의 secret을 base64형식으로 인코딩한 값을 데이터로 사용합니다.

다음 명령어를 통해 문자열을 base64 형식으로 인코딩합니다. your Okta client secret을 복사한 값으로 변경하세요.

$ echo -n "your Okta client secret" | base64

X2E1LUhGdDJWaUppR20taEVZQW9************1NTl2a3pnRHNMNzFJTkU0NEkwX2NhVmw3M0FiU01qSlhPUQ==
secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: oidc-secret
type: nginx.org/oidc
data:
  client-secret: X2E1LUhGdDJWaUppR20taEVZQW9************1NTl2a3pnRHNMNzFJTkU0NEkwX2NhVmw3M0FiU01qSlhPUQ==

yaml 파일에 인코딩된 값을 client-secret의 값으로 설정합니다.

$ kubectl apply -f secret.yaml -n my-app

secret/oidc-secret created

작성한 yaml 파일을 사용하여 my-app 네임스페이스에 oidc-secret 이름으로 Secret 리소스를 생성했습니다.

2. Okta를 통한 OIDC 인증을 구성할 Policy 리소스를 생성합니다.

your-okta-domain으로 사용할 값은 웹 우측 상단에서 확인할 수 있습니다.

policy.yaml
apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: oidc-policy
spec:
  oidc:
    clientID: 0oalk89ojpt*********  # Okta의 클라이언트 ID
    clientSecret: oidc-secret  # 앞 과정에서 생성한 Secret 리소스 이름
    authEndpoint: https://dev-********.okta.com/oauth2/v1/authorize
    tokenEndpoint: https://dev-********.okta.com/oauth2/v1/token
    jwksURI: https://dev-********.okta.com/oauth2/v1/keys
  • clientID : Okta의 클라이언트 ID 값을 그대로 입력합니다.
$ kubectl apply -f policy.yaml -n my-app

policy.k8s.nginx.org/oidc-policy configured

oidc-policy 이름의 Policy 리소스를 my-app 네임스페이스에 생성했습니다.

3. NGINX Ingress Controller를 통한 백엔드 Pod 연결을 위해, VirtualServer 리소스를 생성합니다.

vs.yaml
apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: nginx-devops
  namespace: my-app
spec:
  host: devopssong.nginxstore.kr
  tls:  # SSL 설정
    secret: ingress-ssl
  routes:
  - path: /
    policies:  
    - name: oidc-policy
    action:
      pass: nginx
  upstreams:
  - name: nginx
    port: 80
    service: nginx-svc

NGINX Pod가 노출된 서비스로 연결되는 VirtualServer 리소스의 yaml 파일입니다. HTTPS 연결을 위한 tls 설정을 적용했으며, policies 항목에 앞서 생성한 Policy 리소스 이름(odic-policy)을 설정하여 연결 시 Okta를 통한 인증 과정을 추가합니다.
devopssong.nginxstore.kr 도메인의 / 경로로 접속 시 nginx-svc로 노출된 NGINX Pod로 연결됩니다.

NGINX Ingress Controller의 SSL/TLS 구성을 위한 Secret 리소스 구성 방법은 NGINX Ingress Controller SSL/TLS 구성 튜토리얼을 참고하세요.

$ kubectl apply -f vs.yaml -n my-app

virtualserver.k8s.nginx.org/nginx-devops created
$ kubectl get vs -n my-app

NAME           STATE   HOST                       IP    PORTS   AGE
nginx-devops   Valid   devopssong.nginxstore.kr                 77s

nginx-devops 이름의 VirtualServer 리소스를 생성했습니다.
Valid STATE를 통해 리소스 구성에 문제가 없음을 확인할 수 있습니다.

4. 브라우저에서 구성한 도메인으로 접속하여 확인합니다.

NGINX Ingress Controller Okta 연동 인증 화면

Okta 연동으로 인해 로그인 페이지가 나타납니다. 화면 상단의 연결 대상을 확인할 수 있습니다.

5. 로그인을 완료하여 NGINX Pod로 연결되는 것을 확인합니다.

NGINX Ingress Controller Okta 인증 연결중 화면

VitualServer 리소스를 통해 Okta를 통한 인증 완료 후 NGINX Pod로 연결되어 웹 페이지를 확인할 수 있습니다.

유효하지 않은 ID/PW 입력 시 위와 같이 메시지가 나타납니다.

4. 결론

이번 포스트에서는 NGINX Plus Ingress Controller와 Okta를 연동하여 API 인증을 구성하는 방법에 관해 알아봤습니다.

먼저, Okta의 applications 항목에서 NGINX Ingress Controller와 연동을 위한 app integration 구성을 하고, Okta와의 OIDC 인증 연동을 위한 NGINX Ingress Controller의 Deployment 구성 방법을 알아봤습니다.
또한, Okta 인증을 위한 Policy 생성과 클러스터 내부 Pod에 연결하기 위한 VirtualServer 리소스를 구성하는 방법도 다뤘습니다. 마지막으로, 웹 브라우저 접속을 통해 Okta 인증이 구현된 것을 확인했습니다.

Okta를 통한 API 인증을 구현할 수 있는 NGINX Plus Ingress Controller를 체험해 보고 싶으시다면, NGINX STORE를 통해 문의해 무료로 NGINX Plus trial을 체험해 보세요.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required