매직 링크 인증
일회용 토큰을 사용하여 비밀번호 없는 로그인, 초대 전용 등록, 조직 멤버 초대를 위한 매직 링크 구현 방법을 배워보세요.
매직 링크란 무엇인가요?
매직 링크는 비밀번호 없는 인증 방법으로, 사용자가 이메일(또는 SMS)을 통해 일회용 로그인 URL을 받는 것을 의미합니다. 링크를 클릭하면 비밀번호 없이 로그인됩니다.
매직 링크의 주요 보안 기능은 다음과 같습니다:
- 단일 사용 토큰: 클릭 후 토큰은 재사용을 방지하기 위해 무효화됩니다.
- 링크 만료: 매직 링크는 보안을 강화하기 위해 짧은 만료 시간(예: 10분)을 가져야 합니다.
- 전송 제한: 특정 시간 내에 보낼 수 있는 매직 링크 수를 제한하여 남용을 방지합니다.
- 기기/브라우저 바인딩 (선택 사항): 가로채기를 방지하기 위해 링크의 사용을 원래 기기나 IP로 제한합니다.
매직 링크의 구성
매직 링크는 다음으로 구성됩니다:
- URL 경로: 앱의 랜딩 페이지로 향합니다.
- 일회용 토큰: 비밀번호 없는 인증을 위한 고유하고 일회성 소비 토큰입니다.
- 사용자 이메일: 토큰의 진위 여부와 사용자의 신원을 검증하는 데 사용됩니다.
- 추가 매개변수: 앱의 필요에 따라 다릅니다.
예를 들어, 매직 링크는 다음과 같이 보일 수 있습니다:
매직 링크를 생성하려면 일회용 토큰을 생성하고, 이를 사용자에게 안전하게 전송한 뒤 사용자가 링크를 클릭했을 때 이를 검증해야 합니다.
매직 링크의 워크플로우
- 사용자가 매직 링크 요청: 사용자가 앱에 이메일을 입력합니다.
- 일회용 토큰 생성: 서버가 토큰을 생성하고 이메일로 링크를 보냅니다.
- 사용자가 링크 클릭: 사용자가 이메일의 링크를 클릭합니다.
- 토큰 검증: 서버가 토큰이 유효한지 확인합니다.
- 사용자가 인증됨: 토큰이 유효하면 사용자는 로그인됩니다.
Logto와 함께 매직 링크를 구현하는 방법
1단계: 일회용 토큰 요청하기
Logto 관리 API를 사용하여 일회용 토큰을 생성합니다.
샘플 요청 본문 페이로드:
2단계: 매직 링크 구성하기
일회용 토큰을 받은 후, 귀하의 애플리케이션의 랜딩 페이지로 이동하도록 토큰과 사용자 이메일을 매개변수로 포함한 매직 링크를 작성하여 최종 사용자의 이메일 주소로 보낼 수 있습니다. 예: https://yourapp.com/landing-page
.
여기 매직 링크의 간단한 예시가 있습니다:
참고:
매직 링크의 매개변수 이름은 완전히 사용자 정의할 수 있습니다. 귀하의 애플리케이션 요구사항에 따라 추가 정보를 추가할 수 있으며 URL의 모든 매개변수를 인코딩할 수 있습니다.
3단계: Logto SDK를 통해 인증 흐름 트리거하기
최종 사용자가 매직 링크를 클릭하고 귀하의 애플리케이션으로 이동한 후 URL에서 token
과 email
매개변수를 추출하여 Logto SDK의 signIn()
함수를 호출하여 인증 흐름을 트리거할 수 있습니다.
자세한 사항은 Logto 문서 - 매직 링크 (일회용 토큰)를 참조하세요.
매직 링크 사용 사례
매직 링크는 첫 번째 인증 단계의 대체 기능이지만 다중 요소 인증 (MFA)을 우회할 수는 없습니다.
Logto에서는 일회용 토큰을 사용하여 매직 링크를 생성할 때 그 링크가 로그인이나 가입을 위한 것인지 명시할 필요가 없습니다. 우리는 이메일 등록 상태에 따라 자동으로 흐름을 결정합니다:
- 비등록 이메일: 매직 링크를 클릭하면 사용자는 이메일 입력 및 검증을 건너뛰고 계정 생성 흐름으로 리디렉션됩니다. 사용자는 비밀번호 설정, 프로필 세부정보 추가(예: 전체 이름), 또는 가입 설정에 기초한 MFA 설정으로 진행합니다.
- 등록된 이메일: 매직 링크를 클릭하면 첫 번째 단계 검증(예: "이메일 + 비밀번호" 또는 "이메일 + 인증 코드")을 건너뛰게 됩니다. 사용자는 바로 로그인되거나, 로그인 설정에 따른 MFA 완료가 필요합니다.
Logto는 매직 링크와 함께 다음 시나리오를 지원합니다:
- 초대 전용 등록: 내부 도구 또는 테스트 단계의 AI 제품의 경우, 공개 등록을 비활성화하고 특정 사용자에게 매직 링크를 통해 초대를 보낼 수 있습니다.
- 조직 멤버 초대: SaaS 제품의 경우, 조직의 새 멤버를 초대하는 매직 링크를 사용하여 회원 절차를 간소화합니다.
- 로그인 / 가입: 이메일을 통해 로그인 또는 가입을 위한 매직 링크를 보냅니다.
현재 미지원:
더욱 맞춤화가 필요하시면 알려주세요.
매직 링크를 통한 초대 전용 등록
새 제품(예: AI 도구)의 내부 테스트 또는 내부 도구의 경우 공개 등록을 비활성화하고 특정 사용자에게만 애플리케이션 접근을 허용하고자 할 수 있습니다. Logto를 활용하여 이를 구현하는 방법:
-
콘솔 > 로그인 경험 > 로그인 및 가입 > 고급 옵션으로 이동하여 "사용자 등록 활성화"를 꺼서 공개 등록을 닫습니다.
-
초대하고 싶은 사용자의 이메일 주소를 수집합니다(예: 웹사이트 또는 기존 사용자의 추천을 통해).
-
위에 설명된 대로 매직 초대 링크를 생성 및 전송합니다 (일회용 토큰 요청, 매직 링크 작성, Logto SDK를 통한 인증 트리거).
참고: 초대 링크의 만료 시간을 설정합니다. 링크가 최소 하루 동안 유효하도록 설정하는 것이 좋습니다. 일회용 토큰을 생성하기 위해 다음 요청 본문을 사용합니다:
-
사용자 이메일로 매직 링크를 전송합니다(예:
https://yourapp.com/landing-page?type=registrationInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]
). 이메일 템플릿을 다음과 같이 사용자 정의하세요:사용자가 "초대 수락"을 클릭하면, 공개 등록이 비활성화된 상태에서도 자동으로 서비스에 등록됩니다. 이를 "표적 사용자 초대"라고 합니다.
매직 링크를 통한 조직 멤버 초대
다중 테넌트 제품(예: Slack, GitHub, Vercel 같은 SaaS 앱)의 경우, 조직 멤버십을 쉽게 관리할 수 있도록 매끄러운 멤버 초대 프로세스를 제공합니다. 멤버 초대에서 높은 전환율을 위해 매직 링크를 사용하세요.
-
Logto Docs를 참조하여 조직 생성, 조직 역할 기반 액세스 제어 및 조직 관리를 구현하세요: Logto Organizations.
-
제품 내 "멤버 초대" 워크플로우를 설정합니다. 예:
-
조직 멤버 초대를 위한 이 안내서를 따릅니다. 참고: 멤버를 초대할 때 요청 페이로드에 다음이 포함되도록 합니다:
- **
context: jitOrganizationIds
**를 포함하여 사용자가 가입할 조직을 지정합니다. - 초대를 수락할 수 있는 충분한 시간을 제공하기 위해 더 긴
expiresIn
시간을 설정합니다 (예: 2일 또는 1주일).
요청 페이로드 예시:
- **
-
사용자의 이메일로 초대 링크를 보냅니다(예:
https://yourapp.com/landing-page?type=organizationMemberInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]
). 이메일 템플릿을 다음과 같이 사용자 정의하세요:사용자가 **"초대 수락"**을 클릭하면, 자동으로 로그인되거나 가입하여 조직에 자동으로 가입하게 됩니다.
계정 충돌 처리하기
기존 계정으로 이미 로그인된 사용자가 다른 매직 링크를 클릭하면 어떻게 되나요?
계정 충돌을 올바르게 처리하기 위해 다음을 확인하십시오:
- "로그인 프롬프트"에
login
추가를 피하세요: 로그인 프롬프트에서login
을 포함하지 마십시오. 설정이 잘못되면 Logto는 매직 링크 토큰과 연결된 계정으로 자동 로그인하여 계정 전환 프롬프트를 우회합니다. - 기존 토큰 보존:
signIn()
함수를 호출할 때clearTokens: false
매개변수를 지정하여 기존 토큰을 제거하지 않도록 합니다. 이 옵션을 사용할 경우 수동으로 토큰 제거를 로그인 콜백 페이지에서 수행하는 것을 확인하십시오.
적절한 설정 후 사용자 경험은 다음과 같습니다:
- 현재 계정을 위한 매직 링크: 사용자가 이미 로그인 중인 상태에서 동일한 계정에 대한 매직 링크를 클릭하면, Logto는 일회용 토큰을 확인하고 필요할 경우 사용자를 지정된 조직에 프로비저닝합니다.
- 다른 계정을 위한 매직 링크: 사용자가 로그인된 상태에서 다른 계정에 대한 매직 링크를 클릭하면, Logto는 사용자가 다음을 선택하도록 프롬프트를 표시합니다:
- 새 계정으로 계속함: Logto는 토큰 확인 후 새 계정으로 전환합니다.
- 현재 계정 유지: Logto는 토큰 확인을 건너뛰고 사용자를 현재 계정으로 반환합니다.
매직 링크 무효화 처리 오류 페이지 관리하기
사용자가 무효화된 매직 링크를 클릭하는 경우, 문제에 대해 명확히 설명하는 오류 페이지로 리디렉션됩니다. 가능한 오류 시나리오와 메시지는 다음과 같습니다:
이름 | 설명 |
---|---|
token_not_found | 주어진 이메일 및 토큰으로 활성화된 토큰을 찾을 수 없습니다. |
email_mismatch | 주어진 토 큰과 이메일이 일치하지 않습니다. |
token_expired | 토큰이 만료되었습니다. |
token_consumed | 토큰이 소비되었습니다. |
token_revoked | 토큰이 취소되었습니다. |
cannot_reactivate_token | 토큰을 다시 활성화할 수 없습니다. |
각 오류 페이지는 사용자가 무효화된 매직 링크 뒤에 있는 이유를 이해하고 다음 단계로 안내 받을 수 있도록 구체적인 메시지를 제공합니다. 예를 들어:
결론
Logto는 매직 링크를 통한 유연하고 비밀번호 없는 로그인 흐름을 통해 엔터프라이즈 수준의 보안을 제공합니다. 이는 조직에 사용자를 초대하거나, 사용자 계정을 손쉽게 생성하게 하거나, 번거로움 없는 인증을 제공하는 간단하지만 강력한 방법입니다. 그리고 Logto는 계정 충돌 및 만료된 토큰과 같은 복잡한 상황을 처리하기 때문에 사용자에게 매번 안전하고 불만 없는 과정을 제공합니다.
당신의 IAM을 탄탄한 인증으로 현대화할 준비가 되셨나요?