본문으로 건너뛰기

서명 키

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 쿠키 키를 모두 관리할 수 있습니다.

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

  3. 사용 중인 모든 서명 키가 나열된 테이블을 확인할 수 있습니다. 참고: 이전 키는 삭제할 수 있지만, 현재 사용 중인 키는 삭제할 수 없습니다.

    상태설명
    현재이 키가 현재 애플리케이션 및 API에서 활성 상태로 사용되고 있음을 나타냅니다.
    이전이전에 사용되었으나 교체된 키를 의미합니다. 이 서명 키로 서명된 기존 토큰은 여전히 유효합니다.

회전(교체)에는 다음 세 가지 작업이 포함됨을 기억하세요:

  1. 새 서명 키 생성: 모든 애플리케이션 및 API가 새 서명 키를 사용해야 합니다.
  2. 현재 키 교체: 기존 키는 교체 후 "이전"으로 지정되며, 새로 생성되는 애플리케이션 및 API에서는 사용되지 않습니다. 하지만 이 키로 서명된 토큰은 여전히 유효합니다.
  3. 이전 키 삭제: "이전"으로 표시된 키는 폐기되어 테이블에서 제거됩니다.
경고:

서명 키를 연속적으로(두 번 이상) 교체하지 마세요. 이는 발급된 모든 토큰을 무효화할 수 있습니다.

  • OSS 사용자의 경우, 서명 키를 교체한 후 Logto 인스턴스를 재시작해야 새 서명 키가 적용됩니다.
  • Cloud 사용자의 경우, 서명 키 교체 후 즉시 새 키가 적용되지만, 연속적으로 여러 번 교체하지 않도록 주의하세요.

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