본문으로 건너뛰기

서명 키 교체하기 (OSS)

노트:

Logto Cloud를 사용 중이라면, Console UI에서 서명 키를 교체할 수 있습니다. 자세한 내용은 이 튜토리얼을 참고하세요.

Logto OSS는 v1.8부터 서명 키 교체를 지원합니다.

Logto OIDC 서명 키(“OIDC 프라이빗 키” 및 “OIDC 쿠키 키”라고도 함)는 Logto 로그인 세션에서 JWT(액세스 토큰 (Access token) 및 ID 토큰 (ID token))과 브라우저 쿠키를 서명하는 데 사용되는 서명 키입니다.

서명 키를 정기적으로 교체하면 잠재적인 키 유출 위험을 줄일 수 있습니다. Logto는 최소 1년에 한 번 서명 키를 교체할 것을 권장합니다.

OIDC 프라이빗 서명 키 교체하기​

아래 CLI 명령어를 사용하여 새로운 OIDC 프라이빗 서명 키를 생성하세요. 기본적으로 새 키는 즉시 적용됩니다. 교체를 준비하고 클라이언트가 새로운 키로 JWT가 서명되기 전에 JWKS를 갱신할 시간을 주려면, 유예 기간을 설정하세요.

사용 가능한 옵션:

--type          (선택 사항) JWT에 사용할 서명 키 알고리즘입니다.
                값은 "rsa" 또는 "ec"입니다. 기본값은 "ec"입니다.
--gracePeriod   (선택 사항) 프라이빗 키 교체를 준비하는 유예 기간(초)입니다.
                기본값은 PRIVATE_KEY_ROTATION_GRACE_PERIOD 환경 변수이며, 설정되지 않은 경우 0입니다.
logto db config rotate oidc.privateKeys --type rsa

예를 들어, 새 프라이빗 키가 활성화되기 전 4시간 동안 준비 상태로 두려면 다음과 같이 입력하세요:

logto db config rotate oidc.privateKeys --type rsa --gracePeriod 14400

프라이빗 키 교체의 기본 유예 기간은 환경 변수로도 설정할 수 있습니다:

PRIVATE_KEY_ROTATION_GRACE_PERIOD=14400

이 환경 변수는 Admin Console 또는 Management API를 통해 교체할 때 Logto 서비스에 설정하거나, CLI 명령어로 교체할 때는 해당 셸에 설정하세요.

아래 CLI 명령어를 사용하여 새로운 OIDC 쿠키 키를 생성하세요. 쿠키 키 교체는 유예 기간을 지원하지 않습니다.

logto db config rotate oidc.cookieKeys

이전 키는 어떻게 되나요?​

OIDC 프라이빗 키의 경우, Logto는 교체 준비 중 최대 세 개의 키를 유지합니다:

  • Next: 유예 기간이 끝나기를 기다리는 새 키.
  • Current: 새로 발급되는 JWT를 서명하는 데 현재 사용되는 키.
  • Previous: 최근에 교체된 이전 키로, 기존 JWT가 유효하도록 유지됩니다.

유예 기간이 끝나면 Next 키가 Current가 되고, 기존 Current 키는 Previous가 되며, 가장 오래된 Previous 키는 삭제됩니다.

쿠키 키의 경우, Logto는 현재 키와 이전 키를 유지합니다. 이전 키를 삭제할 때는 예기치 않은 문제가 발생할 수 있으므로 주의하세요. 해당 키로 서명된 모든 기존 세션 또는 토큰이 만료되었음을 확신할 때까지 이전 키를 유지하는 것이 좋습니다.

문제 해결​

Cloudflare Zero Trust에서 Logto를 OIDC Provider로 사용할 때​

Cloudflare Zero Trust에서 Logto를 OIDC provider로 사용하려는 경우, ECDSA 알고리즘을 사용하는 OIDC provider는 지원하지 않는다는 점에 유의하세요. OIDC 프라이빗 서명 키를 교체할 때, 반드시 --type rsa를 명령어에 지정하여 RSA 알고리즘을 사용해야 합니다:

logto db config rotate oidc.privateKeys --type rsa