NGINX 및 NGINX Plus를 사용한 OAuth 2.0 액세스 토큰 검증

Liam Crilly제품 관리 부문 수석 이사

API 호출을 인증하는 방법에는 X.509 클라이언트 인증서부터 HTTP 기본 인증까지 다양한 옵션이 있습니다. 하지만 최근에는 OAuth 2.0 액세스 토큰이 사실상의 표준으로 자리 잡았습니다. 이는 클라이언트에서 API 서버로 전달되는 인증 자격 증명으로, 일반적으로 HTTP 헤더에 포함됩니다.

하지만 OAuth 2.0은 서로 연결된 표준들이 복잡하게 얽혀 있는 미로와 같습니다. OAuth 2.0 인증 흐름에서 토큰을 발급하고 제시하며 검증하는 과정은 여러 관련 표준에 의존하는 경우가 많습니다. 이 글을 작성하는 시점에는 OAuth 2.0 표준이 8개 있으며, 액세스 토큰이 대표적인 사례입니다. OAuth 2.0 핵심 명세인 RFC 6749에서는 액세스 토큰의 형식을 규정하지 않기 때문입니다. 실제로는 다음 두 가지 형식이 일반적으로 사용됩니다:

• RFC 7519에 정의된 JSON 웹 토큰(JWT)RFC 7519
• 인증된 클라이언트를 식별하는 고유 식별자에 불과한 불투명 토큰

인증 후 클라이언트는 보호된 리소스에 액세스하기 위해 각 HTTP 요청에 액세스 토큰을 함께 제시합니다. 액세스 토큰이 신뢰할 수 있는 ID 공급자(IdP)에서 실제로 발급되었으며 만료되지 않았는지 확인하려면 토큰을 검증해야 합니다. IdP는 발급하는 JWT에 암호화 방식으로 서명하므로, JWT는 IdP에 대한 런타임 종속성 없이 “오프라인”으로 검증할 수 있습니다. 일반적으로 JWT에는 확인 가능한 만료 날짜도 포함됩니다. NGINX Plus auth_jwt 모듈은 오프라인 JWT 검증을 수행합니다.

반면 불투명 토큰은 이를 발급한 IdP로 다시 전송하여 검증해야 합니다. 하지만 이러한 방식은 이전에 로그인한 세션을 활성 상태로 남겨 두지 않고도, 예를 들어 전역 로그아웃 작업의 일부로 IdP가 해당 토큰을 폐기할 수 있다는 장점이 있습니다. 전역 로그아웃을 위해 JWT도 IdP를 통해 검증해야 할 수 있습니다.

이 블로그에서는 NGINX와 NGINX Plus가 OAuth 2.0 신뢰 당사자 역할을 수행하여 검증을 위해 액세스 토큰을 IdP로 전송하고, 검증 절차를 통과한 요청만 프록시하는 방법을 설명합니다. 또한 이 작업에 NGINX와 NGINX Plus를 사용할 때 얻을 수 있는 다양한 이점과 검증 응답을 짧은 시간 동안 캐싱하여 사용자 경험을 개선하는 방법을 살펴봅니다. NGINX Plus의 경우 NGINX Plus R18에서 도입된 JavaScript 모듈로 키-값 저장소를 업데이트하여 NGINX Plus 인스턴스 클러스터 전체에 캐시를 분산하는 방법도 보여줍니다.

별도로 명시된 경우를 제외하고, 이 블로그의 정보는 NGINX Open Source와 NGINX Plus 모두에 적용됩니다. NGINX Plus에 대한 언급은 해당 제품에만 적용됩니다.

토큰 인트로스펙션

IdP를 통해 액세스 토큰을 검증하는 표준 방법을 토큰 인트로스펙션이라고 합니다. RFC 7662, 즉 OAuth 2.0 토큰 인트로스펙션은 신뢰 당사자가 IdP에 토큰을 제시할 때 사용하는 JSON/REST 인터페이스와 응답 구조를 설명하는 표준으로, 현재 널리 지원되고 있습니다. 주요 IdP 공급업체와 클라우드 제공업체 다수가 이 표준을 지원합니다.

어떤 토큰 형식을 사용하든 각 백엔드 서비스나 애플리케이션에서 유효성 검사를 수행하면 코드가 많이 중복되고 불필요한 처리가 발생합니다. 다양한 오류 조건과 예외적인 상황을 고려해야 하는데, 이를 각 백엔드 서비스에서 개별적으로 처리하면 구현의 일관성이 떨어지고 결과적으로 사용자 경험을 예측하기 어려워집니다. 각 백엔드 서비스가 다음과 같은 오류 조건을 어떻게 처리할지 생각해 보십시오:

• 액세스 토큰 누락
• 지나치게 큰 액세스 토큰
• 액세스 토큰에 유효하지 않거나 예상치 못한 문자가 포함됨
• 여러 개의 액세스 토큰이 제공됨
• 백엔드 서비스 간의 시계 오차

NGINX auth_request 모듈을 사용하여 토큰 검증하기

코드 중복과 그로 인해 발생하는 문제를 방지하기 위해 NGINX가 백엔드 서비스를 대신하여 액세스 토큰을 검증하도록 할 수 있습니다. 이렇게 하면 다음과 같은 여러 이점이 있습니다:

• 클라이언트가 유효한 토큰을 제시한 경우에만 요청이 백엔드 서비스에 전달됩니다.
• 기존 백엔드 서비스는 코드를 변경하지 않고도 액세스 토큰으로 보호할 수 있습니다.
• 모든 앱이 아니라 NGINX 인스턴스만 IdP에 등록하면 됩니다
• 누락되거나 유효하지 않은 토큰을 비롯한 모든 오류 상황에서 일관되게 동작합니다.

NGINX가 하나 이상의 애플리케이션에 대한 리버스 프록시로 작동하는 경우, auth_request 모듈을 사용하여 요청을 백엔드로 프록시하기 전에 IdP에 대한 API 호출을 트리거할 수 있습니다. 곧 살펴보겠지만 다음 솔루션에는 근본적인 결함이 있습니다. 하지만 이 솔루션은 auth_request 모듈의 기본 작동 방식을 소개하며, 이후 섹션에서 이를 더 자세히 다룰 것입니다.

코드 예제를 로드하는 중…

The auth_request 지시어(5행)는 API 호출을 처리할 위치를 지정합니다. 백엔드로의 프록시 처리(6행)는 auth_request 응답이 성공한 경우에만 수행됩니다. auth_request 위치는 9행에 정의되어 있습니다. 외부 클라이언트가 직접 액세스하지 못하도록 internal로 표시되어 있습니다.

11~14행에서는 요청이 토큰 검사 요청 형식을 따르도록 요청의 여러 속성을 정의합니다. 검사 요청에서 전송되는 액세스 토큰은 14행에 정의된 본문의 구성 요소라는 점에 유의하세요. 여기서 token=$http_apikey는 클라이언트가 apikey 요청 헤더에 액세스 토큰을 제공해야 함을 나타냅니다. 물론 액세스 토큰은 요청의 어떤 속성으로든 제공할 수 있으며, 이 경우에는 다른 NGINX 변수를 사용합니다.

NGINX JavaScript 모듈로 auth_request 확장하기

앞서 언급했듯이, auth_request 모듈을 이런 방식으로 사용하는 것은 완전한 해결책이 아닙니다. auth_request 모듈은 HTTP 상태 코드를 사용하여 성공 여부를 판단합니다(2xx = 성공, 4xx = 실패). 그러나 OAuth 2.0 토큰 검사 응답은 성공 또는 실패 여부를 JSON 객체에 인코딩하며, 두 경우 모두 HTTP 상태 코드 200 (OK)를 반환합니다.

필요한 것은 IdP의 인트로스펙션 응답을 적절한 HTTP 상태 코드로 변환하여 auth_request 모듈이 해당 응답을 올바르게 해석할 수 있도록 하는 JSON 파서입니다.

다행히 NGINX JavaScript 모듈(njs)에서는 JSON 파싱이 매우 간단합니다. 따라서 토큰 인트로스펙션 요청을 수행할 location 블록을 정의하는 대신, auth_request 모듈이 JavaScript 함수를 호출하도록 설정합니다.

[편집자 – 이 게시물은 NGINX JavaScript 모듈의 사용 사례를 살펴보는 여러 게시물 중 하나입니다. 전체 목록은 NGINX JavaScript 모듈 사용 사례에서 확인하세요.

이 섹션의 코드는 js_import 지시문을 사용하도록 업데이트되었습니다. 이 지시문은 js_include 지시문을 NGINX Plus R23 이상에서 대체합니다. 자세한 내용은 NGINX JavaScript 모듈 참조 문서를 확인하세요. 이 문서의 구성 예시 섹션에서는 NGINX 구성 파일과 JavaScript 파일의 올바른 구문을 보여 줍니다.]

참고: 이 솔루션을 사용하려면 JavaScript 모듈을 load_module 지시어를 사용하여 nginx.conf에서 동적 모듈로 로드해야 합니다. 자세한 지침은 NGINX Plus 관리 가이드를 참조하세요.

코드 예제를 로드하는 중…

13번째 줄의 js_content 지시문은 JavaScript 함수인 introspectAccessToken을 auth_request 핸들러로 지정합니다. 이 핸들러 함수는 oauth2.js에 정의되어 있습니다:

코드 예제를 로드하는 중…

Notice that the introspectAccessToken 함수는 다른 위치(/oauth2_send_request)로 HTTP 하위 요청(2행)을 보내며, 이 위치는 아래 구성 코드 조각에 정의되어 있습니다. 그런 다음 JavaScript 코드는 응답을 구문 분석하고(5행) auth_request 모듈에 active 필드의 값을 기반으로 적절한 상태 코드를 반환합니다. 유효한(활성) 토큰은 HTTP 204 (콘텐츠 없음)을 반환하지만 요청은 성공한 것으로 처리되며, 유효하지 않은 토큰은 HTTP 403 (금지)를 반환합니다. 오류가 발생한 경우에는 유효하지 않은 토큰과 구분할 수 있도록 HTTP 401 (인증 필요)를 반환합니다.

참고: 이 코드는 개념 증명용으로만 제공되며 프로덕션 환경에서 사용할 수 있는 수준이 아닙니다. 포괄적인 오류 처리 및 로깅 기능을 갖춘 완전한 솔루션은 아래에서 확인할 수 있습니다.

2번째 줄에 정의된 하위 요청 대상 위치는 원래의 auth_request 구성과 매우 유사합니다.

코드 예제를 로드하는 중…

토큰 검사 요청을 구성하기 위한 모든 설정은 /_oauth2_send_request 위치에 포함되어 있습니다. 일반적으로 인증(19행), 액세스 토큰 자체(21행), 토큰 검사 엔드포인트의 URL(22행)만 설정하면 됩니다. IdP가 이 NGINX 인스턴스의 토큰 검사 요청을 수락하려면 인증이 필요합니다. OAuth 2.0 토큰 검사 사양에서는 인증을 의무화하지만 인증 방법은 명시하지 않습니다. 이 예에서는 Authorization 헤더에 전달자 토큰을 사용합니다.

이 구성을 적용하면 NGINX가 요청을 수신할 때 해당 요청을 JavaScript 모듈로 전달하고, 이 모듈은 IdP에 토큰 검사 요청을 보냅니다. 그런 다음 IdP의 응답을 확인하여 active 필드가 true이면 인증에 성공한 것으로 간주합니다. 이 솔루션은 NGINX에서 OAuth 2.0 토큰 검사를 수행하는 간결하고 효율적인 방법이며, 다른 인증 API에도 쉽게 적용할 수 있습니다.

하지만 아직 끝난 것은 아닙니다. 일반적으로 토큰 인트로스펙션의 가장 큰 문제는 모든 HTTP 요청에 지연 시간이 추가된다는 점입니다. 해당 IdP가 호스팅형 솔루션이거나 클라우드 제공업체인 경우 이는 심각한 문제가 될 수 있습니다. NGINX와 NGINX Plus는 인트로스펙션 응답을 캐싱하여 이러한 단점을 완화할 수 있습니다.

최적화 1: NGINX를 통한 캐싱

OAuth 2.0 토큰 검사는 IdP의 JSON/REST 엔드포인트에서 제공되므로, 표준 응답은 HTTP 상태 코드가 200인 JSON 본문입니다. 이 응답을 액세스 토큰을 키로 사용해 저장하면 캐시 효율이 매우 높아집니다.

각 액세스 토큰의 인트로스펙션 응답 사본을 캐시하도록 NGINX를 구성할 수 있습니다. 그러면 다음에 동일한 액세스 토큰이 제시될 때 NGINX는 IdP에 API를 호출하는 대신 캐시된 인트로스펙션 응답을 제공합니다. 이를 통해 후속 요청의 전반적인 지연 시간이 크게 단축됩니다. 만료되었거나 최근에 해지된 액세스 토큰을 허용할 위험을 줄이기 위해 캐시된 응답의 사용 기간을 제어할 수 있습니다. 예를 들어 API 클라이언트가 일반적으로 짧은 시간 동안 여러 API 호출을 집중적으로 수행한다면, 캐시 유효 기간을 10초로 설정하는 것만으로도 사용자 경험을 눈에 띄게 개선할 수 있습니다.

캐시 저장소, 즉 캐시(인트로스펙션 응답)를 저장할 디스크의 디렉터리와 키(액세스 토큰)를 저장할 공유 메모리 영역을 지정하면 캐싱이 활성화됩니다.

코드 예제를 로드하는 중…

The proxy_cache_path 지시문은 필요한 저장 공간을 할당합니다. 인트로스펙션 응답을 위한 /var/cache/nginx/oauth와 키를 위한 token_responses라는 메모리 영역을 할당합니다. 이 지시문은 http 컨텍스트에 구성되므로 server 및 location 블록 외부에 위치합니다. 그런 다음 토큰 인트로스펙션 응답이 처리되는 location 블록 내에서 캐싱이 활성화됩니다.

코드 예제를 로드하는 중…

이 위치에서는 proxy_cache 지시어(26행)를 사용하여 캐싱을 활성화합니다. 기본적으로 NGINX는 URI를 기준으로 캐싱하지만, 여기서는 apikey 요청 헤더에 제공된 액세스 토큰을 기준으로 응답을 캐싱하려고 합니다(27행).

28번째 줄에서는 proxy_cache_lock 지시어를 사용하여 동일한 캐시 키를 가진 요청이 동시에 들어올 경우, 첫 번째 요청이 캐시를 채울 때까지 기다린 후 나머지 요청에 응답하도록 NGINX에 지시합니다. proxy_cache_valid 지시어(29번째 줄)는 인트로스펙션 응답을 캐시할 기간을 NGINX에 지정합니다. 이 지시어가 없으면 NGINX는 IdP가 전송한 캐시 제어 헤더를 기준으로 캐시 기간을 결정합니다. 하지만 이러한 헤더가 항상 신뢰할 수 있는 것은 아니므로, 응답 캐싱 방식에 영향을 줄 수 있는 헤더를 무시하도록 NGINX에 지시합니다(30번째 줄).

이제 캐싱이 활성화되었으므로 액세스 토큰을 제시하는 클라이언트는 10초마다 한 번씩 토큰 검사 요청을 수행할 때만 지연 시간의 영향을 받습니다.

최적화 2: NGINX Plus를 활용한 분산 캐싱

콘텐츠 캐싱과 토큰 인트로스펙션을 함께 사용하면 보안에 미치는 영향을 최소화하면서 전반적인 애플리케이션 성능을 매우 효과적으로 향상할 수 있습니다. 그러나 NGINX가 여러 데이터 센터, 클라우드 플랫폼 또는 액티브-액티브 클러스터 등에 분산 방식으로 배포된 경우, 캐시된 토큰 인트로스펙션 응답은 인트로스펙션 요청을 수행한 NGINX 인스턴스에서만 사용할 수 있습니다.

NGINX Plus에서는 keyval 모듈(메모리 내 키-값 저장소)을 사용하여 토큰 인트로스펙션 응답을 캐시할 수 있습니다. 또한 zone_sync 모듈을 사용하면 NGINX Plus 인스턴스 클러스터 전체에서 이러한 응답을 동기화할 수도 있습니다. 즉, 어떤 NGINX Plus 인스턴스가 토큰 인트로스펙션 요청을 수행했는지와 관계없이 클러스터의 모든 NGINX Plus 인스턴스에서 해당 응답을 사용할 수 있습니다.

참고: 런타임 상태 공유를 위한 zone_sync 모듈 구성은 이 블로그에서 다루지 않습니다. NGINX Plus 클러스터의 상태 공유에 대한 자세한 내용은 NGINX Plus 관리 가이드를 참조하세요.

In NGINX Plus R18 이상에서는 keyval 지시문에 선언된 변수를 수정하여 키-값 저장소를 업데이트할 수 있습니다. JavaScript 모듈은 모든 NGINX 변수에 액세스할 수 있으므로 응답을 처리하는 동안 인트로스펙션 응답을 키-값 저장소에 저장할 수 있습니다.

NGINX 파일 시스템 캐시와 마찬가지로 키-값 저장소는 저장 공간을 지정하여 활성화합니다. 여기서는 키(액세스 토큰)와 값(인트로스펙션 응답)을 저장하는 메모리 영역을 지정합니다.

코드 예제를 로드하는 중…

Note that with the timeout 매개변수를 keyval_zone 지시문에 사용하여 캐시된 응답의 유효 기간을 auth_request_cache.conf의 29번째 줄과 동일하게 10초로 지정합니다. 따라서 NGINX Plus 클러스터의 각 구성원은 응답이 만료되면 이를 독립적으로 제거합니다. 2번째 줄에서는 각 항목의 키-값 쌍을 지정합니다. 키는 apikey 요청 헤더에 제공된 액세스 토큰이고, 값은 $token_data 변수로 평가된 인트로스펙션 응답입니다.

이제 apikey 요청 헤더가 포함된 각 요청에 대해 $token_data 변수에는 이전 토큰 검사 응답이 있는 경우 해당 응답이 설정됩니다. 따라서 토큰 검사 응답이 이미 있는지 확인하도록 JavaScript 코드를 업데이트합니다.

코드 예제를 로드하는 중…

2번째 줄에서는 이 액세스 토큰에 대한 키-값 저장소 항목이 이미 있는지 확인합니다. 인트로스펙션 응답을 얻는 경로가 두 가지(키-값 저장소에서 가져오거나 인트로스펙션 요청에 대한 응답으로 받는 경우)로 나뉘므로, 검증 로직을 다음과 같은 별도의 함수로 옮깁니다. tokenResult:

코드 예제를 로드하는 중…

이제 각 토큰 검사 응답은 키-값 저장소에 저장되고 NGINX Plus 클러스터의 다른 모든 구성원과 동기화됩니다. 다음 예에서는 유효한 액세스 토큰을 사용한 간단한 HTTP 요청을 보낸 다음, NGINX Plus API를 쿼리하여 키-값 저장소의 내용을 확인합니다.

$ curl -IH "apikey: tQ7AfuEFvI1yI-XNPNhjT38vg_reGkpDFA" http://localhost/HTTP/1.1 200 OK
Date: Wed, 24 Apr 2019 17:41:34 GMT
Content-Type: application/json
Content-Length: 612

$ curl http://localhost/api/4/http/keyvals/access_tokens
{"tQ7AfuEFvI1yI-XNPNhjT38vg_reGkpDFA":"{\"active\":true}"}

키-값 저장소 자체가 JSON 형식을 사용하므로 토큰 인트로스펙션 응답의 따옴표에는 이스케이프 처리가 자동으로 적용됩니다.

최적화 3: 인트로스펙션 응답에서 속성 추출

OAuth 2.0 토큰 인트로스펙션의 유용한 기능 중 하나는 응답에 토큰의 활성 상태뿐만 아니라 토큰에 관한 정보도 포함될 수 있다는 점입니다. 이러한 정보에는 토큰 만료일과 연결된 사용자의 속성(사용자 이름, 이메일 주소 등)이 포함됩니다.

이러한 추가 정보는 매우 유용할 수 있습니다. 이 정보를 로그에 기록하거나, 세분화된 액세스 제어 정책을 구현하는 데 사용하거나, 백엔드 애플리케이션에 제공할 수 있습니다. 성공적인 HTTP 응답에 추가 응답 헤더로 포함하여 이러한 각 속성을 auth_request 모듈로 내보낼 수 있습니다(HTTP 204).

코드 예제를 로드하는 중…

인트로스펙션 응답의 각 속성을 순회한 후(23행), 이를 응답 헤더로 auth_request 모듈에 다시 전송합니다. 표준 응답 헤더와의 충돌을 방지하기 위해 각 헤더 이름 앞에 Token- 접두사를 붙입니다(26행). 이제 이러한 응답 헤더를 NGINX 변수로 변환하여 일반 구성의 일부로 사용할 수 있습니다.

코드 예제를 로드하는 중…

이 예에서는 username 속성을 새 변수인 $username(11행)으로 변환합니다. auth_request_set 지시문을 사용하면 토큰 인트로스펙션 응답의 컨텍스트를 현재 요청의 컨텍스트로 내보낼 수 있습니다. 각 속성의 응답 헤더(JavaScript 코드로 추가됨)는 $sent_http_token_attribute로 사용할 수 있습니다. 그런 다음 12행에서는 $username 값을 백엔드로 프록시되는 요청 헤더에 포함합니다. 토큰 인트로스펙션 응답에서 반환된 모든 속성에 이 구성을 반복해서 적용할 수 있습니다.

프로덕션 구성

위의 코드 및 구성 예시는 정상적으로 작동하며, 개념 증명 테스트 또는 특정 사용 사례에 맞게 사용자 지정하는 데 적합합니다. 프로덕션 환경에서 사용하려면 추가적인 오류 처리와 로깅, 유연한 구성을 적용할 것을 강력히 권장합니다. NGINX 및 NGINX Plus를 위한 더욱 견고하고 상세한 구현은 GitHub 리포지토리에서 확인할 수 있습니다:

• NGINX를 사용한 OAuth 2.0 토큰 검사(디스크 캐싱)
• NGINX Plus를 사용한 OAuth 2.0 토큰 검사(키-값 캐싱)

요약

이 블로그에서는 NGINX auth_request 모듈을 JavaScript 모듈과 함께 사용하여 클라이언트 요청에 대해 OAuth 2.0 토큰 인트로스펙션을 수행하는 방법을 살펴보았습니다. 또한 이 솔루션에 캐싱 기능을 추가하고, NGINX 구성에서 사용할 수 있도록 인트로스펙션 응답에서 속성을 추출했습니다.

또한 NGINX Plus 키-값 저장소를 인트로스펙션 응답을 위한 분산 캐시로 활용하여, 여러 NGINX Plus 인스턴스로 구성된 클러스터의 프로덕션 배포에 적합하게 사용할 수 있는 방법도 설명했습니다.

NGINX Plus로 OAuth 2.0 토큰 검사를 직접 사용해 보세요. 지금 30일 무료 체험을 시작하거나 사용 사례에 대해 논의하려면 문의해 주세요.

작성자 소개

Liam Crilly제품 관리 부문 수석 이사

Liam Crilly의 다른 블로그 게시물