연동 담당이 말합니다. "프론트에서 CORS 에러 나고, Access Token이 만료됐는데 Refresh가 안 돌아요. 결제는 멱등키 없이 재시도해서 중복됐고요. SSO는 SAML Assertion 검증에서 막혔어요." PM·인프라인 당신은 각 문제가 어느 영역이고 누구에게 무엇을 물어야 하는지 판단해야 합니다. 이 사전은 API 연동·인증 용어를 빠르게 해독해, 연동 장애의 방향을 잡게 합니다.
- 1REST/GraphQL·HTTP 메서드·직렬화 용어로 API 구조를 읽을 수 있다
- 2토큰·JWT·OAuth/OIDC/SAML·SSO로 인증 흐름을 구분할 수 있다
- 3CORS·CSRF·SameSite로 브라우저 보안 이슈를 진단할 수 있다
- 4멱등성·레이트리밋·재시도로 연동 안정성 용어를 이해할 수 있다
API 형태와 요청 구성
확대
위 그림처럼 HTTP 메서드별 멱등성과 안전성을 파악하면 연동 안정성 설계의 기반이 되고, Idempotency-Key·Rate Limit·재시도·타임아웃 등 연동 안정성 개념과 SAML/OAuth2/OIDC SSO 방식의 차이도 한눈에 비교할 수 있다.
REST/GraphQL과 요청의 부품들
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| REST API / SOAP / GraphQL | 대표 API 스타일 | REST/GraphQL → API와 계약 | ★★ |
| Endpoint | 호출 주소(경로) | 자원 단위 | ★★ |
| HTTP Method (GET/POST/PUT/PATCH/DELETE) | 행위 | GET=조회(안전) | ★★ |
| Header / Body / Payload | 메타정보 / 본문 / 전송데이터 | 인증·형식은 헤더 | ★★ |
| Query Parameter / Path Variable | ?key=값 / 경로 변수 | 조회 조건 vs 자원 id | ★★ |
| Content-Type / Accept | 보내는/받는 형식 | application/json 등 | ★★ |
| Multipart / Form Data | 파일·폼 전송 형식 | 업로드 | ★ |
| JSON / XML | 데이터 표현 형식 | JSON이 주류 | ★★ |
| Serialization / Deserialization | 객체↔전송형식 변환 | 직렬화 오류 단골 | ★★ |
| Schema Validation / JSON Schema / OpenAPI / Swagger | 형식 검증 / 계약 명세 | 계약 → API와 계약 | ★★ |
인증과 토큰
확대
위 그림처럼 사용자가 로그인하면 인증 서버가 Access Token(단기)과 Refresh Token(장기)을 발급하고, API 서버는 JWT 서명을 검증해 요청을 처리하며, 만료 시 Refresh Token으로 갱신한다.
누구인지 확인하고 권한을 위임하는 용어
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Token / Access Token / Refresh Token | 인증 증표 / 짧은수명 / 재발급용 | 짧은 Access + 긴 Refresh | ★★★ |
| JWT | 서명된 토큰 형식(자체 정보 포함) | 검증이 서버 상태 불필요 | ★★ |
| OAuth / OAuth2 | 권한 위임 프로토콜 | "이 앱이 내 데이터 접근 허용" | ★★ |
| OIDC | OAuth2 위의 인증(로그인) 표준 | 신원 확인 | ★★ |
| SAML / SSO / ACS URL / SAML Assertion / Metadata XML | 기업 SSO(XML) 구성요소 | 사내 통합 로그인 → SAML/OAuth 기반 싱글사인온 구성과 장애 분석 | ★★ |
| Claim / Scope | 토큰 안 정보 / 권한 범위 | 인가 판단 | ★★ |
| Session / Cookie / SameSite | 세션 / 쿠키 / 교차요청 쿠키 정책 | 무상태 vs 세션 → 12-Factor App | ★★ |
| CSRF Token / CORS | 위조요청 방지 / 교차출처 정책 | 브라우저 보안(아래) | ★★★ |
핵심: Access는 짧게·Refresh로 재발급이 표준. SSO 구성(SAML/OAuth)의 깊은 내용은 SAML/OAuth 기반 싱글사인온 구성과 장애 분석에서.
브라우저 보안 — CORS·CSRF
확대
위 그림처럼 HTTPS는 전송 암호화(도청 방지), CORS는 교차 출처 요청 차단(브라우저 정책), CSRF는 세션 악용 방지로 세 가지는 서로 다른 위협을 막는 독립적인 보안 계층이다.
자주 막히는 두 가지
CORS: 브라우저가 '다른 출처(origin)'로의 요청을 기본 차단
증상: 콘솔에 "blocked by CORS policy"
원인: 서버가 허용 출처를 응답 헤더(Access-Control-Allow-Origin)로 안 밝힘
대응: 서버에서 허용 출처/메서드/헤더 설정. (서버-서버 호출엔 무관)
CSRF: 로그인된 사용자의 권한으로 위조 요청을 보내는 공격
대응: CSRF 토큰, SameSite 쿠키 속성
핵심: CORS 에러는 브라우저 환경에서만 나는 클라이언트-서버 정책 이슈입니다. "백엔드는 되는데 프론트에서만 막힌다"면 CORS 1순위 의심. 서버 응답 헤더 설정으로 해결합니다.
연동 안정성 — 멱등·레이트리밋·재시도
중복과 과부하를 다루는 용어
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Idempotency / Idempotency Key | 중복 처리해도 결과 1번 / 그 키 | 결제·주문 필수 → 요구사항 정의 | ★★★ |
| Rate Limit / Throttle | 호출 횟수 제한 / 속도 조절 | 429 응답 → 용어사전 | ★★ |
| Retry / Timeout | 재시도 / 시간 제한 | 멱등 없으면 재시도가 중복 유발 | ★★ |
| Webhook / Callback / Polling | 이벤트 푸시 / 콜백 / 주기 조회 | 연동 방식 → 트래픽 제어와 이벤트 기반 연계 구조 | ★★ |
| API Gateway / Reverse Proxy | API 관문 / 역방향 프록시 | 라우팅·인증·레이트리밋 | ★★ |
핵심: 재시도(Retry)는 멱등성과 짝입니다 — 멱등 보장 없이 재시도하면 중복 결제가 납니다(동기 vs 비동기의 at-least-once와 동일 원리).
연동 에러 해독 — 직접 확인
연동 문제는 상태코드와 에러 메시지로 '어느 영역(인증/권한/형식/CORS)'인지 가릅니다.
# 인증 헤더와 함께 호출해 상태코드·헤더 확인
curl -i https://api.example.com/orders -H "Authorization: Bearer <token>"
HTTP/1.1 401 Unauthorized → 토큰 없음/만료 → Refresh로 재발급
HTTP/1.1 403 Forbidden → 인증은 됐으나 권한 없음(Scope/Role 부족)
HTTP/1.1 429 Too Many Requests → 레이트리밋 초과 → 백오프 후 재시도
(브라우저 콘솔) blocked by CORS → 서버 CORS 허용 설정 필요(브라우저만)
curl -i https://api.example.com/orders -H 'Authorization: Bearer <token>'- 401 Unauthorized → 토큰 없음/만료. Refresh Token으로 재발급 흐름이 동작하는지 확인. 반복되면 토큰 수명/시계 동기 문제
- 403 Forbidden → 인증은 됐는데 권한 부족(Scope/Role). 401과 구분: 401은 "누구인지 모름", 403은 "알지만 안 됨"(용어사전의 RBAC)
- 429 Too Many Requests → 레이트리밋 초과. 즉시 재시도 말고 지수 백오프. 우리가 과호출인지, 상대 한도가 낮은지 확인
- 브라우저 콘솔의 CORS 에러는 서버가 아니라 브라우저 정책 → 서버 응답 헤더(Allow-Origin) 설정. curl(브라우저 아님)로는 재현 안 됨에 주의
상황: 결제 요청이 타임아웃되자 클라이언트가 자동 재시도했는데, 사실 첫 요청은 서버에서 성공 처리된 상태라 결제가 두 번 일어납니다.
원인: 멱등성 미보장입니다. 재시도(Retry)는 안정성 기법이지만, 멱등 키 없이 하면 '같은 결제 두 번'이 됩니다(동기 vs 비동기의 중복 처리와 같은 함정).
진단:
□ 결제 요청에 Idempotency-Key 헤더가 있나?
□ 서버가 같은 키의 중복 요청을 한 번만 처리하나?
□ 타임아웃 후 재시도 정책이 멱등 전제 위에 있나?
해결: 결제·주문 같은 중요 API는 클라이언트가 Idempotency-Key를 보내고, 서버가 그 키로 중복을 흡수(이미 처리한 키면 기존 결과 반환)하게 합니다. 요구사항(요구사항 정의)의 인수 기준에 "중복 요청 시 1건만 처리"를 명시하는 것이 출발점입니다. 재시도와 멱등은 항상 짝으로 설계합니다.
심화 — 무상태의 대가와 '에러만 없앤' 보안 설정
심화: 토큰·CORS 용어가 실전에서 부딪히는 지점
용어를 각각 아는 것과, 두 용어가 한 사건에서 만났을 때 판단하는 것은 다른 수준입니다. 면접도 정확히 이 지점을 파고듭니다.
- 무상태(stateless)의 청구서는 '폐기'에서 날아옵니다: JWT는 서버가 상태를 안 들고 있어 확장에 유리하지만, 뒤집으면 만료 전 토큰을 서버가 무효화할 방법도 없다는 뜻입니다. 탈퇴·권한 회수·탈취 대응으로 "그 토큰은 이제 무효"라고 말하려면 블록리스트나 세션 저장소 — 즉 '상태'를 다시 도입해야 합니다. 면접 단골 후속 질문인 "JWT로 강제 로그아웃은 어떻게 구현하나요?"의 답은 "짧은 Access TTL + Refresh 폐기 + 필요 시 블록리스트"까지 가야 하고, "무상태라서 못 한다"에서 멈추면 안 됩니다.
- Refresh 회전(rotation)은 재사용 탐지와 짝입니다: Refresh Token을 쓸 때마다 새것으로 교체하고, 이미 쓴 토큰이 다시 오면 탈취로 간주해 세션을 끊는 것이 표준입니다. 그런데 이 '재사용 탐지'는 여러 탭·웹+모바일이 동시에 갱신을 시도하는 정상 상황도 탈취로 오인할 수 있습니다. 회전을 도입할 때는 동시 갱신 시나리오를 설계에 반드시 포함해야 합니다.
- CORS 에러를 '없애는 것'과 정책을 '설계하는 것'은 다릅니다: 급한 나머지 요청의 Origin을 그대로 반사해 허용하면서 자격증명(credentials)까지 허용하면, 에러는 사라지지만 아무 사이트나 사용자의 로그인 쿠키를 실어 우리 API를 호출할 수 있게 됩니다. CORS를 넓히는 순간 CSRF 방어(SameSite·CSRF 토큰)의 부담이 그만큼 커집니다 — 두 용어는 반대 방향으로 묶여 있습니다.
"CORS 풀었으니 보안 끝"과 "JWT라 세션 관리 필요 없음"은 각각 CSRF와 토큰 폐기라는 반쪽을 놓친 말입니다. 용어의 '장점'을 들으면 그 대가가 어디서 청구되는지를 함께 물어야 합니다.
상황: 보안 강화를 위해 Refresh Token 회전을 도입했는데, 배포 후 "가만히 있었는데 로그아웃됐다"는 문의가 늘어납니다. 인증 서버 로그에는 token reuse detected가 급증해 있어 처음엔 대규모 토큰 탈취를 의심했습니다.
원인: 탈취가 아니라 동시 갱신 경합입니다. 사용자가 브라우저 탭 여러 개(또는 웹+모바일)를 열어 두면, Access 만료 시점에 여러 클라이언트가 같은 Refresh Token으로 동시에 갱신을 요청합니다. 첫 요청이 토큰을 회전시키는 순간 나머지 요청은 '이미 사용된 토큰'이 되고, 재사용 탐지가 이를 탈취로 판정해 세션 전체를 폐기한 것입니다.
진단:
□ reuse detected가 같은 사용자의 수 초 이내 요청 쌍에서 나는가? (실제 탈취는 보통 시간·IP가 벌어짐)
□ 로그아웃 신고 사용자가 멀티 탭·멀티 기기 사용자인가?
□ 클라이언트에 갱신 요청 중복 방지(탭 간 잠금)가 있는가?
해결: (1) 클라이언트에서 갱신 요청을 단일화합니다 — 탭 간 잠금이나 갱신 전용 큐로 '한 번에 한 갱신'을 보장합니다. (2) 서버는 직전 토큰에 수 초의 유예(grace period)를 둬 동시 갱신을 흡수합니다. (3) reuse 판정 시 IP·시간 간격 같은 맥락을 함께 봐 오탐과 실제 탈취를 구분하고, 실제 탈취 패턴만 알림으로 올립니다(용어사전). 회전은 좋은 보안 장치지만, 동시성 설계 없이 켜면 보안 기능이 가용성 장애로 바뀝니다.
인프라/플랫폼으로서 API 게이트웨이·역방향 프록시에서 인증 검증·레이트리밋·CORS를 중앙 처리하고(트래픽 제어와 이벤트 기반 연계 구조), 토큰 검증·SSO 연동(SAML/OAuth 기반 싱글사인온 구성과 장애 분석)을 운영합니다. 401/403/429의 구분은 대시보드 알람 설계의 기준이 됩니다(용어사전). PM은 이 용어로 연동 요구사항을 명확히 적습니다 — "Idempotency-Key로 중복 방지", "Refresh 토큰 흐름", "허용 출처(CORS)" 같은 항목을 인수 기준에 넣어 연동 사고를 예방합니다. 외부 연동이 많은 서비스일수록 이 사전의 용어가 일상 언어가 됩니다.
다음 용어사전에서는 이 API가 도는 무대 — 서버·WAS·리눅스 운영 용어를 정리합니다.
용어 식별 실습으로 굳히기: 용어 식별 — API / 연동 / 인증 — 증상·문구를 보고 API·인증·연동 용어를 가려내고 헷갈리는 짝을 구분합니다.