Magic Link autentizace

Magic Link poskytuje autentizaci bez hesla prostřednictvím e-mailu. Uživatelé kliknou na bezpečný, časově omezený odkaz a přihlásí se bez zadávání hesla.

Jak to funguje

┌──────────┐         ┌──────────┐         ┌──────────┐         ┌──────────┐
│ Uživatel │         │ Vaše App │         │ Klubero  │         │  E-mail  │
│          │         │          │         │   SSO    │         │  Server  │
└────┬─────┘         └────┬─────┘         └────┬─────┘         └────┬─────┘
     │                    │                    │                    │
     │ 1. Zadá email      │                    │                    │
     │ ──────────────────►│                    │                    │
     │                    │                    │                    │
     │                    │ 2. Požádá o magic  │                    │
     │                    │    link            │                    │
     │                    │ ──────────────────►│                    │
     │                    │                    │                    │
     │                    │                    │ 3. Odešle email    │
     │                    │                    │ ──────────────────►│
     │                    │                    │                    │
     │ 4. Obdrží email    │                    │                    │
     │ ◄───────────────────────────────────────────────────────────│
     │                    │                    │                    │
     │ 5. Klikne na link  │                    │                    │
     │ ────────────────────────────────────────►                    │
     │                    │                    │                    │
     │ 6. Přihlášen, redirect do aplikace      │                    │
     │ ◄───────────────────────────────────────│                    │

Krok 1: Požádání o Magic Link

Endpoint: POST /api/magiclink/send

curl -X POST https://your-sso-domain.com/api/magiclink/send \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "returnUrl": "/connect/authorize?client_id=my-app&redirect_uri=https://myapp.com/callback&response_type=code&scope=openid%20profile%20email&state=xyz"
  }'

Tělo požadavku:

Pole	Povinné	Popis
email	Ano	E-mailová adresa uživatele
returnUrl	Ne	OAuth autorizační URL pro pokračování po autentizaci

Odpověď:

{
  "success": true,
  "message": "If an account exists, a magic link has been sent."
}

Bezpečnostní poznámka

Odpověď je vždy úspěšná, aby se zabránilo útokům typu email enumeration. Uživatel obdrží e-mail pouze pokud jeho účet existuje.

Krok 2: Uživatel klikne na odkaz

E-mail obsahuje odkaz v tomto formátu:

https://your-sso-domain.com/Account/MagicLink?token=BASE64URL_TOKEN&ticket=ENCRYPTED_OAUTH_PARAMS

Krok 3: Dokončení autentizace

Když uživatel klikne na odkaz:

1. Token je validován (existuje, nevypršel, nebyl použit)
2. Uživatel je přihlášen pomocí cookie
3. Pokud jsou přítomny OAuth parametry: Redirect na /connect/authorize (pokračuje normální flow)
4. Pokud nejsou OAuth parametry: Redirect na uživatelský portál

Charakteristiky tokenu

Vlastnost	Hodnota
Formát	256-bitová náhodná hodnota, URL-safe Base64 kódování
Životnost	15 minut
Použití	Pouze jednorázové (spotřebován při kliknutí)
Uložení	SHA256 hash uložen v databázi

Validace tokenu (bez spotřebování)

Endpoint: GET /api/magiclink/validate

Ověření platnosti tokenu bez jeho spotřebování:

curl "https://your-sso-domain.com/api/magiclink/validate?token=TOKEN_VALUE"

Odpověď (platný):

{
  "valid": true,
  "email": "j***@example.com",
  "expiresAt": "2024-01-01T12:15:00Z"
}

Odpověď (neplatný):

{
  "valid": false,
  "error": "TokenExpired"
}

Zrušení všech čekajících odkazů

Endpoint: POST /api/magiclink/revoke-all

Zrušení všech čekajících magic linků pro autentizovaného uživatele:

curl -X POST https://your-sso-domain.com/api/magiclink/revoke-all \
  -H "Authorization: Bearer ACCESS_TOKEN"

Chybové kódy

Kód chyby	Popis	Akce uživatele
TokenNotFound	Token neexistuje	Požádejte o nový magic link
TokenExpired	Token vypršel (>15 minut)	Požádejte o nový magic link
TokenAlreadyUsed	Token byl již použit	Požádejte o nový magic link
UserNotFound	Uživatelský účet nenalezen	Kontaktujte podporu
UserNotActive	Uživatelský účet deaktivován	Kontaktujte podporu
UserLocked	Účet uzamčen (příliš mnoho neúspěšných pokusů)	Počkejte nebo kontaktujte podporu
InvalidTokenFormat	Token je poškozený	Požádejte o nový magic link

Integrace s OAuth flow

Pro integraci magic linku s vaším OAuth flow:

1. Sestavte autorizační URL (stejně jako u normálního flow)
2. Když uživatel požádá o magic link, zahrňte autorizační URL jako returnUrl
3. Po kliknutí na odkaz uživatel automaticky pokračuje v OAuth flow

Příklad:

# Sestavení autorizační URL
AUTH_URL="/connect/authorize?client_id=my-app&redirect_uri=https://myapp.com/callback&response_type=code&scope=openid%20profile%20email&state=xyz"

# Požádání o magic link s returnUrl
curl -X POST https://your-sso-domain.com/api/magiclink/send \
  -H "Content-Type: application/json" \
  -d "{
    \"email\": \"user@example.com\",
    \"returnUrl\": \"$AUTH_URL\"
  }"