본문으로 건너뛰기

비밀번호 정책

Logto는 비밀번호가 생성되거나 업데이트되는 방식에 따라 비밀번호 정책을 다르게 적용합니다:

비밀번호 정책 설정하기​

신규 사용자 또는 비밀번호를 변경하는 사용자의 경우, 비밀번호 강도 요건을 적용하기 위해 비밀번호 정책을 설정할 수 있습니다. 콘솔 > 보안 > 비밀번호 정책에서 비밀번호 정책을 설정하세요.

  1. 최소 비밀번호 길이: 비밀번호에 필요한 최소 문자 수를 설정합니다. (NIST는 최소 8 문자를 권장합니다)
  2. 최소 요구 문자 유형 수: 비밀번호에 필요한 최소 문자 유형 수를 설정합니다. 사용 가능한 문자 유형은 다음과 같습니다:
    1. 대문자: (A-Z)
    2. 소문자: (a-z)
    3. 숫자: (0-9)
    4. 특수 문자: (!"#$%&'()\*+,-./:;<>=?@[]^\_`|{}~ )
  3. 유출 이력 검사: 이 설정을 활성화하면 데이터 유출에서 이미 노출된 비밀번호를 거부합니다. (Have I Been Pwned 기반)
  4. 반복 문자 검사: 이 설정을 활성화하면 반복되는 문자가 포함된 비밀번호를 거부합니다. (예: "11111111" 또는 "password123")
  5. 사용자 정보 포함 검사: 이 설정을 활성화하면 사용자 이름, 이메일 주소, 전화번호 등 사용자 정보가 포함된 비밀번호를 거부합니다.
  6. 사용자 지정 단어: 비밀번호에 포함되면 거부할 사용자 지정 단어 목록(대소문자 구분 없음)을 입력하세요.

비밀번호 만료​

비밀번호 만료는 사용자가 설정된 일수 후에 비밀번호를 재설정하도록 요구합니다. 또한 비밀번호가 유출된 것이 확실할 때 특정 사용자의 비밀번호를 수동으로 만료시킬 수도 있습니다.

이 정책은 사용자가 비밀번호 로그인에서 올바른 비밀번호를 입력한 후에만 확인됩니다. 인증 코드, 소셜 로그인, SSO, 패스키로 로그인하는 사용자는 영향을 받지 않습니다.

비밀번호 만료 활성화하기​

콘솔 > 보안 > 비밀번호 정책로 이동하여 비밀번호 만료 카드에서 다음을 진행하세요:

  1. 비밀번호 만료 활성화를 켭니다.
  2. **비밀번호 유효 기간(일)**을 1~9999일 사이로 설정합니다.
  3. 변경 사항을 저장합니다.

토글은 로그인 경험에 비밀번호 찾기 방법(이메일 또는 전화번호)과 정상 동작하는 커넥터가 최소 1개 이상 있을 때만 활성화됩니다. 사용자는 만료된 비밀번호를 해당 플로우를 통해서만 재설정할 수 있기 때문입니다. 같은 이유로, 정책이 활성화된 동안에는 비밀번호 찾기를 지원하는 마지막 이메일 또는 SMS 커넥터를 삭제할 수 없습니다. 회원가입 시 이메일 주소나 전화번호를 필수로 받지 않는 경우, 일부 사용자는 재설정 코드를 받을 방법이 없을 수 있으니 회원가입 시 하나를 수집하는 것을 고려하세요.

Logto는 사용자의 비밀번호가 마지막으로 설정되거나 변경된 시점을 기록합니다. 비밀번호가 유효 기간만큼 오래되면, 사용자는 비밀번호를 재설정할 때까지 다음 비밀번호 로그인이 차단됩니다. 비밀번호 변경 기록이 없는 사용자는 정책을 활성화한 시점부터 기간을 계산하므로, 정책을 켠다고 해서 모든 사용자의 비밀번호가 즉시 만료되는 것은 아닙니다. 정책을 껐다가 다시 켜면 이 시작 시점이 초기화됩니다.

사용자가 새 비밀번호를 설정하면(비밀번호 찾기, Account API, Management API를 통해) 비밀번호 연령이 다시 시작되고 수동 만료도 해제됩니다.

사용자의 비밀번호를 수동으로 만료시키기​

비밀번호 만료 정책이 활성화된 경우, 특정 사용자가 다음 로그인 시 비밀번호를 재설정하도록 강제할 수 있습니다:

  • 콘솔: 콘솔 > 사용자 관리로 이동하여 사용자 상세 페이지를 열고, 비밀번호 옆의 만료 버튼을 클릭한 후 동작을 확인합니다. 사용자가 비밀번호를 가지고 있을 때만 버튼이 활성화됩니다.

  • Management API: 다음과 같은 body로 PATCH /api/users/{userId}/password/expiration를 호출하세요:

    {
      "isExpired": true
    }

정책이 활성화되어 있지 않으면 API는 400과 함께 에러 코드 sign_in_experiences.password_expiration_not_enabled를 반환하며, 콘솔의 만료 버튼도 비활성화됩니다.

일반적인 예시는 비밀번호가 유출된 것이 확인된 경우입니다. 만료시키면 사용자가 새 비밀번호를 설정하고 다시 로그인하기 전에 이메일 주소나 전화번호로 전송된 인증 코드로 본인임을 증명해야 합니다. 모든 사용자에게 정기적 비밀번호 변경을 강제하지 않고 수동 만료만 원한다면, 정책을 3650일과 같이 긴 유효 기간으로 활성화하세요.

비밀번호를 만료시켜도 기존 세션에서 로그아웃되지는 않습니다. 즉시 접근을 차단하려면 사용자의 활성 세션과 인가된 서드파티 앱도 함께 해지하세요.

최종 사용자가 보는 화면​

사용자가 만료된 비밀번호로 로그인하면, 올바른 비밀번호 입력 후 "비밀번호가 만료되어 로그인 전에 재설정해야 합니다."라는 메시지가 포함된 모달이 표시됩니다. 비밀번호 재설정을 클릭하면 식별자가 미리 입력된 상태로 비밀번호 찾기 플로우로 이동합니다. 이메일 또는 전화번호로 전송된 코드로 인증하고 새 비밀번호를 설정하면 다시 로그인할 수 있습니다.

Experience API로 직접 로그인 UI를 구축하는 경우, 비밀번호 검증 요청이 에러 코드 password.expired(HTTP 422)로 실패합니다. 이 에러를 처리하여 사용자를 비밀번호 재설정 플로우로 안내하세요.

비밀번호 준수 검사​

Logto에서 비밀번호 정책을 업데이트한 후에도 기존 사용자는 현재 비밀번호로 계속 로그인할 수 있습니다. 새로 생성된 계정만 업데이트된 정책을 따라야 합니다.

더 강력한 보안을 위해 POST /api/sign-in-exp/default/check-password API를 사용하여 사용자의 비밀번호가 기본 로그인 경험에 정의된 현재 정책을 충족하는지 확인할 수 있습니다. 충족하지 않는 경우, Account API를 사용한 커스텀 플로우로 비밀번호 업데이트를 유도할 수 있습니다.

사용자 관리 회원가입 및 로그인 Account API로 계정 설정 비밀번호 정책 설계하기