[Spring Security] JWT 발급 · 검증 일반 가이드

아래 예시는 “일반적인 JWT 구조”와 “대표적인 클레임”만을 검증하는 형태로 정리한 가이드입니다. 이대로 복사해서 쓰시면, 어떤 토큰이든 쉽게 적용할 수 있습니다.

---

JWT 발급·검증 일반 가이드

1. 수동 검증 (jwt.io)

1. jwt.io(https://jwt.io) 에 접속
2. 좌측 Encoded 상자에 accessToken 전체 문자열을 붙여넣기
3. 우측 Decoded ▶ Payload 영역에서 다음을 확인
   • Standard Claims
     • sub (Subject) → 토큰 대상 식별자(예: 사용자 ID 또는 이름)
     • iat (Issued At) → 발급 시각
     • exp (Expiration) → 만료 시각
   • Custom Claims
     • 프로젝트별로 넣은 커스텀 키(예: role, scope, userId 등)가 올바르게 들어갔는지

Tip:

• Header에서 알고리즘(alg)과 타입(typ)도 함께 보는 것이 좋습니다.
• Signature 만료 여부는 jwt.io가 자동으로 검증해 줍니다.

---

2. 자동 검증 (Postman Tests)

2-1. 요청 설정 예시

항목	설정 예시
Method	POST
URL	http://localhost:8080/…/login
Headers	Content-Type: application/json
Body	{ "username": "…", "password": "…" } (프로젝트별 페이로드)

2-2. Tests 탭 스크립트

Postman의 Tests 탭(=post-response)에 복사·붙여넣으세요.

// --- 0) JSON 응답이 아닐 경우 스킵 ---
const contentType = pm.response.headers.get("Content-Type") || "";
if (!contentType.includes("application/json")) {
    pm.test("Response is not JSON, skip JWT tests", () => {});
    return;
}

// --- 1) 응답 JSON 파싱 ---
const data = pm.response.json();

// --- 2) accessToken 구조 검증 (헤더.페이로드.서명) ---
pm.test("accessToken has 3 segments", () => {
    pm.expect(data.accessToken.split(".")).to.have.lengthOf(3);
});

// --- 3) Payload 디코딩 ---
const tokenParts = data.accessToken.split(".");
const payload    = JSON.parse(atob(tokenParts[1]));  // atob(): Base64 디코딩

// --- 4) 필수 Standard Claims 검증 ---
pm.test("Payload contains sub (subject)", () => {
    pm.expect(payload).to.have.property("sub");
});
pm.test("Payload contains iat (issued at)", () => {
    pm.expect(payload).to.have.property("iat");
});
pm.test("Payload contains exp (expiration)", () => {
    pm.expect(payload).to.have.property("exp");
});

// --- 5) (선택) Custom Claim 검증 예시 ---
// 예: 클레임 키가 "role" 이면, 존재 여부만 확인
pm.test("Payload contains custom claim 'role'", () => {
    pm.expect(payload).to.have.property("role");
});

// --- 6) Refresh Token 구조 검증 (선택) ---
pm.test("refreshToken has 3 segments", () => {
    pm.expect(data.refreshToken.split(".")).to.have.lengthOf(3);
});

2-3. 테스트 결과 확인

1. Send 버튼 클릭
2. 하단 Test Results 탭에서 각 테스트가 PASS/FAIL 로 표시

팁

• pm.expect(…) 은 Chai Assertion Library 문법입니다.
• “[].split(‘.’).lengthOf(3)” 처럼 다양한 구조 검증을 추가할 수 있습니다.
• 특정 값(예: sub === "someUserId")을 완전히 고정해서 검사하려면, pm.expect(payload.sub).to.eql("expectedValue") 형태로 확장하세요.

---

3. 요약

• jwt.io 로 빠르게 수동 구조·클레임 확인
• Postman Tests 로 자동화된 구조·필수 클레임 검증
• “sub, iat, exp” 처럼 표준 클레임은 무조건,
• “role, scope” 등 커스텀 클레임은 프로젝트별로 확인

위 가이드를 “API 문서”나 “테스트 스크립트”에 포함해 두면,
언제든 새로 발급된 JWT가 올바른 형식과 필수 페이로드를 담고 있는지 즉시 검증할 수 있습니다.