본문으로 건너뛰기
← Systems Notebook / SEC
API 키 교체SECURITY NOTES

API 키를 바꿨는데 왜 일부 요청만 실패할까요?

API 제공자가 허용하는 키와 저장소에 넣은 키, 각 작업자가 실제로 쓰는 키가 다르면 어떤 문제가 생기는지 살펴봅니다.

홍범개념 설명 · 움직이는 예제

문서함 서비스에서 파일의 미리보기를 만드는 작업자 둘이 같은 외부 변환 API를 호출한다고 가정해 보겠습니다. API 키를 교체한 뒤 작업자 1의 요청은 성공하지만 작업자 2가 맡은 요청은 인증 오류로 끝납니다. 키 저장소에는 분명 새 키가 들어 있고 두 작업자가 같은 저장소를 사용하는데, 왜 결과가 다를까요?

저장소에 새 키가 있어도 실행 중인 작업자는 옛 키를 계속 쓸 수 있습니다. 그 요청의 성공 여부는 API 제공자가 옛 키를 아직 허용하는지에 달려 있습니다. 저장소의 값과 작업자가 읽어 둔 값, 제공자의 허용 상태가 서로 어긋난 상황입니다.

여기서는 유출 사고가 없는 정상 교체를 다룹니다. 예시의 API 제공자는 같은 권한을 가진 두 키를 동시에 허용합니다. 모든 제공자가 이런 교체 방식을 지원하는 것은 아닙니다.

저장소의 새 값이 바로 모든 요청에 들어가지는 않습니다

이 예시의 작업자는 시작할 때 저장소에서 API 키를 한 번 읽고, 이후 요청에는 읽어 둔 값을 사용합니다. 처음에는 제공자가 KEY-OLD를 허용하고, 저장소와 두 작업자에도 KEY-OLD가 들어 있습니다. 여기서 키 이름은 상태를 구분하기 위한 표기이며 실제 비밀값은 아닙니다.

제공자에 새 키를 추가한 뒤 저장소를 KEY-NEW로 바꿔도, 이미 실행 중인 작업자 안의 값은 그대로입니다. 작업자 1만 다시 시작하면 작업자 1은 새 키를 읽고, 아직 다시 시작하지 않은 작업자 2는 옛 키를 계속 사용합니다. 저장소에서 새 값을 확인했어도 각 작업자가 어느 키로 요청하는지는 따로 확인해야 합니다.

저장소를 바꿔도 프로세스 안의 값은 남습니다

단계 설명과 조건별 결과
  1. 저장소와 두 작업자의 메모리에는 KEY-OLD가 있습니다. 작업자는 시작할 때 한 번 읽습니다.
  2. 제공자는 KEY-NEW도 허용합니다. 저장소나 작업자의 메모리는 아직 바뀌지 않습니다.
  3. 저장소가 KEY-NEW로 바뀌지만 실행 중인 두 작업자에는 KEY-OLD가 남아 있습니다.
  4. 작업자 1을 다시 시작해 저장소의 새 값을 읽습니다. 아직 메모리에는 도착 전입니다.
  5. 작업자 1은 KEY-NEW를 읽었습니다. 작업자 2는 KEY-OLD를 유지합니다. 두 키가 모두 유효한 동안은 둘 다 요청할 수 있습니다.
  6. 한 작업자만 새 값을 읽었습니다. 저장소 갱신이나 일부 요청 성공만으로 전체 전환 완료라고 판단할 수 없습니다.

작업자 1만 다시 읽기 — 한 작업자만 새 값을 읽었습니다. 저장소 갱신이나 일부 요청 성공만으로 전체 전환 완료라고 판단할 수 없습니다.

두 작업자 차례로 읽기 — 두 작업자 모두 KEY-NEW를 읽었습니다. 실제 전환 확인에는 각 작업자가 이 키로 보낸 요청의 성공도 필요합니다.

제공자가 옛 키를 더 이상 받아들이지 않으면 그 키를 쓰는 작업자의 요청이 실패합니다. 새 키를 보낸 작업자 1은 통과하고, 옛 키를 보낸 작업자 2는 거부됩니다. 두 작업자는 같은 저장소에서 서로 다른 시점에 키를 읽었습니다. 일부 요청이 성공하면 새 키로 요청하는 작업자가 있다는 근거는 될 수 있지만, 모든 작업자의 교체가 끝났다고 볼 수는 없습니다.

같은 API에 도착한 두 요청의 키가 다릅니다

단계 설명과 조건별 결과
  1. 작업자 1은 KEY-NEW, 작업자 2는 KEY-OLD를 요청에 붙입니다. 아직 요청을 보내지 않았습니다.
  2. 제공자가 KEY-OLD 허용을 끝냅니다. 작업자가 읽어 둔 값은 바뀌지 않습니다.
  3. 각 키를 붙인 변환 요청이 API 제공자로 이동합니다. 아직 응답 결과는 표시하지 않습니다.
  4. 새 키 요청은 성공하고 옛 키 요청만 거부됩니다. 같은 저장소를 썼어도 읽은 시점이 달랐습니다.

옛 키 먼저 폐기 — 새 키 요청은 성공하고 옛 키 요청만 거부됩니다. 같은 저장소를 썼어도 읽은 시점이 달랐습니다.

두 키 허용 유지 — 요청은 둘 다 성공하지만 작업자 2는 옛 키를 사용했습니다. 새 키 사용과 해당 요청의 성공을 함께 확인해야 전환 완료입니다.

옛 키가 유효한 동안 작업자들이 새 키를 읽게 합니다

이 실패를 피하려면 옛 키를 폐기하기 전에 모든 작업자가 새 키로 요청하도록 바꿔야 합니다.

옛 키가 유효한 상태에서 새 키를 만들어 저장소에 넣고, 작업자들이 차례로 새 값을 읽도록 합니다. 작업자 1만 새 키를 읽은 중간 상태에서도 두 키가 모두 유효하므로 두 작업자의 요청은 성공합니다. Microsoft의 두 키를 이용한 교체 절차도 애플리케이션이 새 키를 쓰도록 바꾸고 실제로 전환했는지 확인한 뒤 이전 키를 바꾸도록 안내합니다.

다만 요청이 모두 성공한다는 이유로 옛 키를 폐기하면 다시 일부 요청이 실패할 수 있습니다. 지금은 옛 키도 유효해서, 전환하지 않은 작업자의 요청까지 성공하기 때문입니다. 각 작업자가 KEY-NEW를 사용하고 그 키로 변환 요청을 처리하는지까지 확인해야 합니다.

작업자에서 확인한 내용 요청 결과 전환 판정
KEY-OLD 사용 성공 옛 키도 유효해서 성공한 상태입니다. 새 키 전환은 끝나지 않았습니다.
KEY-NEW를 읽음 해당 요청의 결과 확인 전 새 값을 읽었지만 필요한 동작이 되는지는 아직 확인하지 못했습니다.
KEY-NEW 사용 해당 변환 요청 성공 그 작업자의 새 키 전환을 확인했습니다. 다른 작업자는 별도로 확인합니다.

마지막에는 옛 키가 더 이상 통하지 않는지도 확인합니다

두 작업자가 새 키로 동작하면 제공자에서 옛 키를 폐기합니다. 제공자가 그 키를 거부하도록 바꾸는 일입니다. 저장소의 옛 값을 지우기만 하면 이미 복사해 둔 옛 키 요청을 제공자가 여전히 받아들일 수 있습니다.

폐기 이후에는 새 키 요청은 계속 성공하고 옛 키 요청은 거부돼야 합니다. AWS의 접근 키 교체 절차에서도 새 키로 애플리케이션을 전환한 뒤 이전 키를 비활성화하고, 새 키만으로 동작하는지 확인합니다. 이전 키를 계속 사용하는 애플리케이션은 그 시점에 접근할 수 없게 됩니다.

복사본 삭제와 제공자의 허용 종료를 구분합니다

단계 설명과 조건별 결과
  1. 작업자들은 KEY-NEW를 사용하지만 제공자는 아직 KEY-OLD도 허용합니다.
  2. 제공자가 KEY-OLD를 더 이상 받아들이지 않도록 바꿉니다. 복사본이 남아 있어도 효력은 종료됩니다.
  3. 현재 새 키 요청과 비교용 옛 키 요청이 제공자에게 이동합니다. 응답은 아직 확인 전입니다.
  4. 새 키 요청은 성공하고 남아 있는 옛 복사본의 요청은 거부됩니다.

제공자에서 폐기 — 새 키 요청은 성공하고 남아 있는 옛 복사본의 요청은 거부됩니다.

보관본만 삭제 — 새 키와 옛 복사본의 요청 모두 허용됩니다. 파일 삭제만으로 키의 효력이 끝나지는 않습니다.

처음의 일부 요청 실패는 모든 작업자가 새 키를 읽기 전에 기존 키를 폐기해서 생겼습니다. 교체를 마칠 때는 아래 순서대로 제공자·저장소·각 작업자의 상태가 맞는지 확인합니다.

정상 교체의 순서 다음으로 넘어가기 전에 확인할 상태
제공자에서 새 키 허용 필요한 권한으로 새 키를 사용할 수 있고, 전환 중에는 옛 키도 유효합니다.
저장소를 새 키로 갱신 저장소의 현재 값이 KEY-NEW입니다. 실행 중인 작업자의 값은 아직 별개입니다.
각 작업자가 새 값 읽기 모든 작업자가 KEY-NEW를 사용하며, 그 키로 필요한 요청이 성공합니다.
제공자에서 옛 키 허용 종료 새 키 요청은 계속 성공하고, 비교용 옛 키 요청은 거부됩니다.

그림과 애니메이션은 본문의 조건을 단순화한 설명용 예시입니다.