node-jsonwebtoken - GitLite

KO | EN

gitlite — search

#ai #llm #go #rust #deep-learning #linux #docker #macos #java #nodejs #awesome #kubernetes #security #open-source

node-jsonwebtoken

(★ 18,189)

node.js를 위한 JsonWebToken 구현체 http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html

파일 탐색기

최종 버전 다운로드 (.zip)

- - commitlint.yml
  - prepare-release.yml
  - release.yml
  - sca-scan.yml
  - test.yml
- commit-msg
- changelog
- asymmetricKeyDetailsSupported.js
- JsonWebTokenError.js
- NotBeforeError.js
- psSupported.js
- rsaPssKeyDetailsSupported.js
- timespan.js
- TokenExpiredError.js
- validateAsymmetricKey.js
- .eslintrc.json
- async_sign.tests.js
- buffer.tests.js
- claim-aud.test.js
- claim-exp.test.js
- claim-iat.test.js
- claim-iss.test.js
- claim-jti.test.js
- claim-nbf.test.js
- claim-private.tests.js
- claim-sub.tests.js
- decoding.tests.js
- dsa-private.pem
- dsa-public.pem
- ecdsa-private.pem
- ecdsa-public-invalid.pem
- ecdsa-public-x509.pem
- ecdsa-public.pem
- encoding.tests.js
- expires_format.tests.js
- header-kid.test.js
- invalid_exp.tests.js
- invalid_pub.pem
- issue_147.tests.js
- issue_304.tests.js
- issue_70.tests.js
- jwt.asymmetric_signing.tests.js
- jwt.hs.tests.js
- jwt.malicious.tests.js
- non_object_values.tests.js
- noTimestamp.tests.js
- option-complete.test.js
- option-maxAge.test.js
- option-nonce.test.js
- prime256v1-private.pem
- priv.pem
- pub.pem
- rsa-private.pem
- rsa-pss-invalid-salt-length-private.pem
- rsa-pss-private.pem
- rsa-public-key.pem
- rsa-public-key.tests.js
- rsa-public.pem
- schema.tests.js
- secp384r1-private.pem
- secp521r1-private.pem
- set_headers.tests.js
- test-utils.js
- undefined_secretOrPublickey.tests.js
- validateAsymmetricKey.tests.js
- verify.tests.js
- wrong_alg.tests.js
.commitlintrc.json
.editorconfig
.eslintignore
.eslintrc.json
.gitignore
.npmignore
.releaserc.json
CHANGELOG.md
CODEOWNERS
decode.js
index.js
LICENSE
opslevel.yml
package.json
README.md
sign.js
verify.js

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# jsonwebtoken
| \*\*Build\*\* | \*\*Dependency\*\* |
|-----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| [![Build Status](https://secure.travis-ci.org/auth0/node-jsonwebtoken.svg?branch=master)](http://travis-ci.org/auth0/node-jsonwebtoken) | [![Dependency Status](https://david-dm.org/auth0/node-jsonwebtoken.svg)](https://david-dm.org/auth0/node-jsonwebtoken) |
[JSON Web Tokens](https://tools.ietf.org/html/rfc7519)의 구현체입니다.
이 라이브러리는 `draft-ietf-oauth-json-web-token-08`을 기반으로 개발되었습니다. [node-jws](https://github.com/brianloveswords/node-jws)를 사용합니다.
# Install
```bash
$ npm install jsonwebtoken
```
# Migration notes
\* [v8에서 v9로 변경 시](https://github.com/auth0/node-jsonwebtoken/wiki/Migration-Notes:-v8-to-v9)
\* [v7에서 v8로 변경 시](https://github.com/auth0/node-jsonwebtoken/wiki/Migration-Notes:-v7-to-v8)
# Usage
### jwt.sign(payload, secretOrPrivateKey, [options, callback])
(비동기) 콜백이 제공된 경우, 콜백은 `err` 또는 JWT와 함께 호출됩니다.
(동기) JsonWebToken을 문자열로 반환합니다.
`payload`는 유효한 JSON을 나타내는 객체 리터럴, 버퍼 또는 문자열일 수 있습니다.
> \*\*참고:\*\* `exp` 또는 기타 클레임은 페이로드가 객체 리터럴인 경우에만 설정됩니다. 버퍼 또는 문자열 페이로드는 JSON 유효성을 검사하지 않습니다.
> `payload`가 버퍼나 문자열이 아니면 `JSON.stringify`를 사용하여 문자열로 변환됩니다.
`secretOrPrivateKey`는 HMAC 알고리즘의 시크릿 또는 RSA 및 ECDSA의 PEM 인코딩된 개인 키를 포함하는 문자열(utf-8 인코딩), 버퍼, 객체 또는 KeyObject입니다. 암호(passphrase)가 있는 개인 키의 경우 객체 `{ key, passphrase }`를 사용할 수 있습니다([crypto 문서](https://nodejs.org/api/crypto.html#crypto\_sign\_sign\_private\_key\_output\_format) 참고). 이 경우 반드시 `algorithm` 옵션을 전달해야 합니다.
RSA 알고리즘으로 서명할 때 allowInsecureKeySizes 옵션이 true로 설정된 경우를 제외하고 최소 모듈러스 길이는 2048입니다. 이 크기보다 작은 개인 키는 오류와 함께 거부됩니다.
`options`:
\* `algorithm` (기본값: `HS256`)
\* `expiresIn`: 초 단위로 표현되거나 시간 간격을 나타내는 문자열 [vercel/ms](https://github.com/vercel/ms).
> 예: `60`, `"2 days"`, `"10h"`, `"7d"`. 숫자 값은 초 수로 해석됩니다. 문자열을 사용하는 경우 시간 단위(일, 시간 등)를 제공해야 하며, 그렇지 않으면 기본적으로 밀리초 단위가 사용됩니다 (`"120"`은 `"120ms"`와 같음).
\* `notBefore`: 초 단위로 표현되거나 시간 간격을 나타내는 문자열 [vercel/ms](https://github.com/vercel/ms).
> 예: `60`, `"2 days"`, `"10h"`, `"7d"`. 숫자 값은 초 수로 해석됩니다. 문자열을 사용하는 경우 시간 단위(일, 시간 등)를 제공해야 하며, 그렇지 않으면 기본적으로 밀리초 단위가 사용됩니다 (`"120"`은 `"120ms"`와 같음).
\* `audience`
\* `issuer`
\* `jwtid`
\* `subject`
\* `noTimestamp`
\* `header`
\* `keyid`
\* `mutatePayload`: true인 경우, sign 함수는 페이로드 객체를 직접 수정합니다. 이는 클레임이 적용된 후이면서 토큰으로 인코딩되기 전의 페이로드에 대한 원본 참조가 필요한 경우에 유용합니다.
\* `allowInsecureKeySizes`: true인 경우 RSA에 2048 미만의 모듈러스를 가진 개인 키를 사용할 수 있습니다.
\* `allowInvalidAsymmetricKeyTypes`: true인 경우, 지정된 알고리즘과 일치하지 않는 비대칭 키를 허용합니다. 이 옵션은 하위 호환성을 위해서만 제공되므로 피해야 합니다.
> `expiresIn`, `notBefore`, `audience`, `subject`, `issuer`에 대한 기본값은 없습니다. 이러한 클레임은 페이로드 내에서 각각 `exp`, `nbf`, `aud`, `sub`, `iss`로 직접 제공할 수도 있지만, \*\*\_양쪽 모두에 포함할 수는 없습니다\_\*\*.
`exp`, `nbf`, `iat`는 \*\*NumericDate\*\*라는 점을 기억하세요. 관련 내용은 [토큰 만료 (exp 클레임)](#token-expiration-exp-clai)를 참고하세요.

m)
헤더는 `options.header` 객체를 통해 커스터마이징할 수 있습니다.
생성된 jwt에는 `noTimestamp`가 지정되지 않는 한 기본적으로 `iat` (발행 시각) 클레임이 포함됩니다. 페이로드에 `iat`가 삽입된 경우, `options.expiresIn`에 주어진 시간 범위로 `exp`와 같은 다른 항목을 계산할 때 실제 타임스탬프 대신 이 값이 사용됩니다.

기본값(HMAC SHA256)으로 동기 서명
```js
var jwt = require('jsonwebtoken');
var token = jwt.sign({ foo: 'bar' }, 'shhhhh');
```

RSA SHA256으로 동기 서명
```js
// sign with RSA SHA256
var privateKey = fs.readFileSync('private.key');
var token = jwt.sign({ foo: 'bar' }, privateKey, { algorithm: 'RS256' });
```

비동기 서명
```js
jwt.sign({ foo: 'bar' }, privateKey, { algorithm: 'RS256' }, function(err, token) {
console.log(token);
});
```

jwt의 날짜를 30초 전으로 백데이트
```js
var older\_token = jwt.sign({ foo: 'bar', iat: Math.floor(Date.now() / 1000) - 30 }, 'shhhhh');
```

#### 토큰 만료 (exp 클레임)
JWT 표준은 만료를 위해 `exp` 클레임을 정의합니다. 만료는 \*\*NumericDate\*\*로 표현됩니다:
> 1970-01-01T00:00:00Z UTC부터 지정된 UTC 날짜/시간까지의 초 수를 나타내는 JSON 숫자 값이며, 윤초는 무시합니다. 이는 IEEE Std 1003.1, 2013 Edition [POSIX.1] 정의인 "에포크 이후의 초(Seconds Since the Epoch)"와 동등하며, 비정수 값을 표현할 수 있다는 점을 제외하고는 각 날짜가 정확히 86400초로 계산됩니다. 날짜/시간 일반 및 특히 UTC에 대한 자세한 내용은 RFC 3339 [RFC3339]를 참조하세요.

즉, `exp` 필드에는 에포크 이후의 초 수가 포함되어야 합니다.
1시간의 만료 기간을 가진 토큰 서명:
```javascript
jwt.sign({
exp: Math.floor(Date.now() / 1000) + (60 \* 60),
data: 'foobar'
}, 'secret');
```

이 라이브러리를 사용하여 이와 같은 토큰을 생성하는 또 다른 방법은 다음과 같습니다:
```javascript
jwt.sign({
data: 'foobar'
}, 'secret', { expiresIn: 60 \* 60 });
//or even better:
jwt.sign({
data: 'foobar'
}, 'secret', { expiresIn: '1h' });
```

### jwt.verify(token, secretOrPublicKey, [options, callback])
(비동기) 콜백이 제공되면 함수는 비동기식으로 작동합니다. 서명이 유효하고 선택적 만료, 대상(audience), 또는 발행자(issuer)가 유효한 경우 디코딩된 페이로드와 함께 콜백이 호출됩니다. 그렇지 않으면 오류와 함께 호출됩니다.
(동기) 콜백이 제공되지 않으면 함수는 동기식으로 작동합니다. 서명이 유효하고 선택적 만료, 대상, 또는 발행자가 유효한 경우 디코딩된 페이로드를 반환합니다. 그렇지 않으면 오류를 발생시킵니다.

> \_\_경고:\_\_ 토큰이 신뢰할 수 없는 소스(예: 사용자 입력 또는 외부 요청)에서 오는 경우, 반환된 디코딩된 페이로드는 다른 사용자 입력과 마찬가지로 취급되어야 합니다. 반드시 살균(sanitization)을 거치고 예상되는 속성만 다루도록 하세요.

`token`은 JsonWebToken 문자열입니다.
`secretOrPublicKey`는 HMAC 알고리즘용 비밀키를 포함하는 문자열(utf-8 인코딩), 버퍼, 또는 KeyObject이거나, RSA 및 ECDSA용 PEM 인코딩된 공개키입니다.
`jwt.verify`가 비동기식으로 호출되는 경우, `secretOrPublicKey`는 비밀키나 공개키를 가져와야 하는 함수일 수 있습니다. 자세한 예제는 아래를 참조하세요.

[이 댓글](https://github.com/auth0/node-jsonwebtoken/issues/208#issuecomment-231861138)에서 언급된 것처럼, base64로 인코딩된 비밀키(base64로 인코딩된 무작위 바이트)를 기대하는 다른 라이브러리들도 있습니다. 그러한 경우라면 `Buffer.from(secret, 'base64')`를 전달할 수 있으며, 이렇게 하면 비밀키가 base64로 디코딩되고 토큰 검증에 원래의 무작위 바이트가 사용됩니다.

`options`
\* `algorithms`: 허용된 알고리즘 이름의 문자열 목록입니다. 예를 들어 `["HS256", "HS384"]`.
> 지정하지 않으면 제공된 키 유형에 따라 기본값이 사용됩니다.
> \* secret - ['HS256', 'HS384', 'HS512']
> \* rsa - ['RS256', 'RS384', 'RS512']
> \* ec - ['ES256', 'ES384', 'ES512']
> \* default - ['RS256', 'RS384', 'RS512']
\* `audience`: 대상(`aud`)을 확인하려는 경우 여기에 값을 제공합니다. 대상은 s와 대조하여 확인할 수 있습니다.

tring, 정규표현식 또는 문자열 및/또는 정규표현식의 배열입니다.
> 예: `"urn:foo"`, `/urn:f[o]{2}/`, `[/urn:f[o]{2}/, "urn:bar"]`
\* `complete`: 일반적인 페이로드 내용만 반환하는 대신 디코딩된 `{ payload, header, signature }` 객체를 반환합니다.
\* `issuer` (선택 사항): `iss` 필드에 대한 유효한 값의 문자열 또는 문자열 배열입니다.
\* `jwtid` (선택 사항): JWT ID(`jti`)를 확인하려면 여기에 문자열 값을 제공하세요.
\* `ignoreExpiration`: `true`인 경우 토큰의 만료 시간을 검증하지 않습니다.
\* `ignoreNotBefore`...
\* `subject`: subject(`sub`)를 확인하려면 여기에 값을 제공하세요.
\* `clockTolerance`: 서로 다른 서버 간의 미세한 시계 차이를 처리하기 위해 `nbf` 및 `exp` 클레임을 확인할 때 허용할 초(second) 단위의 숫자입니다.
\* `maxAge`: 토큰이 유효한 상태로 유지될 수 있는 최대 허용 기간입니다. 초 단위 또는 시간 범위를 설명하는 [vercel/ms](https://github.com/vercel/ms) 형식의 문자열로 표현됩니다.
> 예: `1000`, `"2 days"`, `"10h"`, `"7d"`. 숫자는 초 단위로 해석됩니다. 문자열을 사용하는 경우 반드시 시간 단위(days, hours 등)를 제공해야 하며, 그렇지 않으면 기본적으로 밀리초 단위가 사용됩니다(`"120"`은 `"120ms"`와 같음).
\* `clockTimestamp`: 필요한 모든 비교에서 현재 시간으로 사용할 초 단위의 시간입니다.
\* `nonce`: `nonce` 클레임을 확인하려면 여기에 문자열 값을 제공하세요. Open ID의 ID 토큰에 사용됩니다. ([Open ID implementation notes](https://openid.net/specs/openid-connect-core-1\_0.html#NonceNotes))
\* `allowInvalidAsymmetricKeyTypes`: true인 경우, 지정된 알고리즘과 일치하지 않는 비대칭 키를 허용합니다. 이 옵션은 하위 호환성을 위해서만 제공되므로 피해야 합니다.
```js
// verify a token symmetric - synchronous
var decoded = jwt.verify(token, 'shhhhh');
console.log(decoded.foo) // bar
// verify a token symmetric
jwt.verify(token, 'shhhhh', function(err, decoded) {
console.log(decoded.foo) // bar
});
// invalid token - synchronous
try {
var decoded = jwt.verify(token, 'wrong-secret');
} catch(err) {
// err
}
// invalid token
jwt.verify(token, 'wrong-secret', function(err, decoded) {
// err
// decoded undefined
});
// verify a token asymmetric
var cert = fs.readFileSync('public.pem'); // get public key
jwt.verify(token, cert, function(err, decoded) {
console.log(decoded.foo) // bar
});
// verify audience
var cert = fs.readFileSync('public.pem'); // get public key
jwt.verify(token, cert, { audience: 'urn:foo' }, function(err, decoded) {
// if audience mismatch, err == invalid audience
});
// verify issuer
var cert = fs.readFileSync('public.pem'); // get public key
jwt.verify(token, cert, { audience: 'urn:foo', issuer: 'urn:issuer' }, function(err, decoded) {
// if issuer mismatch, err == invalid issuer
});
// verify jwt id
var cert = fs.readFileSync('public.pem'); // get public key
jwt.verify(token, cert, { audience: 'urn:foo', issuer: 'urn:issuer', jwtid: 'jwtid' }, function(err, decoded) {
// if jwt id mismatch, err == invalid jwt id
});
// verify subject
var cert = fs.readFileSync('public.pem'); // get public key
jwt.verify(token, cert, { audience: 'urn:foo', issuer: 'urn:issuer', jwtid: 'jwtid', subject: 'subject' }, function(err, decoded) {
// if subject mismatch, err == invalid subject
});
// alg mismatch
var cert = fs.readFileSync('public.pem'); // get public key
jwt.verify(token, cert, { algorithms: ['RS256'] }, function (err, payload) {
// if token alg != RS256, err == invalid signature
});
// Verify using getKey callback
// Example uses https://github.com/auth0/node-jwks-rsa as a way to fetch the keys.
var jwksClient = require('jwks-rsa');
var client = jwksClient({
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json'
});
function getKey(header, callback){
client.getSigningKey(header.kid, function(err, key) {
var signingKey = key.publicKey || key.rsaPublicKey;
callback(null, signingKey);
});
}
jwt.verify(token, getKey, options, function(err, decoded) {
console.log(decoded.foo) // bar

});
```
서명을 검증하지 않고 JWT를 살짝 들여다보고 싶으신가요? (클릭하여 펼치기)
### jwt.decode(token [, options])
(동기 방식) 서명이 유효한지 검증하지 않고 디코딩된 페이로드를 반환합니다.
> \_\_경고:\_\_ 이 함수는 서명이 유효한지 \_\_검증하지 않습니다\_\_. 신뢰할 수 없는 메시지에는 이 함수를 \_\_사용하지 않아야 합니다\_\_. 대신 `jwt.verify`를 사용하는 것이 좋습니다.
> \_\_경고:\_\_ 토큰이 신뢰할 수 없는 소스(예: 사용자 입력 또는 외부 요청)에서 온 경우, 반환된 디코딩된 페이로드는 다른 사용자 입력과 마찬가지로 취급해야 합니다. 반드시 입력값을 검증(sanitize)하고 예상되는 속성만 다루도록 하세요.
`token`은 JsonWebToken 문자열입니다.
`options`:
\* `json`: 헤더에 `"typ":"JWT"`가 포함되어 있지 않더라도 페이로드에 강제로 JSON.parse를 적용합니다.
\* `complete`: 디코딩된 페이로드와 헤더가 포함된 객체를 반환합니다.
예시
```js
// 서명을 무시하고 디코딩된 페이로드를 가져옵니다. secretOrPrivateKey가 필요 없습니다.
var decoded = jwt.decode(token);
// 디코딩된 페이로드와 헤더를 가져옵니다.
var decoded = jwt.decode(token, {complete: true});
console.log(decoded.header);
console.log(decoded.payload)
```
## 에러 및 코드
검증 중에 발생할 수 있는 에러들입니다.
에러는 검증 콜백의 첫 번째 인자입니다.
### TokenExpiredError
토큰이 만료된 경우 발생하는 에러입니다.
에러 객체:
\* name: 'TokenExpiredError'
\* message: 'jwt expired'
\* expiredAt: [ExpDate]
```js
jwt.verify(token, 'shhhhh', function(err, decoded) {
if (err) {
/\*
err = {
name: 'TokenExpiredError',
message: 'jwt expired',
expiredAt: 1408621000
}
\*/
}
});
```
### JsonWebTokenError
에러 객체:
\* name: 'JsonWebTokenError'
\* message:
\* 'invalid token' - 헤더 또는 페이로드를 파싱할 수 없음
\* 'jwt malformed' - 토큰이 세 개의 구성 요소로 이루어져 있지 않음 (`.`으로 구분됨)
\* 'jwt signature is required'
\* 'invalid signature'
\* 'jwt audience invalid. expected: [OPTIONS AUDIENCE]'
\* 'jwt issuer invalid. expected: [OPTIONS ISSUER]'
\* 'jwt id invalid. expected: [OPTIONS JWT ID]'
\* 'jwt subject invalid. expected: [OPTIONS SUBJECT]'
```js
jwt.verify(token, 'shhhhh', function(err, decoded) {
if (err) {
/\*
err = {
name: 'JsonWebTokenError',
message: 'jwt malformed'
}
\*/
}
});
```
### NotBeforeError
현재 시간이 nbf 클레임 이전인 경우 발생합니다.
에러 객체:
\* name: 'NotBeforeError'
\* message: 'jwt not active'
\* date: 2018-10-04T16:10:44.000Z
```js
jwt.verify(token, 'shhhhh', function(err, decoded) {
if (err) {
/\*
err = {
name: 'NotBeforeError',
message: 'jwt not active',
date: 2018-10-04T16:10:44.000Z
}
\*/
}
});
```
## 지원되는 알고리즘
지원되는 알고리즘 배열입니다. 현재 다음 알고리즘들이 지원됩니다.
| alg 매개변수 값 | 디지털 서명 또는 MAC 알고리즘 |
|---------------------|------------------------------------------------------------------------|
| HS256 | SHA-256 해시 알고리즘을 사용하는 HMAC |
| HS384 | SHA-384 해시 알고리즘을 사용하는 HMAC |
| HS512 | SHA-512 해시 알고리즘을 사용하는 HMAC |
| RS256 | SHA-256 해시 알고리즘을 사용하는 RSASSA-PKCS1-v1\_5 |
| RS384 | SHA-384 해시 알고리즘을 사용하는 RSASSA-PKCS1-v1\_5 |
| RS512 | SHA-512 해시 알고리즘을 사용하는 RSASSA-PKCS1-v1\_5 |
| PS256 | SHA-256 해시 알고리즘을 사용하는 RSASSA-PSS (node ^6.12.0 또는 >=8.0.0 전용) |
| PS384 | SHA-384 해시 알고리즘을 사용하는 RSASSA-PSS (node ^6.12.0 또는 >=8.0.0 전용) |
| PS512 | SHA-512 해시 알고리즘을 사용하는 RSASSA-PSS (node ^6.12.0 또는 >=8.0.0 전용) |
| ES256 | P-256 곡선과 SHA-256 해시 알고리즘을 사용하는 ECDSA |
| ES384 | P-384 곡선과 SHA-384 해시 알고리즘을 사용하는 ECDSA |
| ES512 | P-521 곡선과 SHA-512 해시 알고리즘을 사용하는 ECDSA |
| none | 디지털 서명 또는 MAC 값이 포함되지 않음 |
## JWT 갱신하기
무엇보다도, JWT를 자동으로 갱신하는 것이 시스템에 취약성을 유발하지 않는지 신중하게 생각해 보실 것을 권장합니다.
이 기능을 라이브러리의 일부로 포함하는 것은 적절하지 않다고 판단되지만, 이것이 어떻게 구현될 수 있는지 보여주는 [이 예시](https://gist.github.com/ziluvatar/a3feb505c4c0ec37059054537b38fc48)를 참고하실 수 있습니다.
그 외에도

예를 들어 이 주제에 대해 더 자세히 알아보려면 [이슈](https://github.com/auth0/node-jsonwebtoken/issues/122)와 [풀 리퀘스트](https://github.com/auth0/node-jsonwebtoken/pull/172)를 참고하세요.
# TODO
\* X.509 인증서 체인이 확인되지 않습니다.
## 이슈 신고
버그를 발견하거나 기능 요청이 있는 경우, 본 저장소의 이슈 섹션에 신고해 주세요. 보안 취약점은 공개 GitHub 이슈 추적기에 신고하지 마세요. 보안 취약점 공개 절차에 대한 자세한 내용은 [Responsible Disclosure Program](https://auth0.com/whitehat)을 참고하시기 바랍니다.
## 작성자
[Auth0](https://auth0.com)
## 라이선스
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.