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_modulengx_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_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;

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

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을 반환합니다.

Comments are closed.