ngx_http_auth_jwt_module

ngx_http_auth_jwt_module 모듈(1.11.3)은 제공된 JSON 웹 토큰(JWT)을 지정된 키로 인증하는 방식으로 클라이언트 인증을 구현합니다. 이 모듈은 JSON 웹 서명(JWS), JSON 웹 암호화(JWE)(1.19.7) 및 중첩된 JWT(1.21.0)를 지원합니다. 이 모듈은 OpenID Connect 인증에 사용할 수 있습니다.

이 모듈은 satisfy 명령을 통해 다른 액세스 모듈(예: ngx_http_access_module, ngx_http_auth_basic_module, ngx_http_auth_request_module)과 결합할 수 있습니다.

이 모듈은 상업용 구독에서 제공합니다.

지원되는 알고리즘

이 모듈은 다음의 JSON 웹 알고리즘을 지원합니다.

JWS 알고리즘:

  • HS256, HS384, HS512
  • RS256, RS384, RS512
  • ES256, ES384, ES512
  • EdDSA (Ed25519 and Ed448 signatures) (1.15.7)

1.13.7버전 이전에는 HS256, RS256, ES256 알고리즘만 지원했습니다.

JWE 콘텐츠 암호화 알고리즘(1.19.7):

  • A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
  • A128GCM, A192GCM, A256GCM

JWE 키 관리 알고리즘(1.19.9):

  • A128KW, A192KW, A256KW
  • A128GCMKW, A192GCMKW, A256GCMKW
  • dir – 공유된 대칭 키를 콘텐츠 암호화 키로 직접 사용
  • RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0)

예제 구성

location / {
    auth_jwt          "closed site";
    auth_jwt_key_file conf/keys.json;
}

Directives

Syntax:  auth_jwt string [token=$variable] | off;
Default: auth_jwt off;
Context: http, server, location, limit_except

JSON 웹 토큰의 인증을 활성화합니다. 지정된 string을 realm으로 사용합니다. 매개변수 값은 변수를 포함할 수 있습니다.

선택적 token 매개변수가 JSON 웹 토큰을 포함한 변수를 지정합니다. 기본적으로 JWT는 “Authorization” 헤더에서 Bearer 토큰으로 전달됩니다. JWT는 쿠키나 쿼리 문자열의 일부로 전달될 수도 있습니다.

auth_jwt "closed site" token=$cookie_auth_token;

특수 값 off는 이전 구성 수준에서 상속한 auth_jwt 명령의 효과를 상쇄합니다.

Syntax:  auth_jwt_claim_set $variable name ...;
Default: —
Context: http
This directive appeared in version 1.11.10.

variable를 키 이름으로 식별된 JWT 클레임 매개변수로 설정합니다. 이름 매칭은 JSON 트리의 최상위 수준부터 시작합니다. 배열의 경우, 변수에 쉼표(,)로 구분된 배열 요소 목록이 저장됩니다.

auth_jwt_claim_set $email info e-mail;
auth_jwt_claim_set $job info "job title";

1.13.7버전 이전에는 키 이름을 하나만 지정할 수 있었고, 배열에 대한 결과는 정의되지 않았습니다.

JWE로 암호화된 토큰에 대한 변수 값은 액세스 단계에서 복호화된 이후에만 사용할 수 있습니다.

Syntax:  auth_jwt_header_set $variable name ...;
Default: —
Context: http
This directive appeared in version 1.11.10.

variable를 키 이름으로 식별된 JOSE 헤더 매개변수로 설정합니다. 이름 매칭은 JSON 트리의 최상위 수준부터 시작합니다. 배열의 경우, 변수에 쉼표(,)로 구분된 배열 요소 목록이 저장됩니다.

1.13.7버전 이전에는 키 이름을 하나만 지정할 수 있었고, 배열에 대한 결과는 정의되지 않았습니다.

Syntax:  auth_jwt_key_cache time;
Default: auth_jwt_key_cache 0;
Context: http, server, location
This directive appeared in version 1.21.4.

파일 또는 하위 요청에서 얻은 Key 캐싱을 활성화 또는 비활성화하고 해당 Key에 대한 캐싱 시간을 설정합니다. 변수에서 얻은 Key의 캐싱은 지원되지 않습니다. 기본적으로 Key 캐싱은 비활성화되어 있습니다.

Syntax:  auth_jwt_key_file file;
Default: —
Context: http, server, location, limit_except

JWT 서명을 인증하기 위해 JSON 웹 키 세트 형식으로 file을 지정합니다. 매개변수 값은 변수를 포함할 수 있습니다.

동일한 수준에서 여러 auth_jwt_key_file 명령을 지정할 수 있습니다(1.21.1).

auth_jwt_key_file conf/keys.json;
auth_jwt_key_file conf/key.jwk;
Syntax:  auth_jwt_key_request uri;
Default: —
Context: http, server, location, limit_except
This directive appeared in version 1.15.6.

JWT 서명을 인증하기 위해 하위 요청에서 JSON 웹 키 세트 파일을 검색하도록 허용하고, 하위 요청을 전송할 URI를 설정합니다. 매개변수 값은 변수를 포함할 수 있습니다. 인증 오버헤드가 발생하지 않으려면 키 파일을 캐싱하는 것이 좋습니다.

proxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m;

server {
    ...

    location / {
        auth_jwt             "closed site";
        auth_jwt_key_request /jwks_uri;
    }

    location = /jwks_uri {
        internal;
        proxy_cache foo;
        proxy_pass  http://idp.example.com/keys;
    }
}

동일한 수준에서 여러 auth_jwt_key_request 명령을 지정할 수 있습니다(1.21.1).

auth_jwt_key_request /jwks_uri;
auth_jwt_key_request /jwks2_uri;

지정된 키의 하나 이상을 로드하거나 처리할 수 없을 경우, nginx는 500(Internal Server Error) 오류를 반환합니다.

Syntax:  auth_jwt_leeway time;
Default: auth_jwt_leeway 0s;
Context: http, server, location
This directive appeared in version 1.13.10.

exp 및 nbf JWT 클레임을 인증할 때 클록 스큐를 보상하기 위해 허용 가능한 최대한도를 설정합니다.

Syntax:  auth_jwt_type signed | encrypted | nested;
Default: auth_jwt_type signed;
Context: http, server, location, limit_except
This directive appeared in version 1.19.7.

다음 중 어떤 유형의 JSON 웹 토큰을 받을지 지정합니다. JWS(signed), JWE(encrypted) 또는 서명 후 암호화한 중첩 JWT(nested)가 있습니다(1.21.0).

Syntax:	auth_jwt_require value ...;
Default:	—
Context:	http, server, location, limit_except
This directive appeared in version 1.21.2.

JWT 인증을 위한 추가 조건을 정의합니다. 이 값에는 텍스트, 변수 및 그 두 가지의 조합을 포함할 수 있습니다. 모든 값이 비어 있지 않고 “0”이 아니어야 인증이 성공합니다.

map $jwt_claim_iss $valid_jwt_iss {
    "good" 1;
}
...

auth_jwt_require $valid_jwt_iss;

임베디드 변수

ngx_http_auth_jwt_module 모듈은 임베디드 변수를 지원합니다.

$jwt_header_name

지정된 JOSE 헤더 값을 반환

$jwt_claim_name

지정된 JWT 클레임 값을 반환

중첩 클레임과 점(“.”)을 포함한 클레임의 경우, 변수 값을 평가할 수 없습니다. 대신 auth_jwt_claim_set 명령을 사용해야 합니다.

JWE로 암호화된 토큰에 대한 변수 값은 액세스 단계에서 복호화된 이후에만 사용할 수 있습니다.

$jwt_payload

nested 또는 encrypted 토큰의 복호화된 최상위 페이로드를 반환합니다(1.21.2). 중첩된 토큰은 인용 부호를 붙인 JWS 토큰을 반환합니다. 암호화된 토큰은 클레임이 포함된 JSON을 반환합니다.