# Node.js JWT alg none 점검: jsonwebtoken verify 옵션 확인

> jsonwebtoken 9.0.3의 jwt.verify에 헤더가 alg none이고 서명이 빈 토큰을 넣어 실제 결과와 에러 메시지를 봅니다. algorithms 옵션을 고정해야 하는 이유를 RS256과 HS256 혼동으로 설명합니다. 헤더의 alg를 믿는 검증 코드가 뚫리는 과정도 고친 코드와 함께 실행해 확인합니다.

- 주소: https://copyandrun.com/blog/nodejs-jwt-algorithm-none-check/
- 분야: 시큐어코딩
- 발행일: 2026-11-16
- 태그: JWT, jsonwebtoken, alg none, Node.js, 토큰 검증

`jsonwebtoken` 9.0.3의 `jwt.verify`는 비밀 키를 넘기면 `alg: none` 토큰을 `jwt signature is required`로 거절합니다. 시도한 호출 가운데 통과한 것은 키가 비어 있고 `algorithms`에 `"none"`이 들어 있는 경우 하나였습니다. 반면 토큰 헤더의 `alg`를 읽어 검증 방법을 고르도록 직접 짠 코드는 같은 토큰을 그대로 수락했습니다. 점검할 곳은 `verify`에 넘기는 키와 `algorithms` 옵션, 그리고 라이브러리 밖에서 토큰을 해석하는 코드입니다.

만료, `aud`, 서명 확인 끄기까지 포함한 전체 비교는 [JWT 검증에서 자주 틀리는 것들](/blog/jwt-validation-pitfalls/)에 있습니다. 이 글은 Node.js와 `alg` 검사만 다룹니다.

## 준비물

| 항목 | 내용 |
| --- | --- |
| Node.js | v24.15.0 |
| npm | 11.12.1 |
| jsonwebtoken | 9.0.3 |
| 비밀 키와 토큰 | 이 글에서만 쓰는 demo 값 (실제 서비스에 쓰지 않음) |

이 글의 비밀 키, RSA 키, 토큰은 모두 실습용으로 만든 값입니다. 토큰은 어느 서버에도 보내지 않고 같은 스크립트 안에서 만들고 검증합니다.

## 1. 설치와 버전 확인

```bash
npm init -y
npm install jsonwebtoken
npm ls
```

```text
added 15 packages, and audited 16 packages in 1s

found 0 vulnerabilities

`-- jsonwebtoken@9.0.3
```

출력에서 funding 안내와 폴더 경로 줄은 뺐습니다. 아래 결과는 모두 9.0.3에서 얻은 것이고, 다른 버전에서는 달라질 수 있습니다.

## 2. HS256 토큰 서명과 검증

HS256은 서명하는 쪽과 검증하는 쪽이 같은 비밀 키를 쓰는 HMAC 방식입니다.

```javascript
// 1-sign-verify.js
const jwt = require("jsonwebtoken");

// 실습용으로 만든 값입니다. 실제 서비스에 쓰지 않습니다.
const SECRET = "demo-secret-do-not-use-0123456789abcdef";

const token = jwt.sign({ sub: "alice", role: "user" }, SECRET, {
  algorithm: "HS256",
  expiresIn: "10m",
});
console.log("token :", token);

const [h, p] = token.split(".");
console.log("header:", Buffer.from(h, "base64url").toString());
console.log("payload:", Buffer.from(p, "base64url").toString());

const claims = jwt.verify(token, SECRET, { algorithms: ["HS256"] });
console.log("verify:", claims);

try {
  jwt.verify(token, "wrong-secret", { algorithms: ["HS256"] });
} catch (e) {
  console.log("wrong secret ->", e.name + ":", e.message);
}
```

```bash
node 1-sign-verify.js
```

```text
token : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzk0ODE4OTgyLCJleHAiOjE3OTQ4MTk1ODJ9.V87cAPSDCxLC_fAh1xfVc_4G-ghltXlL03WpOK6wRuU
header: {"alg":"HS256","typ":"JWT"}
payload: {"sub":"alice","role":"user","iat":1794818982,"exp":1794819582}
verify: { sub: 'alice', role: 'user', iat: 1794818982, exp: 1794819582 }
wrong secret -> JsonWebTokenError: invalid signature
```

토큰은 점으로 나뉜 세 칸입니다. 앞의 두 칸은 base64url로 인코딩한 JSON이라 누구나 읽고 고쳐 쓸 수 있습니다. 위조를 막는 것은 셋째 칸의 서명뿐입니다. 그리고 어떤 알고리즘으로 서명했는지는 첫 칸, 곧 공격자가 고칠 수 있는 헤더에 적혀 있습니다. `alg` 문제는 여기서 시작합니다.

## 3. alg none 토큰을 jwt.verify에 넣기

JWT 규격에는 서명이 없는 토큰을 뜻하는 `none` 알고리즘이 있습니다. 헤더를 `{"alg":"none"}`으로 쓰고 서명 칸을 비운 토큰을 손으로 만들어, `jwt.verify`를 여러 방식으로 호출합니다. payload에는 `role: admin`을 넣었습니다.

```javascript
// 2-none-token.js
const jwt = require("jsonwebtoken");

const SECRET = "demo-secret-do-not-use-0123456789abcdef";

const b64 = (obj) => Buffer.from(JSON.stringify(obj)).toString("base64url");

// 헤더의 alg를 none으로 쓰고 서명 칸은 비운다
const noneToken = b64({ alg: "none", typ: "JWT" }) + "." + b64({ sub: "mallory", role: "admin" }) + ".";
console.log("none token:", noneToken);

function attempt(label, fn) {
  try {
    console.log(label, "-> 수락", JSON.stringify(fn()));
  } catch (e) {
    console.log(label, "-> 거절", e.name + ":", e.message);
  }
}

attempt("1) secret, 옵션 없음           ", () => jwt.verify(noneToken, SECRET));
attempt("2) secret, algorithms HS256    ", () => jwt.verify(noneToken, SECRET, { algorithms: ["HS256"] }));
attempt("3) secret, algorithms none 포함", () => jwt.verify(noneToken, SECRET, { algorithms: ["HS256", "none"] }));
attempt("4) secret 없음(undefined)      ", () => jwt.verify(noneToken, undefined));
attempt("5) secret 없음, algorithms none", () => jwt.verify(noneToken, undefined, { algorithms: ["none"] }));
attempt("6) 빈 문자열 secret            ", () => jwt.verify(noneToken, ""));
console.log("7) jwt.decode (검증 안 함)      ->", JSON.stringify(jwt.decode(noneToken)));
```

```bash
node 2-none-token.js
```

```text
none token: eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJzdWIiOiJtYWxsb3J5Iiwicm9sZSI6ImFkbWluIn0.
1) secret, 옵션 없음            -> 거절 JsonWebTokenError: jwt signature is required
2) secret, algorithms HS256     -> 거절 JsonWebTokenError: jwt signature is required
3) secret, algorithms none 포함 -> 거절 JsonWebTokenError: jwt signature is required
4) secret 없음(undefined)       -> 거절 JsonWebTokenError: please specify "none" in "algorithms" to verify unsigned tokens
5) secret 없음, algorithms none -> 수락 {"sub":"mallory","role":"admin"}
6) 빈 문자열 secret             -> 거절 JsonWebTokenError: please specify "none" in "algorithms" to verify unsigned tokens
7) jwt.decode (검증 안 함)      -> {"sub":"mallory","role":"admin"}
```

결과에서 읽을 것은 네 가지입니다.

- **비밀 키를 넘기면 거절됩니다.** 1번부터 3번까지 모두 `jwt signature is required`입니다. 3번처럼 `algorithms`에 `"none"`을 실수로 넣어도 키가 있으면 서명 없는 토큰은 통과하지 못했습니다.
- **키가 비어 있어도 기본값으로는 거절됩니다.** 4번과 6번은 환경 변수를 읽지 못해 키가 `undefined`나 빈 문자열이 된 상황과 같습니다. 이때도 `algorithms`에 `"none"`을 적으라는 메시지와 함께 거절됩니다.
- **키가 비어 있고 `"none"`을 허용하면 수락됩니다.** 5번에서 `role: admin` 토큰이 그대로 통과했습니다. 코드에 `algorithms: ["none"]`이 있거나, 허용 목록을 설정 파일이나 토큰 헤더에서 읽어 오는 곳이 있으면 이 경로가 열립니다.
- **`jwt.decode`는 검증하지 않습니다.** 7번은 서명을 보지 않고 payload를 돌려줍니다. `decode` 결과로 권한을 판단하는 코드는 라이브러리 버전과 상관없이 위조 토큰을 받아들입니다.

## 4. algorithms를 고정해야 하는 이유: RS256과 HS256 혼동

`none`만 문제가 아닙니다. 서버가 RS256(개인 키로 서명, 공개 키로 검증)을 쓰는데 검증 코드가 헤더의 `alg`를 따르면, 공격자는 헤더를 HS256으로 바꿉니다. 그리고 누구나 얻을 수 있는 공개 키 PEM 문자열을 HMAC 비밀 키로 써서 서명합니다. 검증하는 쪽이 같은 공개 키로 HMAC을 계산하면 서명이 맞아떨어집니다.

실습용 RSA 키를 만들고, 이 방식으로 위조한 토큰을 `jwt.verify`에 넣어 봅니다.

```javascript
// 3-confusion.js
const crypto = require("crypto");
const jwt = require("jsonwebtoken");

// 실습용 RSA 키 쌍을 실행할 때마다 새로 만든다
const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
  modulusLength: 2048,
  publicKeyEncoding: { type: "spki", format: "pem" },
  privateKeyEncoding: { type: "pkcs8", format: "pem" },
});

const b64 = (v) => Buffer.from(typeof v === "string" ? v : JSON.stringify(v)).toString("base64url");

function attempt(label, fn) {
  try {
    console.log(label, "-> 수락", JSON.stringify(fn()));
  } catch (e) {
    console.log(label, "-> 거절", e.name + ":", e.message);
  }
}

// 정상: 서버가 개인키로 RS256 서명
const good = jwt.sign({ sub: "alice", role: "user" }, privateKey, { algorithm: "RS256", noTimestamp: true });
attempt("정상 RS256, algorithms RS256      ", () => jwt.verify(good, publicKey, { algorithms: ["RS256"] }));

// 공격: 공개키 PEM 문자열을 HMAC 비밀로 써서 HS256 토큰을 손으로 만든다
const head = b64({ alg: "HS256", typ: "JWT" }) + "." + b64({ sub: "mallory", role: "admin" });
const sig = crypto.createHmac("sha256", publicKey).update(head).digest("base64url");
const forged = head + "." + sig;

attempt("혼동 토큰, algorithms RS256        ", () => jwt.verify(forged, publicKey, { algorithms: ["RS256"] }));
attempt("혼동 토큰, 옵션 없음               ", () => jwt.verify(forged, publicKey));
attempt("혼동 토큰, algorithms HS256        ", () => jwt.verify(forged, publicKey, { algorithms: ["HS256"] }));
attempt("혼동 토큰, 헤더의 alg를 그대로 허용", () => {
  const alg = jwt.decode(forged, { complete: true }).header.alg;
  return jwt.verify(forged, publicKey, { algorithms: [alg] });
});
```

```bash
node 3-confusion.js
```

```text
정상 RS256, algorithms RS256       -> 수락 {"sub":"alice","role":"user"}
혼동 토큰, algorithms RS256         -> 거절 JsonWebTokenError: invalid algorithm
혼동 토큰, 옵션 없음                -> 거절 JsonWebTokenError: invalid algorithm
혼동 토큰, algorithms HS256         -> 거절 JsonWebTokenError: secretOrPublicKey must be a symmetric key when using HS256
혼동 토큰, 헤더의 alg를 그대로 허용 -> 거절 JsonWebTokenError: secretOrPublicKey must be a symmetric key when using HS256
```

9.0.3에서는 혼동 공격이 재현되지 않았습니다. 헤더의 `alg`를 그대로 허용 목록에 넣는 잘못된 호출까지 거절됐습니다. 공개 키 PEM을 HS256 검증 키로 쓰지 못하게 라이브러리가 막기 때문입니다. `algorithms`를 생략했을 때도 `invalid algorithm`으로 거절됐습니다.

그래도 `algorithms: ["RS256"]`은 적어야 합니다. 위 결과는 이 버전이 키 종류를 보고 막아 준 것이고, 그 방어는 버전과 라이브러리마다 다릅니다. 허용 목록을 코드에 적어 두면 라이브러리의 기본 동작에 기대지 않고 서버 코드가 직접 막습니다. 거절 사유도 `invalid algorithm`으로 분명해집니다.

방어가 없는 코드에서는 이 공격이 실제로 통합니다. 같은 키 하나를 받아 헤더의 `alg`에 따라 RSA 검증과 HMAC 검증 중 하나를 고르는 검증기를 직접 만들어 확인했습니다.

```javascript
// 5-confusion-handrolled.js (검증기 두 개만 발췌)

// 취약한 예: 키는 하나인데 알고리즘은 토큰 헤더가 고른다
function verifyByHeader(token, key) {
  const [h, p, s] = token.split(".");
  const header = JSON.parse(Buffer.from(h, "base64url").toString());
  const data = h + "." + p;
  let ok = false;
  if (header.alg === "RS256") {
    ok = crypto.verify("RSA-SHA256", Buffer.from(data), key, Buffer.from(s, "base64url"));
  } else if (header.alg === "HS256") {
    ok = crypto.createHmac("sha256", key).update(data).digest("base64url") === s;
  }
  if (!ok) throw new Error("invalid signature");
  return JSON.parse(Buffer.from(p, "base64url").toString());
}

// 고친 예: 서버가 RS256만 받는다
function verifyPinned(token, key) {
  const [h, p, s] = token.split(".");
  const header = JSON.parse(Buffer.from(h, "base64url").toString());
  if (header.alg !== "RS256") throw new Error("alg not allowed: " + header.alg);
  const ok = crypto.verify("RSA-SHA256", Buffer.from(h + "." + p), key, Buffer.from(s || "", "base64url"));
  if (!ok) throw new Error("invalid signature");
  return JSON.parse(Buffer.from(p, "base64url").toString());
}
```

두 검증기에 공개 키를 주고, 개인 키로 서명한 정상 토큰과 위와 같은 방식으로 만든 혼동 토큰을 넣습니다.

```bash
node 5-confusion-handrolled.js
```

```text
== verifyByHeader
  정상 RS256 -> 수락 sub=alice role=user
  HS256 혼동 -> 수락 sub=mallory role=admin
== verifyPinned
  정상 RS256 -> 수락 sub=alice role=user
  HS256 혼동 -> 거절 (alg not allowed: HS256)
```

`verifyByHeader`는 개인 키 없이 만든 `role: admin` 토큰을 정상 토큰과 똑같이 받아들입니다.

## 5. 헤더의 alg를 믿는 검증 코드와 고친 코드

`none`도 같은 구조에서 뚫립니다. 라이브러리 없이 HS256 검증을 직접 짠 코드를 가정합니다. "규격에 있는 알고리즘이니 지원한다"는 생각으로 `none` 분기를 넣은 것이 취약점입니다.

```javascript
// verify-vulnerable.js
const crypto = require("crypto");

// 취약한 예: 토큰 헤더의 alg를 읽어 그 값에 따라 검증 방법을 고른다
function verifyVulnerable(token, secret) {
  const [h, p, s] = token.split(".");
  const header = JSON.parse(Buffer.from(h, "base64url").toString());
  const payload = JSON.parse(Buffer.from(p, "base64url").toString());

  if (header.alg === "none") {
    return payload; // 서명이 없다는 토큰의 말을 그대로 믿는다
  }
  if (header.alg === "HS256") {
    const expected = crypto.createHmac("sha256", secret).update(h + "." + p).digest("base64url");
    if (s === expected) return payload;
    throw new Error("invalid signature");
  }
  throw new Error("unsupported alg: " + header.alg);
}

module.exports = verifyVulnerable;
```

고친 코드는 허용할 알고리즘을 상수로 두고, 헤더의 `alg`는 그 값과 같은지 비교하는 데만 씁니다.

```javascript
// verify-fixed.js
const crypto = require("crypto");

const ALLOWED_ALG = "HS256"; // 서버가 정한 값. 토큰이 바꿀 수 없다

function verifyFixed(token, secret) {
  const parts = token.split(".");
  if (parts.length !== 3) {
    throw new Error("malformed token");
  }
  const [h, p, s] = parts;
  const header = JSON.parse(Buffer.from(h, "base64url").toString());
  if (header.alg !== ALLOWED_ALG) {
    throw new Error("alg not allowed: " + header.alg);
  }

  const expected = crypto.createHmac("sha256", secret).update(h + "." + p).digest();
  const given = Buffer.from(s, "base64url");
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    throw new Error("invalid signature");
  }

  const payload = JSON.parse(Buffer.from(p, "base64url").toString());
  if (typeof payload.exp !== "number" || payload.exp <= Math.floor(Date.now() / 1000)) {
    throw new Error("token expired or exp missing");
  }
  return payload;
}

module.exports = verifyFixed;
```

토큰 네 개를 두 검증기에 넣습니다. 정상 토큰, `alg: none` 토큰, 정상 토큰에서 서명만 지운 토큰, 다른 비밀 키로 서명한 토큰입니다.

```javascript
// 4-handrolled.js
const jwt = require("jsonwebtoken");
const verifyVulnerable = require("./verify-vulnerable");
const verifyFixed = require("./verify-fixed");

const SECRET = "demo-secret-do-not-use-0123456789abcdef";
const b64 = (obj) => Buffer.from(JSON.stringify(obj)).toString("base64url");

const tokens = {
  "정상 HS256": jwt.sign({ sub: "alice", role: "user" }, SECRET, { algorithm: "HS256", expiresIn: "10m" }),
  "alg none  ": b64({ alg: "none", typ: "JWT" }) + "." + b64({ sub: "mallory", role: "admin" }) + ".",
  "서명 삭제 ": null,
  "다른 비밀 ": jwt.sign({ sub: "mallory", role: "admin" }, "attacker-secret", { algorithm: "HS256", expiresIn: "10m" }),
};

// 정상 토큰에서 서명만 지운 것 (헤더는 HS256 그대로)
tokens["서명 삭제 "] = tokens["정상 HS256"].split(".").slice(0, 2).join(".") + ".";

for (const [name, verify] of [["verifyVulnerable", verifyVulnerable], ["verifyFixed", verifyFixed]]) {
  console.log("== " + name);
  for (const [label, token] of Object.entries(tokens)) {
    try {
      const c = verify(token, SECRET);
      console.log(`  ${label} -> 수락 sub=${c.sub} role=${c.role}`);
    } catch (e) {
      console.log(`  ${label} -> 거절 (${e.message})`);
    }
  }
}
```

```bash
node 4-handrolled.js
```

```text
== verifyVulnerable
  정상 HS256 -> 수락 sub=alice role=user
  alg none   -> 수락 sub=mallory role=admin
  서명 삭제  -> 거절 (invalid signature)
  다른 비밀  -> 거절 (invalid signature)
== verifyFixed
  정상 HS256 -> 수락 sub=alice role=user
  alg none   -> 거절 (alg not allowed: none)
  서명 삭제  -> 거절 (invalid signature)
  다른 비밀  -> 거절 (invalid signature)
```

취약한 검증기는 서명을 지우기만 한 토큰과 다른 비밀 키로 서명한 토큰은 막았습니다. 그래서 서명 검증이 동작하는 것처럼 보입니다. 뚫린 것은 헤더를 `none`으로 바꾼 토큰 하나였고, 그 하나로 `admin` 권한이 넘어갔습니다. 서명 검증 테스트에 `alg`를 바꾼 토큰이 없으면 이 구멍은 드러나지 않습니다.

`verifyFixed`는 원리를 보이려고 짧게 만든 코드입니다. 실제 서비스에서는 직접 만든 검증기 대신 `jwt.verify`에 `algorithms`를 고정해서 씁니다.

## 6. 결과 비교와 점검 항목

| 검증 방식 | `alg: none` 토큰 | HS256 혼동 토큰 |
| --- | --- | --- |
| `jwt.verify(token, secret)` | 거절 (`jwt signature is required`) | 해당 없음 |
| `jwt.verify(token, undefined, { algorithms: ["none"] })` | 수락 | 해당 없음 |
| `jwt.verify(token, publicKey, { algorithms: ["RS256"] })` | 실행하지 않음 | 거절 (`invalid algorithm`) |
| `jwt.verify(token, publicKey)` | 실행하지 않음 | 거절 (`invalid algorithm`) |
| `jwt.decode(token)` | payload 반환 (검증 없음) | 실행하지 않음 |
| 직접 만든 검증기, 헤더의 `alg`를 따름 | 수락 | 수락 |
| 직접 만든 검증기, `alg` 고정 | 거절 | 거절 |

Node.js 코드에서 JWT 검증을 점검할 때는 다음을 찾습니다.

1. `jwt.verify` 호출마다 `algorithms`가 배열 리터럴로 적혀 있는지 확인합니다. 변수나 토큰 헤더에서 온 값이면 그 출처를 따라갑니다.
2. 코드 전체에서 `"none"`을 검색합니다. `algorithms`에 `"none"`이 들어 있으면 지웁니다.
3. `verify`에 넘기는 키가 비어 있을 수 있는지 봅니다. 환경 변수에서 읽는다면 값이 없을 때 서버가 시작하지 않게 합니다.
4. `jwt.decode`의 결과가 인증이나 권한 판단에 쓰이는 곳이 없는지 확인합니다.
5. `split(".")`과 `base64url`로 토큰을 직접 해석하는 코드가 있으면 `alg`를 어떻게 다루는지 읽습니다.
6. 인증 단위 테스트에 `alg: none` 토큰과 알고리즘을 바꾼 토큰을 넣고, 둘 다 거절되는지 확인합니다.

## 자주 묻는 질문

**최신 `jsonwebtoken`을 쓰면 `algorithms` 옵션을 생략해도 됩니까?**

9.0.3은 생략해도 이 글의 위조 토큰을 거절했지만, 허용 알고리즘을 서버가 정해 둔다는 사실이 코드에 남도록 항상 적는 편이 안전합니다.

**`jwt.decode`는 언제 써도 됩니까?**

서명을 확인하지 않으므로 로그에 `kid`를 남기는 것처럼 신뢰가 필요 없는 용도에만 쓰고, 인증과 권한 판단에는 `jwt.verify`의 반환값만 씁니다.

**HS256과 RS256 중 무엇을 골라야 합니까?**

토큰을 발급하는 서버와 검증하는 서버가 같으면 HS256으로 충분하고, 검증하는 쪽이 여러 곳이면 비밀 키를 공유하지 않아도 되는 RS256이 맞습니다.
