Autenticazione delle app satellite

Un'app satellite è un'app del catalogo di Frontdoor che si affida a Frontdoor per l'autenticazione. Gli amministratori ne scelgono la modalità di connessione nell'editor delle app (vedi App e modalità di connessione); questa pagina spiega cosa deve fare l'app satellite.

Scegliere uno schema

Scegli lo schema più restrittivo adatto alla tua installazione.

Schema	Quando usarlo	Cosa serve all'app satellite
Cookie condiviso (mode=shared-cookie)	L'app satellite è ospitata su un sottodominio di BASE_DOMAIN.	Leggere il cookie httpOnly frontdoor_token e verificarlo in locale con il JWT_SECRET condiviso.
Redirect con secret condiviso (mode=redirect)	L'app satellite è su un dominio diverso, gestita dallo stesso team.	Ricevere il token di breve durata tramite query string GET o form POST, e verificarlo in locale con il JWT_SECRET condiviso.
Redirect con introspezione (mode=redirect)	L'app satellite è su un dominio diverso e non deve possedere il secret di Frontdoor: una terza parte, un ambiente meno affidabile, o per limitare i danni di una fuga di dati.	Ricevere il token di breve durata, poi inviarlo in POST a /api/auth/verify-sso-token con il proprio slug come expected_aud. Nessun secret condiviso.

Entrambi gli schemi con redirect usano la stessa modalità dell'app (mode=redirect); cambia solo il modo in cui l'app satellite verifica il token.

Condividere il secret

Un'app che possiede JWT_SECRET può verificare i token di Frontdoor, ma potrebbe anche firmarli, compresi i token di sessione. Condividi il secret solo con app di totale fiducia e usa l'introspezione per le altre.

Frontdoor accetta come sessioni solo token firmati con HS256, con il suo emittente (JWT_ISSUER, predefinito frontdoor) e senza audience. Un'app satellite che verifica i token in locale deve aspettarsi lo stesso emittente.

Verificare un token con l'introspezione

POST /api/auth/verify-sso-token è un endpoint di introspezione da server a server, ispirato alla RFC 7662 e limitato a questo flusso. Con una sola chiamata Frontdoor controlla firma, scadenza, emittente, audience, che l'utente sia attivo e che l'app sia attiva.

Non ti serve una chiave API: l'autorizzazione è il possesso di un token valido per l'expected_aud richiesto.

curl -sX POST https://frontdoor.contoso.com/api/auth/verify-sso-token \
  -H 'Content-Type: application/json' \
  -d '{"token":"<jwt>","expected_aud":"<your-app-slug>"}'

Un token valido restituisce 200:

{
  "valid": true,
  "user": { "id": "...", "email": "...", "name": "...", "role": "user" },
  "aud": "<your-app-slug>",
  "exp": 1745740300
}

Errori

Stato	error	Significato
400	bad_request	token o expected_aud manca o non è valido (formato dello slug).
401	invalid_token	Firma errata o token scaduto (volutamente indistinguibili).
401	invalid_issuer	Il token non è stato emesso da questo Frontdoor.
401	user_not_found_or_inactive	Il sub del token non corrisponde a un utente attivo.
403	audience_mismatch	Il token è stato riutilizzato su un'altra app. Frontdoor registra il chiamante con un avviso.
403	app_inactive	expected_aud corrisponde a un'app che è stata disattivata.
429	too_many_requests	Limite di frequenza superato (120 richieste al minuto per IP).

Limitare la sessione locale

Usa exp per limitare la sessione dell'app satellite, così non sopravvive mai al token di Frontdoor:

local session lifetime = min(default_session_ttl, exp - now)

Controllare la sessione da un'altra origine

Una pagina che deve solo sapere se l'utente ha effettuato l'accesso, senza essere un'app del catalogo, può chiamare /api/auth/me con credentials: 'include' una volta che la sua origine è in CORS_ALLOWED_ORIGINS. Vedi Controllo della sessione da altre origini.

Impersonation e app satellite

Quando un amministratore agisce come un utente in Frontdoor, la sessione vive in un cookie separato, valido solo per l'host (frontdoor_impersonation) e usato solo nelle richieste che arrivano da Frontdoor stesso. Il cookie condiviso frontdoor_token non cambia mai, quindi le app satellite con cookie condiviso e i controlli della sessione da altre origini continuano a vedere l'amministratore, mai l'utente impersonato. Durante l'impersonation le app non si possono aprire e non viene emesso alcun token SSO.