서명 키

Logto OIDC 서명 키는 "OIDC 개인 키" 또는 "OIDC 쿠키 키"라고도 불리며, Logto 로그인 세션에서 JWT (액세스 토큰 및 ID 토큰)과 브라우저 쿠키를 서명하는 데 사용되는 서명 키입니다. 이러한 서명 키는 Logto 데이터베이스를 시드할 때 (오픈소스) 또는 새 테넌트를 생성할 때 (Cloud) 생성되며, CLI (오픈소스), Management API 또는 Console UI를 통해 관리할 수 있습니다.

기본적으로 Logto는 타원 곡선 (EC) 알고리즘을 사용하여 디지털 서명을 생성합니다. 하지만 사용자가 JWT 서명을 검증해야 하는 경우가 많고, 많은 구버전 도구들이 EC 알고리즘을 지원하지 않고 RSA만 지원하기 때문에, 개인 키를 교체(로테이션)하고 서명 알고리즘(RSA 및 EC 모두 포함)을 선택할 수 있는 기능을 구현했습니다. 이를 통해 구식 서명 검증 도구를 사용하는 서비스와의 호환성을 보장합니다.

노트:

이론적으로 서명 키는 유출되어서는 안 되며 만료 시간이 없으므로 교체할 필요가 없습니다. 그러나 일정 기간 후에 주기적으로 서명 키를 교체하면 보안을 강화할 수 있습니다.

동작 방식

• OIDC 개인 키 Logto 인스턴스를 초기화할 때, 공개 키와 개인 키 쌍이 자동으로 생성되어 기본 OIDC 제공자에 등록됩니다. 따라서 Logto가 새로운 JWT(액세스 토큰 또는 ID 토큰)를 발급할 때, 해당 토큰은 개인 키로 서명됩니다. 동시에, JWT를 수신하는 모든 클라이언트 애플리케이션은 쌍으로 제공되는 공개 키를 사용하여 토큰 서명을 검증할 수 있으므로, 토큰이 제3자에 의해 변조되지 않았음을 보장할 수 있습니다. 개인 키는 Logto 서버에서 안전하게 보호됩니다. 반면, 공개 키는 이름 그대로 모두에게 공개되어 있으며, OIDC 엔드포인트의 /oidc/jwks 인터페이스를 통해 접근할 수 있습니다. 개인 키를 생성할 때 서명 키 알고리즘을 지정할 수 있으며, Logto는 기본적으로 EC (타원 곡선) 알고리즘을 사용합니다. 관리자는 개인 키를 교체(로테이션)하여 기본 알고리즘을 RSA (Rivest-Shamir-Adleman)로 변경할 수 있습니다.
• OIDC 쿠키 키 사용자가 로그인 또는 회원가입 플로우를 시작하면, 서버에 "OIDC 세션"이 생성되고 브라우저 쿠키 세트도 함께 생성됩니다. 이 쿠키를 통해 브라우저는 Logto Experience API에 요청하여 로그인, 회원가입, 비밀번호 재설정 등 일련의 상호작용을 사용자를 대신해 수행할 수 있습니다. 하지만 JWT와 달리, 쿠키는 Logto OIDC 서비스 자체에서만 서명 및 검증되며, 비대칭 암호화가 필요하지 않습니다. 따라서 쿠키 서명 키에는 쌍으로 된 공개 키가 없으며, 비대칭 암호화 알고리즘도 사용하지 않습니다.

Console UI에서 서명 키 교체하기

Logto는 "서명 키 교체" 기능을 도입하여, 테넌트 내에서 새로운 OIDC 개인 키와 쿠키 키를 생성할 수 있도록 합니다.

1. Console > 테넌트 설정 > OIDC 설정으로 이동하세요. 여기서 OIDC 개인 키와 OIDC 쿠키 키를 모두 관리할 수 있습니다.

2. 서명 키를 교체하려면 "개인 키 교체" 또는 "쿠키 키 교체" 버튼을 클릭하세요. 개인 키를 교체할 때는 서명 알고리즘을 변경할 수도 있습니다.

3. 사용 중인 모든 서명 키가 나열된 테이블을 확인할 수 있습니다. OIDC 개인 키의 경우, 이전 키는 삭제할 수 있지만 현재 키나 다음 키는 삭제할 수 없습니다. OIDC 쿠키 키의 경우, 이전 키는 삭제할 수 있지만 현재 키는 삭제할 수 없습니다.

   상태	설명
   Next	이 상태는 단계적 OIDC 개인 키 교체를 위한 것입니다. 키가 생성되었지만, 유예 기간이 끝나고 키가 활성화될 때까지 Logto는 이 키로 새로운 JWT를 서명하지 않습니다.
   Current	이 키가 현재 Logto에서 새로 발급되는 JWT 또는 쿠키를 서명하는 데 사용되고 있음을 나타냅니다.
   Previous	이전에 사용되었으나 교체된 키를 의미합니다. 이 키로 서명된 기존 JWT 또는 쿠키는 만료되거나 키가 삭제될 때까지 유효합니다.

교체(로테이션)는 다음 세 가지 작업을 포함한다는 점을 기억하세요:

1. 새 서명 키 생성: OIDC 개인 키의 경우, Logto는 새 키를 먼저 "Next"로 준비할 수 있으므로, 애플리케이션과 API가 새 키가 서명에 사용되기 전에 /oidc/jwks 엔드포인트에서 공개 키를 갱신할 시간을 가질 수 있습니다.
2. 현재 키 교체: 교체가 활성화되면, "Next" 키가 "Current"가 되고, 기존 "Current" 키는 "Previous"가 됩니다. 이전 키로 서명된 토큰은 여전히 유효합니다.
3. 가장 오래된 이전 키 삭제: Logto는 최대 한 개의 "Previous" 개인 키만 유지합니다. 준비된 키가 현재 키가 될 때 이미 이전 개인 키가 존재한다면, 더 오래된 이전 키는 삭제됩니다.

Logto Cloud의 경우, OIDC 개인 키 교체는 4시간의 유예 기간 후에 적용됩니다. 이 기간 동안 새 키가 준비되어 JWKS를 통해 노출되며, Logto가 새로 발급되는 JWT를 해당 키로 서명하기 시작하기 전까지 유지됩니다. Console 테이블의 Effective at 열에서 준비된 "Next" 키가 "Current"가 되는 시점을 확인할 수 있습니다.

셀프 호스팅 OSS 배포의 경우, 기본 개인 키 교체 유예 기간은 0초로, 즉시 교체가 이루어집니다. 단계적 교체를 사용하려면 Logto 서비스에서 PRIVATE_KEY_ROTATION_GRACE_PERIOD 환경 변수를 설정하거나, Management API 엔드포인트 POST /api/configs/oidc/private-keys/rotate 호출 시 요청 본문에 명시적으로 rotationGracePeriod 값을 전달하세요.

경고:

대기 중인 교체가 적용되기 전에 반복적으로 서명 키를 교체하지 마세요. 의도적으로 준비된 "Next" 키를 교체하려는 경우가 아니라면 피해야 합니다.

유일한 "Previous" 키를 너무 일찍 삭제하면 해당 키로 서명된 기존 JWT 또는 쿠키가 무효화될 수 있습니다.

관련 리소스

JWT에서 EC 및 RSA 서명 알고리즘 소개