Configurazione di Microsoft Entra

Frontdoor fa accedere gli utenti con Microsoft Entra ID tramite il flusso OAuth 2.0 Authorization Code con PKCE, usando MSAL. Ti serve una registrazione di app nel tuo tenant.

Passo 1: creare una registrazione di app

1. Nel portale di Azure, vai a Microsoft Entra ID > App registrations > New registration.
2. Name: Frontdoor, o qualsiasi nome tu preferisca.
3. Supported account types:
   • Single tenant: solo gli utenti della tua organizzazione (il caso più comune).
   • Multitenant: gli utenti di qualsiasi organizzazione Microsoft Entra.
4. Redirect URI: seleziona Web e inserisci:
   • produzione: https://frontdoor.contoso.com/api/auth/microsoft/callback
   • sviluppo locale: http://localhost:3001/api/auth/microsoft/callback
5. Seleziona Register.

Passo 2: annotare gli identificativi

Dalla pagina Overview della nuova registrazione di app, copia:

• Application (client) ID → AZURE_CLIENT_ID
• Directory (tenant) ID → AZURE_TENANT_ID

Passo 3: creare un client secret

1. Vai a Certificates & secrets > Client secrets > New client secret.
2. Aggiungi una descrizione (per esempio "Frontdoor produzione") e scegli una scadenza.
3. Copia subito il Value, perché non viene più mostrato → AZURE_CLIENT_SECRET.

Ruota il secret periodicamente e non inserirlo mai nel repository.

Passo 4: configurare i permessi API

Permessi per l'accesso

1. Vai a API permissions > Add a permission > Microsoft Graph > Delegated permissions.
2. Aggiungi:
   • openid: far accedere gli utenti
   • profile: leggere il nome visualizzato dell'utente
   • email: leggere l'indirizzo email dell'utente
   • User.Read: leggere il profilo di base dell'utente che ha effettuato l'accesso
3. Seleziona Grant admin consent, oppure chiedi a un amministratore del tenant di farlo.

Permessi per la sincronizzazione dei gruppi e il pre-onboarding

Per usare la sincronizzazione dei gruppi Entra (ENTRA_GROUP_SYNC=true) o l'azione Sincronizza gruppi, aggiungi anche questi permessi Microsoft Graph di tipo application e concedi il consenso amministratore:

Permesso	Perché
User.Read.All	Leggere le appartenenze ai gruppi di ogni utente (/users/{id}/transitiveMemberOf)
GroupMember.Read.All	Leggere i membri dei gruppi importati (/groups/{id}/transitiveMembers)
Group.Read.All	Facoltativo: letture più ampie degli oggetti gruppo (descrizione, visibilità e simili)

Sia il flusso di accesso sia Sincronizza gruppi chiamano Microsoft Graph con un token solo applicativo. Senza questi permessi applicativi le funzioni sui gruppi restituiscono errori 403, anche per un amministratore globale.

Pre-onboarding utenti cerca nel tenant con lo stesso token solo applicativo e richiede User.Read.All con consenso amministratore, anche quando ENTRA_GROUP_SYNC è disattivato.

Foto del profilo

Per permettere all'utility di preriscaldamento e all'aggiornamento degli avatar in Personalizza di scaricare le foto di Microsoft 365 degli utenti esistenti, aggiungi il permesso applicativo ProfilePhoto.Read.All con consenso amministratore.

Passo 5: impostare le variabili d'ambiente

AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
AZURE_REDIRECT_URI=https://frontdoor.contoso.com/api/auth/microsoft/callback

Vedi il Riferimento della configurazione per le altre variabili.

Come funziona la sincronizzazione dei gruppi

Con ENTRA_GROUP_SYNC=true, a ogni accesso Frontdoor:

1. recupera le appartenenze ai gruppi dell'utente tramite /users/{id}/transitiveMemberOf
2. aggiorna il catalogo dei gruppi dell'intero tenant tramite /groups, al massimo una volta ogni ENTRA_TENANT_REFRESH_MINUTES
3. salva i gruppi in una cache di rilevamento

Gli amministratori importano poi solo i gruppi che vogliono usare. Poiché Graph viene chiamato in modalità solo applicativa, il consenso dell'utente all'accesso resta limitato all'insieme minimo openid, profile, email e User.Read. Sincronizza gruppi usa lo stesso percorso solo applicativo per aggiornare in un colpo solo il catalogo dei gruppi e le appartenenze di tutti gli utenti.

La prima volta che attivi ENTRA_GROUP_SYNC=true, aggiungi i permessi applicativi, concedi il consenso, poi provoca un nuovo accesso o esegui Sincronizza gruppi per popolare la cache.

Rilevamento e importazione sono separati. Se elimini da Frontdoor dei gruppi Entra importati, non vengono ricreati al prossimo accesso: devono essere rilevati di nuovo da un accesso o da una sincronizzazione, e poi importati di nuovo. Vedi Gruppi e accessi.

Anche gli utenti in pre-onboarding rientrano nella sincronizzazione, quindi i loro gruppi Entra possono comparire prima che accedano.