Eseguire la migrazione da Amazon Cognito a Microsoft Entra per ID esterno

Se attualmente si usa Amazon Cognito con l'accesso social e si prevede di eseguire la migrazione del carico di lavoro a Azure, questa guida consente di comprendere i mapping delle funzionalità, il processo di migrazione e le procedure consigliate.

Questa guida è destinata a sviluppatori e architetti che eseguono la migrazione di un'applicazione rivolta agli utenti da Amazon Cognito a Microsoft Entra per ID esterno. Illustra la migrazione end-to-end di accesso tramite social, rilascio di token, autorizzazione basata sui gruppi, claim personalizzati e i corrispettivi dei trigger Lambda.

Cosa riuscirai a realizzare

Imparerai a:

• Migra la tua base utenti di Cognito in un tenant External ID, compresi gli utenti collegati ai provider di identità social.
• Mantieni i tuoi provider di identità social esistenti, ad esempio Facebook o Google, e configurali come provider di identità in External ID.
• Spostare l'applicazione da AWS Amplify Auth (o Cognito SDK) a Libreria di Autenticazione Microsoft (MSAL).
• Sostituire i token di accesso rilasciati da Cognito con token rilasciati con ID esterno nelle chiamate API. L'ID esterno utilizza il flusso del codice di autorizzazione OAuth 2.0 con Proof Key for Code Exchange (PKCE).
• Preserva la logica di autorizzazione mappando le claim di Cognito agli equivalenti di External ID, inclusa la distinzione tra gli attributi di archiviazione nella directory e le claim emesse nel token.
• Verificare che gli utenti possano accedere con i propri account di social networking e che l'API funzioni ancora per conto dell'utente.

La guida adotta un approccio in cinque fasi:

Scenario di esempio: app consumer con accesso tramite social network e accesso alle API

Lo scenario seguente è la base per i passaggi di migrazione descritti in questa guida. Se lo scenario è diverso, l'approccio generale è lo stesso, ma alcuni dettagli potrebbero differire.

Si dispone di un'applicazione Web rivolta agli utenti (ad esempio, una piattaforma di contenuti o un marketplace). Il front-end usa Amplify Auth per reindirizzare gli utenti all'interfaccia utente ospitata da Cognito per l'accesso. Gli utenti accedono con Google o Facebook. Cognito crea un utente nel pool di utenti al primo accesso. Prima dell'emissione dei token, viene eseguito un trigger lambda per aggiungere un'attestazione personalizzata basata sul profilo dell'utente o su una ricerca in un altro sistema. Cognito rilascia quindi il token di accesso e il token ID e il front-end li archivia. Quando l'app Web chiama l'API back-end, invia il token di accesso Cognito nella richiesta. L'API convalida il token e controlla l'attestazione cognito:groups per determinare le operazioni che l'utente può eseguire. Lo stato finale per questo scenario usa l'accesso gestito da External ID con gli stessi provider di identità social a monte.

L'obiettivo è spostare l'intero stack di identità dell'app in ID esterno senza richiedere agli utenti di creare nuovi account o reimpostare l'accesso social.

Panoramica dell'architettura

Il diagramma seguente confronta il flusso di autenticazione prima e dopo la migrazione. La chiave cambia: Amplify Auth diventa MSAL, Cognito diventa accesso gestito con ID esterno e l'API passa dalla convalida cognito:groups alla lettura roles (o groups per l'autorizzazione basata su gruppo).

Prerequisites

• Un tenant External ID attivo.
• Accesso all'ambiente Cognito di origine tramite la console AWS, l'interfaccia della riga di comando di AWS o un SDK AWS. L'utente o il ruolo IAM richiede i AmazonCognitoReadOnly criteri gestiti (o autorizzazioni di lettura equivalenti per il pool di utenti, i client, i provider di identità, gli utenti e i gruppi).
• Credenziali del client OAuth (ID client e segreto) per ogni provider di identità social che si intende migrare (Facebook e Google).
• Ambiente di sviluppo o test in cui è possibile convalidare la migrazione prima dell'ambiente di produzione. Usare un tenant ID esterno separato per il test anziché eseguire il traffico di test attraverso il tenant di produzione. Questo approccio evita di inquinare la directory di produzione con gli utenti di test e consente di eliminare e ricreare il tenant di test senza rischi.
• Un account con i ruoli Amministratore applicazione e Amministratore utenti assegnati nel tenant ID esterno.
• Una sottoscrizione di Azure.
• Autorizzazioni di Microsoft API Graph per il provisioning in blocco degli utenti. L'applicazione di migrazione richiede almeno l'autorizzazione dell'applicazione User.ReadWrite.All con il consenso dell'amministratore.

Passaggio 1: Pianificare

In questo passaggio si compila l'inventario di origine della verità per la migrazione. La valutazione deve acquisire la configurazione corrente di Cognito, le dipendenze dell'applicazione da token e attestazioni Cognito e i sistemi operativi che devono continuare a funzionare dopo la rimozione di Cognito.

Valutare l'ambiente Amazon Cognito

Prima di iniziare la migrazione, esaminare e documentare tutti gli elementi attualmente configurati in Cognito. È anche necessario comprendere come l'applicazione e l'API back-end usano attualmente Cognito. È necessario un inventario completo per pianificare la migrazione.

Esaminare il pool di utenti Cognito, il codice dell'applicazione e la logica di autorizzazione api e registrare le informazioni seguenti:

• Impostazioni del pool di utenti: ID pool di utenti, area geografica, alias di accesso (posta elettronica, telefono, nome utente), attributi obbligatori, criteri password, configurazione dell'autenticazione a più fattori (MFA).
• Client app: ID client, segreti client (se presenti), flussi OAuth consentiti, URL di callback, URL di disconnesso, ambiti OAuth consentiti, provider di identità assegnati al client.
• Provider di identità: Quali provider di social networking o enterprise sono configurati, l'ID client OAuth e il segreto usati per ognuno e il mapping degli attributi.
• Attributi personalizzati: Elenco di attributi definiti nel pool di custom:* utenti e delle app che le usano.
• Gruppi: Tutti i gruppi Cognito, i relativi valori di precedenza e qualsiasi ruolo IAM associato.
• Trigger Lambda: Quali trigger sono configurati (pre-registrazione, pre-autenticazione, post-conferma, pre-generazione del token, messaggio personalizzato, post-autenticazione, migrazione utente, definizione/creazione/verifica della challenge di autenticazione) e che cosa fa ciascuno. Trigger del mittente email personalizzato e del mittente SMS personalizzato. (Entrambi richiedono AWS Key Management Service (KMS) per la crittografia.) Se utilizzi questi trigger per inviare messaggi tramite un provider esterno, ad esempio SendGrid o Twilio, prendi nota del provider, della chiave KMS e dei modelli di messaggio.
• Impostazioni della UI ospitata: Personalizzazioni del branding, override CSS, logo.
• Conteggio utenti e tasso di crescita: Quanti utenti sono attivi, utenti attivi mensili, tariffe di accesso di picco.
• Consumer di eventi downstream: Avvisi CloudWatch sugli eventi Cognito, regole eventbridge attivate da Cognito, analisi di terze parti che ricevono dati webhook e qualsiasi notifica semplice (SNS)/Simple Queue Service (SQS) associata al pool di utenti. Tutti questi si interrompono in silenzio quando Cognito viene rimosso.

Usare l'interfaccia della riga di comando di AWS per estrarre la maggior parte di queste informazioni. Per esempio:

aws cognito-idp describe-user-pool --user-pool-id <pool-id>
aws cognito-idp list-user-pool-clients --user-pool-id <pool-id>
aws cognito-idp list-identity-providers --user-pool-id <pool-id>
aws cognito-idp list-groups --user-pool-id <pool-id>
aws cognito-idp list-users --user-pool-id <pool-id>

Questi comandi restituiscono JSON che descrive la configurazione del pool, le app registrate, i provider federati, le definizioni di gruppo e i record utente. Usa questo output come inventario di partenza per pianificare il tenant External ID.

Scopri cosa gestisce Cognito oltre all'accesso social

Anche se ogni utente accede tramite Facebook o Google, Cognito gestisce ancora un sacco di lavoro:

• Cognito funge da server di autorizzazione. Rilascia i token che la tua app e l'API utilizzano.
• Cognito archivia il profilo dell'utente, gli attributi personalizzati e le appartenenze ai gruppi.
• Cognito esegue i trigger Lambda, compresa tutta la logica che utilizzi per arricchire i token.
• Cognito controlla la durata dei token, il contenuto dell'attestazione e la forma dell'attestazione cognito:groups .
• Cognito firma i token. L'API considera attendibile l'endpoint JWKS Cognito.

Il passaggio all'ID esterno comporta lo spostamento di tutte le funzionalità attualmente fornite da Cognito per gli utenti, non solo lo scambio dei provider di identità social. Pianificare la migrazione in modo che includa l'accesso, gli utenti, i gruppi, le attestazioni personalizzate e la logica Lambda.

Mapping diretto delle funzionalità

Questa tabella esegue il mapping dei concetti principali di Cognito ai relativi equivalenti in Microsoft Entra ID.

Incongruenze delle capacità e strategie alternative

Alcune funzionalità di Cognito non hanno un equivalente diretto in ID esterno. Le sezioni seguenti spiegano cosa fa ciascuna funzionalità, perché non esiste una corrispondenza uno a uno e cosa usare in alternativa.

Pool di identità

I pool di identità di Cognito non hanno un Azure equivalente diretto. I pool di identità vengono usati per scambiare un token federato per le credenziali del servizio token di sicurezza di AWS (STS) di breve durata associate a un ruolo IAM. È necessario prendere decisioni di progettazione per i mapping seguenti:

• Accesso da servizio a servizio: Usare le identità gestite anziché le credenziali temporanee.
• Accesso alle risorse per utente: Usare le assegnazioni di controllo degli accessi in base al ruolo di Azure (RBAC) o i token di firma di accesso condiviso con ambito limitato all'identità dell'utente.
• Accesso diretto alle risorse dalle app client: Per l'accesso diretto da client a risorsa, acquisire un token di accesso per la risorsa di destinazione direttamente dal client. Usare il flusso On-Behalf-Of (OBO) solo in un'API confidenziale di livello intermedio che scambia il token di accesso dell'utente per ottenere l'accesso a un'API a valle.
• Se l'applicazione usa pool di identità, pianificare questa sostituzione come flusso di lavoro separato. Richiede modifiche all'architettura oltre la migrazione del pool di utenti Cognito-to-External ID descritta in questa guida.

Provider di identità sociale

In Cognito si registra il provider di identità social (IdP) una volta a livello del pool di utenti e lo si abilita per ogni client dell'app. In External ID, il provider si registra una sola volta a livello di tenant e si aggiunge a ogni flusso utente che deve accettarlo. È possibile riutilizzare le credenziali del client Facebook o Google OAuth esistenti, ma è necessario aggiungere il nuovo URI di reindirizzamento ID esterno all'elenco consentito nelle console per sviluppatori google e Facebook.

Interfaccia utente ospitata e accesso gestito

In Cognito l'interfaccia utente ospitata può includere personalizzazioni come logo, colori e personalizzazioni CSS a livello di pool di utenti, ma gli URL di callback, i flussi OAuth, gli ambiti e i provider di identità abilitati vengono configurati per ogni client dell'app. In ID esterno questo scenario usa l'accesso gestito per mantenere il modello di migrazione simile: l'app reindirizza gli utenti a un'esperienza di accesso Microsoft ospitata e si configurano opzioni di accesso come Google e Facebook nella registrazione dell'app. L'accesso gestito supporta la personalizzazione aziendale, ma non è una destinazione di migrazione uno-a-uno per ogni personalizzazione CSS dell'interfaccia utente ospitata da Cognito. Se l'interfaccia utente ospitata attuale dipende da CSS personalizzato o da un controllo a livello di pixel, hai due opzioni:

• Adattare l'esperienza alle funzionalità di personalizzazione dell'accesso gestito.
• Ospita l'esperienza di accesso nella tua applicazione e usa MSAL per avviare il flusso di autorizzazione di External ID.

Gruppi e autorizzazione

I gruppi di Cognito hanno un aspetto simile a gruppi di ID esterni, ma per l'autorizzazione a livello di app, in ID esterno vengono in genere mappati in modo più pulito ai ruoli dell'app. I ruoli dell'app mantengono il modello di autorizzazione all'interno della registrazione dell'app, vengono inclusi nella rivendicazione roles, evitano l'eccessiva proliferazione dei gruppi a livello di tenant e non incappano nel limite di eccedenza dei gruppi (trattato nel passaggio 3). Se l'app dispone di un set ridotto e stabile di autorizzazioni (amministratore, editor, visualizzatore), usare i ruoli dell'app come modello di autorizzazione principale. È comunque possibile assegnare gruppi di sicurezza ai ruoli dell'app nell'applicazione aziendale per semplificare l'amministrazione. Usare l'autorizzazione diretta basata su gruppi solo quando l'app deve ragionare sull'appartenenza a gruppi. Per impostazione predefinita, le attestazioni dell'ID esterno groups contengono gli ID oggetto del gruppo, non etichette aziendali trasferibili come admin o viewer. Per altre informazioni, vedere Attestazioni del token di accesso, Attestazioni facoltative e Configurazione delle attestazioni di gruppo.

Attributi personalizzati

Ogni attributo custom:* in Cognito viene mappato a un attributo utente cliente di ID esterno, che viene archiviato come attributo di estensione della directory nell'oggetto utente. In Microsoft Graph questi attributi usano il modello extension_<appid>_<name>di denominazione di archiviazione . Il nome del claim del token può essere diverso. Ad esempio, un'estensione di autenticazione personalizzata potrebbe leggere extension_<appid>_tier dalla directory e generare un'attestazione di token descrittiva per l'azienda denominata tier. Configurare l'attributo di estensione nella registrazione dell'app e includerlo nei token rilasciati usando un flusso utente o un'estensione di autenticazione personalizzata. Un'estensione di autenticazione personalizzata consente di estendere i flussi di autenticazione con la propria logica di business in punti specifici all'interno del flusso di autenticazione. Quando viene attivato, effettua una chiamata HTTP a un endpoint API REST in cui si definisce un'azione del flusso di lavoro. Non presupporre che il payload della richiesta TokenIssuanceStart contenga tutti i ruoli, i gruppi o gli attributi personalizzati necessari per l'arricchimento. Se l'arricchimento dei claim dipende da questi valori, progetta una mappatura deterministica che non richieda una ricerca esterna oppure una query a Microsoft Graph che usi l'identità gestita o le credenziali client confidenziali con autorizzazioni applicative con privilegi minimi. Per informazioni dettagliate, vedere Attributi utente CON ID esterno, Definire attributi personalizzati e Aggiungere attributi utente personalizzati ai token.

Durata dei token

Cognito consente di impostare il token di accesso, il token ID e la durata dei token di aggiornamento per ogni client dell'app. L'ID esterno supporta periodi di validità configurabili per i token di accesso e i token ID tramite criteri relativi alla durata. Le durate dei token di aggiornamento non sono configurabili in ID esterno. Se i client dell'app Cognito hanno una durata breve del token di aggiornamento come misura di sicurezza deliberata, usate invece la frequenza di accesso condizionale. Per i token di accesso e ID, ove possibile, fate corrispondere i valori di Amazon Cognito per ciascun client dell'app per ridurre al minimo le variazioni di comportamento al momento della migrazione.

Mappatura degli eventi: trigger Lambda per le estensioni di autenticazione personalizzate

I trigger lambda di Cognito diventano estensioni di autenticazione personalizzate con ID esterno, che chiamano una funzione Azure (o qualsiasi endpoint HTTPS) durante il flusso di autenticazione. Non tutti i trigger hanno un equivalente uno-a-uno. I mapping in questa sezione descrivono i modelli di prodotto supportati.

Endpoint del flusso del codice di autorizzazione ID esterno

L'ID esterno espone gli endpoint OIDC e OAuth 2.0 in un dominio dedicato, seguendo questo modello:

• Autorizzazione: https://<tenant-name>.ciamlogin.com/<tenant-id>/oauth2/v2.0/authorize
• Token: https://<tenant-name>.ciamlogin.com/<tenant-id>/oauth2/v2.0/token

È possibile trovare gli URL esatti nel Interfaccia di amministrazione di Microsoft Entra in Registrazioni app>Endpoints o nel documento di individuazione di OpenID Connect all'indirizzo https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration. Per i tenant esterni, il valore dell'emittente restituito dai metadati usa l'ID tenant nell'host e nel percorso: https://<tenant-id>.ciamlogin.com/<tenant-id>/v2.0. Convalidare i token rispetto al valore dell'emittente nel documento dei metadati, e non a un valore creato manualmente.

Cognito e EXTERNAL ID supportano lo stesso flusso.

Cosa cambia:

• Endpoint di autorizzazione: Reindirizza da https://<cognito-domain>/oauth2/authorize all'endpoint di autorizzazione di External ID del tenant.
• Endpoint del token: Passa dall'endpoint https://<cognito-domain>/oauth2/token del token ID esterno.
• Ambiti: Gli ambiti di Cognito sono formattati come <resource-server-identifier>/<scope>, mentre gli ambiti di External ID sono formattati come <application-id-uri>/<scope>, dove l'URI ID dell'applicazione è in genere api://<api-client-id>. In External ID si definisce l'API con Esporre un'API, si dichiarano gli ambiti e si concedono all'app client come autorizzazioni API. Il client richiede questi ambiti quando chiama l'API.
• Destinatario: Convalida il valore del destinatario in fase di esecuzione che compare nel token di accesso. Nei token di accesso di Microsoft Identity Platform v2.0, aud è in genere l'ID client (GUID) dell'applicazione API. Nei token v1.0 può essere l'URI ID applicazione. I token di accesso Cognito identificano il client dell'app con client_id. Un'attestazione aud viene visualizzata solo quando l'app richiede un'associazione di risorse Cognito per un'API. Il validatore JWT della tua API deve aggiornare il valore previsto di aud, il valore previsto di iss e l'URI JWKS in base alla versione del token e al comportamento del provider. Per altre informazioni, vedere Attestazioni del token di accesso, convalida delle attestazioni e attestazioni del token di accesso Cognito.

La documentazione Microsoft Identity Platform sul flusso del codice di autorizzazione è il riferimento per il formato esatto di richiesta e risposta.

Scegli un approccio di transizione

Scegli tra i due approcci di cutover seguenti:

• Graduale. Un segmento utente alla volta.
• Big bang. Un'unica finestra di cutover, tutti insieme.

Scegli un passaggio graduale, se possibile. Per un'app rivolta ai clienti con accesso social, un cutover graduale causa l'interruzione minima e ti dà il tempo di trovare eventuali problemi prima che influiscano su ogni utente. Un passaggio big bang è indicato solo quando:

• La migrazione può essere gestita end-to-end in un ambiente non di produzione con elevata attendibilità.
• Il pool di utenti Cognito legacy può rimanere disponibile in sola lettura per un periodo di fallback definito.
• Si dispone di una finestra di manutenzione breve e ben definita. La maggior parte delle app rivolte agli utenti non è disponibile.
• Il numero di utenti è abbastanza ridotto da rendere un rollback poco costoso.

Ecco l'aspetto di un cutover in più fasi per questo scenario:

1. Eseguire la pre-migrazione degli utenti all'ID esterno. Usare Microsoft Graph per creare in blocco account utente in External ID. Per gli utenti collegati tramite social network, impostare la identities proprietà su ogni oggetto utente in modo che l'ID esterno conosca l'account Google o Facebook mappato all'utente. Questa fase avviene prima di qualsiasi passaggio in produzione.

2. Indirizzare una piccola percentuale degli accessi a External ID. L'app sceglie quale provider di identità deve avviare il flusso OAuth in base a un flag di funzionalità o a un'impostazione di configurazione. Iniziare con 5% di traffico. Gli utenti che accedono tramite l'ID esterno eseguono l'autenticazione tramite il nuovo tenant e poiché l'identità federata è stata pre-collegata al passaggio 1, corrispondono all'account utente esistente senza che venga richiesto di eseguire di nuovo la registrazione.

3. Monitorare ed espandere. Controllare le percentuali di esito positivo dell'accesso, la convalida dei token e i risultati dell'autorizzazione API per il gruppo ID esterno. Se tutto sembra buono, aumentare la percentuale. Se si verificano problemi, ripristinare il flag di funzionalità e correggerli prima di procedere con l'espansione. Per le app mobili con SDK integrati, il rollback richiede una nuova versione dell'app tramite il processo di revisione dello store anziché una modifica di configurazione, quindi pianifica i rilasci graduali su mobile in modo prudente.

4. Recupera gli utenti inattivi. Per gli utenti che non hanno eseguito l'accesso durante la finestra di migrazione (account inattivi o abbandonati), sono disponibili due opzioni:

   • Premigrarli al passaggio 1 in modo che siano pronti nel caso in cui tornino.
   • Lascia gli utenti in Cognito ed esegui la migrazione su richiesta se accedono dopo il passaggio. Usare un modello JIT leggero in cui l'app rileva un utente solo Cognito ed esegue la migrazione all'ID esterno al primo accesso.

   La maggior parte delle organizzazioni effettua una migrazione preventiva di tutti gli utenti per evitare la complessità dell'identificazione JIT.

Un cutover big bang è indicato solo quando si dispone di una finestra di manutenzione breve e ben definita, di un numero limitato di utenti oppure non è possibile gestire due provider di identità in parallelo.

Considerazioni aggiuntive

Usare queste considerazioni sulla pianificazione per decidere se l'approccio alla migrazione è fattibile prima di iniziare a configurare il tenant di destinazione. Consentono di stimare l'impatto operativo, definire i criteri di idoneità e mantenere pratico il rollback durante ogni ciclo di migrazione.

Licensing

L'ID esterno include un determinato numero di utenti attivi mensili (MAU) senza costi. Dopo tale limite, la tariffazione avviene per autenticazione. I criteri di accesso condizionale richiedono almeno una licenza Microsoft Entra ID P1. Microsoft Entra ID Protection (accesso basato sul rischio, rilevamento delle credenziali compromesse) richiede licenze Microsoft Entra ID P2. Esaminate la pagina dei prezzi di External ID e la guida alle licenze di Microsoft Entra ID per stimare i costi per il numero di utenti.

Criteri di esito positivo

Impostare criteri di esito positivo chiari:

• Tasso di accesso riuscito entro il X% rispetto al valore di riferimento pre-migrazione
• Latenza mediana entro Y ms dalla baseline di Cognito
• Zero regressioni negli esiti dell'autorizzazione API

Utilizza i criteri di successo nella fase 4, in cui valuti se approvare una migrazione riuscita.

Piano di ripristino

1. Mantenere Cognito completamente operativo fino a quando non si completa la convalida per ogni ondata di migrazione.
2. Mantenere attivi gli URI di reindirizzamento Cognito e External ID nelle console del provider di social networking durante la transizione.
3. Se un'ondata non supera la convalida, ripristinare la configurazione dell'app in modo che punti di nuovo a Cognito. Aggiornare nuovamente l'autorità MSAL al dominio Cognito o ridistribuire la versione di Amplify Auth.
4. Assicurarsi che ogni onda abbia un checkpoint go/no-go basato sull'elenco di controllo di convalida nel passaggio 4: Valutare.
5. Rimuovere solo gli URI di reindirizzamento Cognito e disabilitare il pool di utenti dopo che l'ultima ondata supera la convalida e si osserva zero traffico per Cognito per almeno 72 ore.
6. Se gli utenti hanno effettuato l'iscrizione o hanno modificato il profilo in ID esterno prima del rollback, tali modifiche esistono solo nella directory ID esterno. Documentare un processo di riconciliazione: esportare eventuali modifiche a nuovi utenti o profili con ID esterno, quindi decidere se ricrearli in Cognito o portarli avanti nel tentativo di migrazione successivo.

Manuale operativo di migrazione

Creare un runbook di migrazione per il team prima di avviare le modifiche di produzione. Il runbook è il documento operativo dettagliato seguito dal team durante la fase di esecuzione (passaggio 3). Definiscilo durante la pianificazione in modo che il team concordi sulla sequenza, sulle responsabilità, sui checkpoint di comunicazione e sui criteri decisionali prima che inizi il cutover. I seguenti passaggi numerati delineano la struttura del runbook. Adattarli agli strumenti e ai canali di comunicazione del team.

Una ondata di migrazione è un gruppo definito di utenti che viene spostato da Cognito a External ID contemporaneamente. È possibile definire una coorte in base alla percentuale di traffico, alla versione dell'app, all'area geografica o al segmento di clienti. Eseguire lo stesso processo ordinato per ogni onda e espandersi solo all'onda successiva dopo che il processo corrente supera la convalida.

Il runbook deve coprire i passaggi seguenti per ogni ondata di migrazione:

1. Confermare i criteri go/no-go: la convalida del pilota è stata completata con esito positivo, il monitoraggio è attivo, il rollback è pronto, gli script di migrazione sono stati testati e i team di supporto conoscono il perimetro dell'ondata.
2. Distribuite la versione finale del codice dell'applicazione preparata, se non è già stata distribuita protetta da un feature flag o da un interruttore di configurazione.
3. Applicare solo le modifiche di configurazione dell'ID esterno finali già convalidate nel progetto pilota, ad esempio l'abilitazione di un'estensione di autenticazione personalizzata preparata o la conferma delle assegnazioni di ruolo dell'app.
4. Eseguire gli script preparati per la migrazione degli utenti relativi alla wave e riconciliare i risultati prodotti.
5. Validare gli utenti migrati prima di instradare il traffico di produzione per l'ondata.
6. Avvia la finestra di cutover per la wave e instrada gli utenti selezionati a External ID.
7. Eseguire entrambi i sistemi in parallelo e monitorare l'accesso, il rilascio di token, l'autorizzazione API, l'integrità dell'estensione personalizzata e i segnali di supporto.
8. Ripristinare l'ondata se vengono superate le soglie di errore, oppure passare all'ondata successiva quando la convalida ha esito positivo.

Pianificare la transizione del metodo MFA

Le impostazioni MFA di Cognito non vengono trasferite automaticamente. I tenant cliente di External ID supportano il passcode monouso tramite e-mail e l'autenticazione basata su SMS (come componente aggiuntivo) come metodi di secondo fattore di autenticazione. Passkey (FIDO2) non è disponibile come secondo fattore per gli utenti del provider di identità esterno. La registrazione dell'app Authenticator da Cognito non è una destinazione di migrazione supportata.

Per gli utenti che utilizzavano l’MFA dell’app Cognito Authenticator, pianificare una transizione a un metodo External ID supportato prima dell’ondata di migrazione. Comunicare la modifica prima del cutover in modo che gli utenti comprendano quale secondo fattore verrà richiesto di usare.

Gli utenti MFA hanno un'esperienza di migrazione diversa rispetto agli utenti non MFA. Valutare la possibilità di eseguire prima la migrazione di utenti non MFA per convalidare il flusso principale, quindi eseguire la migrazione degli utenti MFA come onda separata e fornire comunicazioni mirate.

Scegliere una strategia di migrazione delle password

Per gli utenti con account Cognito locali (posta elettronica e password), Cognito non esporta gli hash delle password. Scegliere una delle tre opzioni e comunicarla agli utenti prima del cutover:

• Reimpostazione forzata della password (scelta consigliata): Eseguire la migrazione dell'account utente senza password, contrassegnare l'account per la reimpostazione della password al primo accesso e consentire all'utente di impostare una nuova password usando il flusso self-service di ID esterno. Questa opzione è il percorso più semplice e affidabile. Allinea l'utente ai criteri per le password di External ID fin dal primo accesso. Fornire comunicazioni proattive tramite posta elettronica alcuni giorni prima del cutover in modo che gli utenti non siano sorpresi.
• Migrazione delle password JIT (Just-In-Time): Un'estensione di autenticazione personalizzata convalida la password rispetto all'API di AdminInitiateAuth Cognito al primo accesso, quindi scrive la password in ID esterno. L'utente non nota la migrazione. Questa opzione richiede maggiore implementazione e impegno operativo. Richiede a Cognito di rimanere raggiungibile durante la finestra JIT e deve essere monitorato come flusso di lavoro di implementazione e convalida.
• Transizione a senza password: Passare gli account locali alla posta elettronica con passcode monouso e rimuovere completamente la password.

Usare la reimpostazione della password forzata come impostazione predefinita. Usare JIT solo se l'azienda non richiede alcuna reimpostazione della password. Una migrazione completa con una reimpostazione della password pulita è più prevedibile e ha esito negativo in meno posizioni rispetto a un flusso JIT che dipende dal sistema legacy che rimane online.

Passaggio 2: Preparare

Ora disponi di un inventario documentato del tuo ambiente Cognito, di una strategia di cutover e di un runbook per la migrazione. Successivamente, creare l'ambiente di destinazione e convalidarlo dall'inizio alla fine in un progetto pilota.

In questo passaggio preparare l'ambiente di destinazione e gli asset di migrazione prima di spostare gli utenti o cambiare il traffico di produzione. Completare prima queste attività in un ambiente pilota, quindi ripetere la configurazione convalidata nell'ambiente di produzione.

Preparare un ambiente pilota

Prima di configurare qualsiasi elemento nel tenant External ID di produzione, configura un tenant pilota separato in cui puoi convalidare la migrazione dall'inizio alla fine con un piccolo gruppo di utenti di prova. Configurare innanzitutto il progetto pilota, incluse le registrazioni app, l'autenticazione gestita, i provider di identità social, le autorizzazioni API, i ruoli dell'app, il monitoraggio, la configurazione del codice e gli script di migrazione. Dopo che il progetto pilota ha superato la convalida, ripetere la stessa configurazione nel tenant di produzione.

Definire i criteri di accettazione in anticipo:

• Gli utenti possono accedere usando i provider di identità social configurati, ad esempio Facebook o Google.
• I nuovi accessi creano un utente nella directory.
• Gli utenti già esistenti migrati da Cognito accedono senza che venga loro richiesto di registrarsi di nuovo.
• L'API riceve un token di accesso CON ID esterno e autorizza l'utente in base ai ruoli dell'app o alle attestazioni di gruppo se è stata configurata in modo esplicito l'autorizzazione basata su gruppo. Se si utilizzano i ruoli dell'app, verificare che siano definiti e assegnati nella registrazione dell'app API o nel relativo service principal, in modo che siano presenti nel token di accesso dell'API.
• Il monitoraggio acquisisce errori di accesso, errori di autorizzazione API e errori di estensione personalizzati durante la convalida pilota.
• Gli script di migrazione possono esportare un set di utenti pilota da Cognito e creare o aggiornare gli utenti corrispondenti in ID esterno senza modifiche manuali.

Se uno di questi criteri non riesce nel progetto pilota, correggere la configurazione, il codice o gli script di migrazione nell'ambiente pilota prima di applicare la configurazione corretta all'ambiente di produzione.

Confermare l'accesso con privilegi per la preparazione

Prima di configurare il tenant pilota o di produzione, verificare che gli operatori che eseguono questa fase dispongano dei privilegi necessari per completare ogni attività. La creazione di registrazioni di app, l'esposizione di ambiti API, la configurazione dell'accesso gestito, l'assegnazione dei ruoli dell'app, la creazione di utenti tramite Microsoft Graph e la configurazione delle esportazioni di monitoraggio possono richiedere ruoli amministrativi diversi o autorizzazioni di Microsoft Graph. Pianificare almeno i ruoli Amministratore applicazioni e Amministratore utenti nel tenant ID esterno e confermare eventuali privilegi aggiuntivi necessari per Log Analytics, Monitoraggio di Azure, Funzioni di Azure, identità gestite o segreti CI/CD prima dell'avvio del progetto pilota.

Creare e configurare il tenant esterno

Se non si ha già un tenant di ID esterno pilota, crearne uno nel Interfaccia di amministrazione di Microsoft Entra prima di creare o modificare il tenant di produzione. Per mantenere coerente la residenza dei dati, selezionare la posizione geografica corrispondente alla posizione del pool di utenti Cognito. L'ID esterno archivia i dati del profilo utente, le credenziali e i metadati di autenticazione nell'area geografica selezionata quando si crea il tenant. Questa selezione è permanente e non può essere modificata dopo la creazione. Per i carichi di lavoro che presentano rigidi requisiti di residenza dei dati, consultare Dove Microsoft Entra ID archivia i dati delle identità prima di procedere e usare il componente aggiuntivo Go-Local.

Se si ha già un tenant ID esterno per un'altra app, è possibile riutilizzarlo. Ogni tenant supporta più registrazioni di app, flussi utente e configurazioni IdP di social networking.

Registrare le applicazioni e configurare i flussi utente

Per ciascun client app di Cognito, creare una registrazione dell’applicazione corrispondente in External ID:

1. Registrare l'app client (l'app Web a cui gli utenti accedono). Impostare l'URI di reindirizzamento sul callback usato dall'app dopo la migrazione. Abilitare il flusso del codice di autorizzazione con PKCE.
2. Registrare l'API back-end come registrazione di app separata. In Esporre un'API impostare l'URI ID applicazione e dichiarare gli ambiti necessari (l'equivalente degli ambiti del server di risorse Cognito).
3. Nella registrazione dell'app client aggiungere gli ambiti API in Autorizzazioni API.
4. Se l'API usa i ruoli dell'app per l'autorizzazione, definisci i ruoli nella registrazione dell'app dell'API back-end, quindi assegna utenti o gruppi di sicurezza a tali ruoli nell'applicazione aziendale dell'API. I ruoli definiti solo nell'app client non vengono visualizzati nel token di accesso all'API.
5. Creare un flusso utente (registrazione e accesso) in External ID. Configurare i provider di identità, gli attributi da raccogliere durante l'iscrizione e i metodi di autenticazione.
6. Associare l'app client al flusso utente e verificare che l'URI di reindirizzamento, l'URI di reindirizzamento post-disconnessione, gli ambiti e le autorizzazioni API corrispondano alla configurazione dell'app pilota.

Pianificare la migrazione dall'interfaccia utente ospitata all'accesso gestito

Se l'interfaccia utente ospitata di Cognito usa un branding personalizzato, documenta ciò che gli utenti vedono attualmente prima di configurare l'accesso gestito. Acquisisci loghi, colori, testo, uso di un dominio personalizzato, comportamento relativo alla lingua, schermate di accesso e registrazione, punti di accesso alla reimpostazione della password e qualsiasi comportamento personalizzato che dipende dal CSS.

In External ID, configurare prima l'esperienza di accesso gestita più simile nel tenant pilota. Verifica se il branding aziendale soddisfa i requisiti in materia di esperienza utente. In caso contrario, non rimandare la decisione al giorno del passaggio in produzione. Decidete durante la preparazione se accettare le differenze nell’accesso gestito, aggiornare le comunicazioni agli utenti oppure spostare all’interno dell’applicazione l’esperienza di accesso visibile agli utenti, mentre MSAL gestisce il flusso di autorizzazione basato su standard con External ID.

Configurare i provider di identità social

Aggiungi al tenant External ID gli stessi provider di identità social upstream che usi attualmente, ad esempio Facebook o Google. La migrazione modifica il broker e l'autorità emittente di token da Cognito a ID esterno. Non sostituisce gli account del provider di social networking upstream.

Prima di modificare la configurazione della console per sviluppatori del provider social, conferma nell'inventario di valutazione gli attuali URL di callback e di disconnessione di Cognito. È possibile riutilizzare le credenziali client OAuth di Google e Facebook già configurate per Cognito. Passare a Google Cloud Console e al portale Meta for Developers e aggiungere gli URI di reindirizzamento ID esterno all'elenco autorizzato accanto agli URI di reindirizzamento Cognito. Copiare l'URI di reindirizzamento esatto dal Interfaccia di amministrazione di Microsoft Entra per ogni provider anziché crearlo manualmente. Il formato varia in base al provider, ad esempio /federation/oauth2 per OIDC personalizzato o a un percorso specifico del provider per Google e Facebook. Non rimuovere ancora gli URI di reindirizzamento Cognito. Entrambi i set devono essere attivi durante la transizione.

Quindi, nell'interfaccia di amministrazione di ID esterno aggiungere Google e Facebook come provider di identità, incollare l'ID client OAuth e il segreto e aggiungerli come opzioni di accesso per l'accesso gestito.

I provider OIDC personalizzati seguono il flusso di federazione OIDC personalizzato. Avrai bisogno dell'endpoint di individuazione noto del provider, dell'ID client e del segreto client. A differenza dei provider non personalizzati, la mappatura delle attestazioni (sub, email, name e così via) deve essere configurata esplicitamente in modo che corrisponda a quanto presente in Cognito.

Eseguire la migrazione di domini personalizzati (se applicabile)

Se l'ambiente Cognito usa un dominio personalizzato (ad esempio, auth.example.com), pianificare la migrazione DNS. Non è possibile indirizzare contemporaneamente lo stesso dominio sia a Cognito sia a External ID. Ecco alcune opzioni:

• Usare un sottodominio diverso per l'ID esterno durante il funzionamento in parallelo. Ad esempio, usa login.example.com per External ID lasciando auth.example.com puntato su Cognito. Dopo il passaggio, puoi facoltativamente passare il dominio originale a External ID.
• Per usare un dominio personalizzato con External ID, è necessario usare Frontdoor di Azure come proxy inverso davanti al tenant External ID. Seguire il processo documentato in Usare un dominio URL personalizzato, che include la creazione di un'istanza di Frontdoor di Azure, la configurazione di regole di routing personalizzate e l'aggiunta del dominio personalizzato con un record CNAME (Canonical Name). Impostare la durata (TTL) del DNS su un valore basso (ad esempio, 300 secondi) prima del cutover in modo che l'opzione venga applicata rapidamente.

Verificare l'idoneità pilota prima della configurazione di produzione

Prima di ripetere la configurazione nell'ambiente di produzione, verificare che l'ambiente pilota dall'inizio di questo passaggio superi i criteri di accettazione. Se i criteri hanno esito negativo, correggere la configurazione, il codice, il monitoraggio o gli script di migrazione nel progetto pilota prima di applicare l'installazione all'ambiente di produzione.

Configurare il monitoraggio

Impostare il monitoraggio prima della convalida pilota e prima del passaggio in produzione. Il monitoraggio fa parte della preparazione della migrazione, non un'attività di completamento. Raggiungi o supera la visibilità che avevi in Cognito riesaminando la baseline di monitoraggio documentata nel Passaggio 1: Pianificazione (metriche Cognito CloudWatch per le percentuali di successo dell'accesso, la latenza di emissione dei token, l'esecuzione dei trigger Lambda e le percentuali di errore). Replicare le stesse metriche in Azure.

• Log di accesso: I log di accesso con ID esterno mostrano ogni tentativo di autenticazione. Filtrare in base all'applicazione e al motivo dell'errore per rilevare i problemi di configurazione. Ciò sostituisce le metriche di accesso di Cognito CloudWatch.
• Monitoraggio di Azure: esportare i log di accesso e di controllo in un'area di lavoro Log Analytics. Impostare avvisi relativi ai picchi di frequenza degli errori e ai timeout di estensione personalizzati. Configurare le stesse soglie di avviso presenti in Cognito in modo da intercettare immediatamente le regressioni.
• Metriche di estensione personalizzate: Le estensioni di autenticazione personalizzate hanno un timeout predefinito di 1 secondo, configurabile per un massimo di 2 secondi. Gli avvii a freddo in Funzioni di Azure spesso superano questo limite. I dati di latenza dettagliati si trovano a livello di calcolo e l'ID esterno registra solo che la chiamata all'estensione non è riuscita. Impostare un avviso sul calcolo dell'estensione per qualsiasi latenza P99 che si avvicina alla soglia di timeout. Confronta questo con le metriche CloudWatch del trigger Lambda. Quando un'estensione personalizzata va in timeout o restituisce un errore, External ID procede senza i claim dell'estensione. Decidi in anticipo se i claim mancanti devono bloccare l'accesso (fail-closed) oppure consentirlo con funzionalità ridotte (fail-open) e implementa questa logica nel middleware della tua API.
• Dashboard attività utente: L'ID esterno include dashboard predefiniti per l'iscrizione, gli accessi e l'utilizzo di MFA. Usa queste dashboard per verificare che il comportamento degli utenti sia in linea con i valori di riferimento pre-migrazione.

Creare e testare script di migrazione

Creare gli script di migrazione o i runbook durante la fase di preparazione. Gli script devono leggere gli utenti da Cognito, trasformare i dati nella forma di destinazione ID esterno e creare o aggiornare gli utenti tramite Microsoft Graph. Testare gli script nel tenant pilota con un piccolo set di utenti prima di eseguirli nell'ambiente di produzione.

La fase di esportazione dello script deve usare le API ListUsers e AdminGetUser, gestire la paginazione e acquisire i campi necessari per gli oggetti utente External ID di destinazione:

• Nome utente o posta elettronica
• Flag verificati tramite posta elettronica e verificati tramite telefono
• Dettagli dell'identità federata (fornitore, ID esterno del soggetto) per ogni account social collegato per l'accesso
• Attributi personalizzati
• Appartenenze a gruppi da AdminListGroupsForUser
• Configurazione MFA, se applicabile

Cognito non espone hash delle password. Per gli utenti che usano solo le funzionalità social, questa soluzione va bene perché non c'è nulla da migrare. Per gli utenti con account locale, prevedere una reimpostazione forzata della password o la migrazione JIT della password.

La fase di importazione deve creare utenti tramite l'endpoint Microsoft Graph/users. Per gli utenti collegati tramite social network, lo script deve aggiungere ogni identità federata nell'oggetto utente. Quando l'utente accede successivamente tramite un account Facebook o Google, l'ID esterno corrisponde a issuer e issuerAssignedId riutilizza l'account creato invece di crearne uno nuovo. La raccolta popolata identities deve esistere prima del primo accesso.

Ecco un esempio di chiamata a Microsoft API Graph per un utente collegato a Google:

POST /users
{
  "displayName": "Jane Doe",
  "accountEnabled": true,
  "userPrincipalName": "janedoe_google.com#EXT#@<tenant>.onmicrosoft.com",
  "identities": [
    {
      "signInType": "federated",
      "issuer": "google.com",
      "issuerAssignedId": "110169484474386276334"
    }
  ]
}

Se issuer o issuerAssignedId è errato, External ID considera il successivo accesso social come quello di un nuovo utente e crea un account duplicato. Recupera l'ID soggetto del provider dall'attributo JSON identities dell'oggetto utente Cognito (restituito da AdminGetUser).

Mappare i gruppi Cognito principalmente ai ruoli dell’app quando rappresentano le autorizzazioni dell’app. Se è necessaria l'autorizzazione diretta basata su gruppi, associala ai gruppi External ID e documenta che i valori emessi di groups sono, per impostazione predefinita, ID oggetto del gruppo. Applicare lo stesso mapping alle appartenenze o alle assegnazioni di ruolo di ogni utente.

Usare lo schema di proprietà dell'estensione di migrazione per contrassegnare quali utenti sono migrati e quali non lo sono. Questo flag è utile per tenere traccia dello stato della migrazione e per identificare gli utenti durante un cutover graduale, indipendentemente dal fatto che eseguino l'accesso con provider di social networking o account locali.

Base utenti di grandi dimensioni

Se si esegue la migrazione di un numero elevato di utenti, la limitazione della frequenza imposta da Microsoft Graph farà sì che questo passaggio richieda molto tempo. Usare Microsoft Graph batch per ridurre il numero di richieste e implementare la logica di back-off che rispetta l'intestazione Retry-After restituita nelle risposte 429/503 per evitare di raggiungere ripetutamente i limiti di limitazione.

Scrivi identities e attributi personalizzati nella chiamata iniziale POST anziché nelle chiamate successive PATCH.

Per un'implementazione di riferimento che include elaborazione in batch, nuovi tentativi e logica di limitazione della frequenza, vedi B2C-to-External-ID migration tool su GitHub. Adattare i modelli per l'origine Cognito.

Questi script verranno eseguiti nel passaggio 3.

Preparare la migrazione della logica personalizzata

Ricompilare e testare ogni sostituzione del trigger Lambda prima della finestra di migrazione. Per lo scenario di accesso tramite social, lo schema più comune è Pre token generation >OnTokenIssuanceStart. Se la funzione Lambda aggiunge un claim personalizzato basato sugli attributi dell'utente o su una ricerca nel back-end, ricrea tale logica come una funzione di Azure o un altro endpoint HTTPS che restituisca il formato di risposta previsto di External ID. Validare l'estensione nel tenant pilota, inclusi il comportamento in caso di timeout, il rollback, i requisiti relativi alla chiave di firma e gli allarmi di monitoraggio.

Per i trigger che non hanno un equivalente diretto tra gli eventi di External ID, come post confirmation o post authentication, va preparato il flusso di lavoro sostitutivo prima del passaggio. Ad esempio, utilizzare le notifiche di modifica di Microsoft Graph, Logic Apps, i registri di accesso o Monitoraggio di Azure, a seconda dei requisiti aziendali.

Per un esempio completo di implementazione di OnTokenIssuanceStart, consulta Introduzione alle estensioni di autenticazione personalizzate.

Preparazione della convalida dei token, della mappatura delle dichiarazioni e delle chiavi di identità

Completate la mappatura di token e claim prima del giorno di migrazione. Aggiornare le impostazioni di convalida dell'API back-end per l'autorità emittente di ID esterno, l'endpoint dei metadati JWKS, il gruppo di destinatari previsto e la versione del token accettata. Aggiorna il codice di autorizzazione per usare il modello di attestazioni di destinazione, ad esempio roles per i ruoli dell'app oppure groups solo quando usi deliberatamente attestazioni dirette dei gruppi.

Utilizza la tabella seguente per mappare i claim di Cognito ai rispettivi equivalenti negli ID esterni. Questa tabella approfondisce la mappatura delle capacità nel passaggio 1, fornendo i nomi esatti delle attestazioni che il codice deve gestire.

Se il database o i sistemi downstream archiviano il valore Cognito sub come identificativo utente, prepara la migrazione dei dati o la strategia di ricerca prima del cutover. Dopo la migrazione, usare l'ID oid esterno come identificatore di oggetto utente stabile. Verificare che i controlli di autorizzazione, i controlli di proprietà, i log di controllo e gli strumenti di supporto possano risolvere correttamente gli utenti migrati prima del primo ciclo di produzione.

Se si utilizza l'autorizzazione basata sui gruppi, preparare la strategia per il superamento del limite dei gruppi prima del passaggio. Cognito incorpora ogni gruppo a cui appartiene l'utente direttamente nell'attestazione cognito:groups (fino a 100 gruppi per utente). Microsoft Entra ID funziona in modo diverso. Per impostazione predefinita, groups contiene gli ID oggetto del gruppo, non i nomi intuitivi dei gruppi. Se l'utente è membro di più di 200 gruppi, Microsoft Entra ID non emette il claim groups nei token JWT. Genera invece un indicatore di eccedenza, come descritto nel riferimento alle attestazioni del token di accesso:

"_claim_names": { "groups": "src1" },
"_claim_sources": {
  "src1": {
    "endpoint": "https://graph.microsoft.com/v1.0/users/{id}/getMemberObjects"
  }
}

Quando l'API trova _claim_names con una voce groups, chiama l'endpoint getMemberObjects con un corpo della richiesta POST di {"securityEnabledOnly": false} per ottenere l'elenco effettivo dei gruppi. Per i token SAML, il limite di eccedenza è 150. I token di flusso impliciti si comportano in modo diverso: l'ID esterno genera hasgroups: true (un valore booleano) anziché il _claim_names/_claim_sources modello e l'app deve chiamare Microsoft Graph direttamente senza hint endpoint dal token. Il limite di eccedenza per i token di flusso impliciti è cinque.

Se gli utenti appartengono in genere a un numero ridotto di gruppi, questa distinzione non si applica. Se si dispone di utenti in un numero elevato di gruppi, gestirlo in uno dei modi seguenti:

• Configurare le attestazioni di gruppo in modo da includere solo i gruppi assegnati all'applicazione, riducendo così le dimensioni dell'attestazione.
• Usare i ruoli dell'app anziché i gruppi. I ruoli dell'app non sono soggetti al limite di eccedenza e sono il modello consigliato per l'autorizzazione a livello di app.
• Gestire l'attestazione di eccedenza nell'API chiamando Microsoft Graph quando viene visualizzato _claim_names (o hasgroups per i token di flusso impliciti).

Per la maggior parte delle migrazioni da Cognito, il passaggio ai ruoli dell'app è l'approccio più pulito. Usare i gruppi di sicurezza assegnati ai ruoli dell'app se è necessaria l'amministrazione basata su gruppi mantenendo valori stabili definiti dall'app nell'attestazione roles .

Altre attestazioni da verificare. Il set predefinito di attestazioni in un token di ID esterno è più ridotto di quanto alcuni team si aspettino. Se l'API legge un'attestazione che non è nel set predefinito (ad esempio, email, family name, ), given_nameaggiungerla come attestazione facoltativa nella registrazione dell'app in modo che sia inclusa nel token.

Preparare le modifiche al codice dell'applicazione

Preparare le modifiche dell'applicazione prima di eseguire la migrazione o cambiare il traffico. Nel ramo pilota o nell'ambiente, aggiornare la configurazione di autenticazione del front-end per usare MSAL con l'autorità External ID, l'ID client, l'URI di reindirizzamento e gli ambiti dell'API. Aggiornare le impostazioni di convalida dell'API back-end per l'autorità emittente di ID esterno, i metadati JWKS e i destinatari previsti. Aggiorna il codice di autorizzazione per leggere le attestazioni di destinazione, ad esempio roles per i ruoli dell'applicazione o groups se usi intenzionalmente le attestazioni di gruppo.

Se si utilizza una migrazione graduale (vedi Scegliere un approccio di cutover), preparare il flag di funzionalità o l'interruttore di configurazione usato per selezionare Cognito o External ID per un gruppo di utenti. Se l'API deve accettare entrambe le autorità emittenti di token durante la transizione, preparare e testare la convalida del token specifica dell'autorità emittente prima della prima fase. Mantenere pronte queste modifiche al codice per la distribuzione nel passaggio 3.

Per le app per dispositivi mobili, preparare le librerie MSAL specifiche della piattaforma:

Ios: Usare MSAL per iOS. I token vengono memorizzati nella cache nel Keychain iOS. Registrare un URI di reindirizzamento nel formato msauth.<bundle-id>://auth. Se si usa Microsoft Authenticator come broker, aggiungere l'URI di reindirizzamento del broker.

Android: Usare MSAL per Android. I token vengono memorizzati nella cache in EncryptedSharedPreferences. Registra un URI di reindirizzamento insieme all'hash della firma dell'app. L'app Authenticator funge da intermediario per l'accesso single sign-on (SSO) tra le app.

Preparazione della convalida del token con doppia esecuzione

Durante la migrazione, l'API potrebbe ricevere token di accesso sia da Cognito che da ID esterno. Configurare la convalida del token per autorità emittente. Per ogni emittente, convalida la firma usando i metadati corretti o l'endpoint JWKS e verifica l'emittente e il pubblico previsti. Non ritenere sufficiente, ai fini della validazione, il solo inserimento del soggetto emittente in un elenco di elementi consentiti.

ASP.NET: usare schemi di connessione JWT separati o uno schema di criteri, in modo che ogni autorità emittente abbia le proprie impostazioni di autorità, metadati, chiavi di firma e convalida. Se si utilizza Microsoft.Identity.Web, configura ogni schema esplicitamente per l'origine del token di cui si fida.

Node.js: Utilizzare express-jwt o jose con una selezione della chiave basata sull'emittente, in modo che l'emittente del token determini quale endpoint JWKS viene usato per la verifica della firma. Verifica anche il valore previsto aud per ogni origine del token.

Durante la doppia esecuzione, aggiornare i criteri CORS (Cross-Origin Resource Sharing) dell'API solo se l'origine dell'applicazione Web che chiama l'API cambia. CORS si applica alle richieste del browser dall'origine dell'app Web all'API. Il dominio dell'interfaccia utente ospitata da Cognito e il dominio di accesso di External ID normalmente non sono le origini che effettuano chiamate alla tua API.

Se l'applicazione usa AWS API Gateway con un autorizzatore Cognito, il Azure equivalente dipende dall'architettura:

• Con Gestione API di Azure, configura il criterio validate-jwt per convalidare i token di External ID, impostando l'URL openid-config sull'endpoint dei metadati del tenant.
• Senza Gestione API, convalidare i token nel middleware dell'applicazione usando Microsoft. Identity.Web (.NET).

Preparare il comportamento di cutover della sessione

Se si prevede di abbreviare la durata del token di aggiornamento Cognito prima del cutover, eseguirla durante la preparazione, non durante la finestra di migrazione. I token di rinnovo esistenti possono rimanere validi fino alla scadenza del periodo di validità configurato, quindi apporta la modifica con sufficiente anticipo, in modo che i token emessi in precedenza scadano prima della fase di cutover. Usare la durata corrente del token di aggiornamento Cognito per decidere quando applicare questa impostazione.

Pianificare il cutover durante una finestra con traffico ridotto. Controllare le metriche di Cognito CloudWatch per trovare il periodo più tranquillo.

Preparare anche le comunicazioni utente per la riautenticazione. Quando gli utenti vengono spostati da Cognito a EXTERNAL ID, le sessioni Cognito attive potrebbero non riuscire al successivo aggiornamento del token e gli utenti potrebbero dover eseguire di nuovo l'accesso. Se la base utente è sensibile alla ripetizione forzata dell'autenticazione (ad esempio, app finanziarie o sanitarie), comunicare in modo proattivo prima dell'onda.

Eseguire test di carico e resilienza di pre-produzione

Eseguire test di carico di pre-produzione nell'ambiente pilota o di gestione temporanea prima della migrazione di produzione. Promuovere una frequenza di accesso realistica tramite l'ID esterno e l'applicazione, tra cui rilascio di token, chiamate API e chiamate di estensione di autenticazione personalizzate. Utilizzare i risultati per convalidare il comportamento del throttling, i margini personalizzati di timeout dell'estensione, gli avvisi del monitoraggio e i criteri di rollback prima del passaggio 3.

Passaggio 3: Eseguire

L'ambiente pilota viene convalidato, il codice è pronto e gli script di migrazione vengono testati. Ora esegui il cutover graduale. Segui attentamente il runbook e comunica con le parti interessate durante tutto il processo.

Eseguite il runbook che avete creato nel passaggio 1 per ogni ondata. Le sezioni seguenti forniscono i dettagli operativi per ogni passaggio.

Eseguite gli script di migrazione degli utenti per l'ondata

Esegui gli script di migrazione che hai creato e testato nel passaggio 2 per il gruppo di utenti di questa fase. Riconcilia i log di output: conferma gli utenti creati, esamina le operazioni di scrittura saltate o non riuscite e risolvi le identità duplicate prima di procedere.

Eseguire la migrazione di credenziali e account collegati tramite social network

Solo provider di identità social: Per gli utenti che accedono utilizzando solo provider di identità social, non c'è alcuna password da migrare. Il processo di migrazione collega l'utente dell'ID esterno allo stesso oggetto Facebook o Google, quindi l'accesso successivo funziona senza ripetere la registrazione. Se si imposta correttamente l'identità federata, la migrazione viene completata per questi utenti.

Account locali: Applica la strategia per le password selezionata nel passaggio 2 (reimpostazione forzata, JIT o senza password).

Alcuni utenti di Cognito hanno sia un collegamento di provider di social networking che una password locale. Quando incontri questi utenti, migra entrambe le identità. Aggiungere l'identità federata (Google, Facebook) all'oggetto utente tramite la identities raccolta in Microsoft Graph e impostare una password temporanea per le credenziali locali. L'identità social ha la priorità per l'accesso quando l'utente sceglie quel provider. Se l'utente accede con posta elettronica e password, il percorso della password dipende dall'opzione di migrazione scelta: l'estensione JIT convalida la password rispetto a Cognito o l'utente completa una reimpostazione della password self-service. Questo approccio mantiene entrambi i percorsi di accesso senza richiedere all'utente di scegliere.

Se si sceglie di usare JIT, seguire le indicazioni riportate nell'articolo esistente sulla migrazione delle password just-in-time nella documentazione di External ID. Il modello di implementazione è lo stesso per Cognito come per qualsiasi altro IdP legacy. Inoltre, pianificate queste modalità di guasto:

• Cognito non raggiungibile: L'utente non può accedere affatto durante l'interruzione. Valutare una soluzione di ripiego che preveda la reimpostazione forzata della password per gli utenti che non vengono migrati entro un intervallo di tempo prestabilito.
• La scrittura in Microsoft Graph non riesce dopo che Cognito ha convalidato: La password non viene salvata. L'accesso successivo contatta di nuovo Cognito, che funziona fino alla dismissione. Registrare questi errori e riprovare a scrivere Microsoft Graph in modo asincrono.
• Limitazione della velocità: L'API di AdminInitiateAuth Cognito prevede limiti di throttling. Se si usa JIT per migliaia di utenti contemporaneamente, implementare il backoff esponenziale.

Convalida la transizione MFA per l'ondata

MFA SMS: Se viene eseguita la migrazione del numero di telefono dell'utente all'ID esterno dall'esportazione dell'utente Cognito, SMS MFA può funzionare senza ripetere la registrazione, ma è necessario abilitare SMS come metodo MFA nel tenant ID esterno e collegare la sottoscrizione richiesta. Verificare che i numeri di telefono in Cognito siano in formato E.164, che l'ID esterno richiede.

Prima di includere gli utenti MFA in un ciclo di produzione, convalidare i metodi di autenticazione a più fattori con ID esterno supportati che si prevede di usare, ad esempio un passcode monouso o SMS tramite posta elettronica, oltre alla formattazione del numero di telefono, ai percorsi di ripristino e al completamento della richiesta di verifica dell'autenticazione a più fattori per gli utenti migrati.

Abilitare la logica personalizzata preparata

Abilitare solo le estensioni di autenticazione personalizzate e i flussi di lavoro sostitutivi preparati e convalidati nel passaggio 2. La fase 3 non è il momento di progettare o ricostruire i sostituti dei trigger Lambda.

Per lo scenario di accesso tramite social, verificare il comportamento predisposto in fase di esecuzione:

• Prima della generazione del token >OnTokenIssuanceStart: verificare che l'estensione preparata sia distribuita, abilitata, restituisca le attestazioni previste e soddisfi il budget di latenza.
• Flussi di lavoro sostitutivi dopo la conferma: Verificare che le notifiche di modifica di Microsoft Graph, Logic Apps, l'elaborazione dei registri di accesso o altre alternative predisposte siano operative.
• Flussi di lavoro di sostituzione prima della registrazione: Verificare che le estensioni predisposte per la raccolta degli attributi convalidino i dati immessi o blocchino le registrazioni come previsto.

Mantieni la logica di business identica quando la abiliti per la wave. Se si verifica un errore, usare il percorso di rollback preparato nel passaggio 2 anziché eseguire il debug di una nuova logica durante la finestra di cutover.

Verificare il comportamento di token e attestazioni

Verifica che la convalida del token e la mappatura delle attestazioni che hai preparato nel passaggio 2 funzionino correttamente per questa fase. Usa la tabella di mappatura delle dichiarazioni nel Passaggio 2 come riferimento. Confermare che:

• L'API accetta token ID esterni con l'autorità di certificazione e il gruppo di destinatari corretti.
• oid corrisponde all'utente corretto nei sistemi downstream.
• Le dichiarazioni roles o groups generano le decisioni di autorizzazione previste.
• Le attestazioni facoltative (email, given_namee così via) sono presenti se sono necessarie per l'API.
• La gestione dell'eccedenza dei gruppi funziona se gli utenti appartengono a più di 200 gruppi.
• I sistemi downstream (database, log di controllo, strumenti di supporto) risolvono correttamente gli identificatori utente migrati.

Dopo aver completato l'ultima fase di cutover e aver confermato l'assenza di traffico verso Cognito, rimuovi immediatamente l'issuer di Cognito dalla configurazione di convalida. Lasciare attive entrambe le autorità emittenti dopo la migrazione crea una superficie di attacco non necessaria.

Distribuire le modifiche dell'applicazione

Distribuire le modifiche dell'applicazione preparate nel passaggio 2. Il front-end deve passare da Amplify Auth, Cognito SDK o una libreria client OIDC a MSAL come parte dell'ondata di migrazione.

Usare la strategia di distribuzione convalidata nel progetto pilota. Un'implementazione MSAL pulita è meno costosa da mantenere e più facile da comprendere, ma una migrazione in più fasi potrebbe richiedere uno switch di configurazione temporaneo affinché i gruppi selezionati usino External ID mentre gli altri continuano a passare tramite Cognito.

Verificare che il codice distribuito usi l'implementazione MSAL preparata per il reindirizzamento dell'accesso, la selezione dell'account, l'acquisizione di token, la cache dei token, la disconnessione e le richieste di token API. Per le app basate su browser, usare la documentazione di MSAL Browser e MSAL React per l'accesso, l'acquisizione di token, gli account, la disconnessione e gli hook React. Se l'app precedente ha usato un client OIDC generico anziché Amplify Auth, verificare che l'autorità ID esterno, l'ID client, l'URI di reindirizzamento, gli ambiti e il codice di gestione dei token corrispondano alla configurazione MSAL convalidata nel progetto pilota.

Verificare la configurazione distribuita:

Confermare che:

• L'ID client OAuth e l'URL dell'authority nella configurazione MSAL puntano a External ID.
• L'URI di reindirizzamento corrisponde a quello registrato in ID esterno.
• Le chiamate API richiedono i nuovi scope dell'ID esterno.
• Qualsiasi codice che elabora il token ID o il token di accesso utilizza la mappatura delle attestazioni preparata.

Procedura di passaggio

Usare questo elenco di controllo per ogni ondata di migrazione:

1. Esegui le verifiche di convalida pre-cutover per l'ondata (un sottoinsieme della convalida completa nel passaggio 4):
   • Accedi a ogni provider di identità social configurato utilizzando un utente migrato.
   • Verificare che venga emesso un token.
   • Verificare che all'utente non venga richiesto di eseguire di nuovo la registrazione.
   • Completa una nuova registrazione.
   • Confermare che il token di accesso includa i ruoli previsti o i claim di gruppo.
   • Verificare che siano presenti i claim personalizzati obbligatori.
   • Verificare che le estensioni di autenticazione personalizzate siano completate entro il timeout.
   • Verificare che l'applicazione sia in grado di chiamare l'API di back-end.
2. Verificare che le estensioni di autenticazione personalizzate siano distribuite e restituiscano risposte valide.
3. Se è abilitato il provider di attestazioni personalizzate o la logica di rilascio di token personalizzati, verificare che la chiave di firma specifica dell'applicazione sia configurata, attiva e non scaduta prima di abilitare il flusso nell'ambiente di produzione.
4. Se gli utenti riscontrano AADSTS50146 o invalid_request immediatamente dopo aver abilitato l'estensione, disattivino l'estensione o il provider di attestazioni come procedura di rollback, ripristinino l'accesso e quindi correggano la configurazione della chiave di firma prima di riprovare.
5. Verificare che gli URI di reindirizzamento di Social IdP funzionino sul lato ID esterno. (Testa l'accesso con ciascun provider nell'ambiente pilota.)
6. Conferma che la durata del refresh token di Cognito fosse già stata ridotta durante la Fase 2, se ciò era previsto nel piano di cutover.
7. Attendere la scadenza delle sessioni Cognito attive o invalidarle revocando i token di aggiornamento tramite l'API AdminUserGlobalSignOut .
8. Distribuisci l'aggiornamento dell'applicazione che sostituisce Amplify Auth / Cognito SDK con MSAL con l'autorità External ID.
9. Monitorare i log di accesso per i primi 15 minuti. Controllare gli errori, i timeout di estensione personalizzati e i valori di attestazione imprevisti.
10. Esaminare la checklist di convalida post-migrazione (passo 4).
11. Se gli errori superano la soglia, esegui il rollback: ridistribuisci la versione precedente dell'app che fa riferimento a Cognito. Entrambi gli URI di reindirizzamento sono ancora attivi, quindi il rollback è una modifica della configurazione.

Passaggio 4: Valutare

Il cutover di ogni onda è completo. Verifica che funzioni prima di espandere o disattivare.

Convalidare la migrazione con test end-to-end prima di considerarla completata.

Elenco di controllo di convalida post-migrazione

Completa le verifiche seguenti dopo ogni ondata di migrazione e dopo il cutover finale per convalidare la migrazione end-to-end. Questa checklist comprende tutti gli elementi della verifica pre-cutover al passaggio 3 e aggiunge scenari post-migrazione.

Accedi con ciascun provider di identità social configurato per la tua applicazione utilizzando un utente migrato. Confermare che:

• Viene emesso un token.
• All'utente non viene richiesto di eseguire di nuovo la registrazione.

Completa una nuova iscrizione con ciascun provider di identità social. Confermare che:

• L'utente viene creato in EXTERNAL ID con gli attributi previsti.
• Un utente di ritorno che ha impostato una password (ad esempio, dopo una reimpostazione forzata della password) può accedere utilizzando la nuova password.
• Il token di accesso include il claim dei gruppi o dei ruoli attesi.
• Il token di accesso include tutte le attestazioni personalizzate richieste dall'API.
• L'estensione di autenticazione personalizzata viene eseguita e completata entro il timeout configurato.
• L'applicazione può chiamare con successo l'API back-end usando il token di accesso ID esterno.
• Le decisioni di autorizzazione API corrispondono al comportamento osservato in Cognito per lo stesso utente.

Verificare i flussi di autenticazione e l'autorizzazione api

Oltre a esaminare la checklist, esegui questi scenari prima del passaggio in produzione:

• Chiamata API per il rilascio del token per l'accesso social nel percorso happy-path >>: End-to-end, tramite gli stessi percorsi di codice usati in produzione.
• Collegamento dell'account: Un utente che esiste già in ID esterno (utente migrato) accede con lo stesso account Google. Assicurarsi che corrispondano all'utente esistente, non a uno nuovo.
• Richiesta di autenticazione a più fattori: Se l'autenticazione a più fattori è abilitata, eseguire un passaggio di convalida MFA separato per i metodi di ID esterno supportati configurati, ad esempio passcode monouso o SMS tramite posta elettronica. Verificare il recapito del codice di verifica, il formato del numero di telefono per gli SMS, il comportamento del ripristino e il corretto accesso degli utenti migrati.
• Reimpostazione della password (per gli account locali, se è stata usata la reimpostazione forzata): L'utente esegue il flusso di reimpostazione della password self-service e accede di nuovo.
• Scadenza e aggiornamento dei token: Consentire a un token di accesso di scadere e verificare che il flusso del token di aggiornamento funzioni tramite MSAL.
• Limiti di autorizzazione API: Eseguire nuovamente gli stessi test di autorizzazione usati con Cognito, questa volta usando i token di accesso rilasciati con ID esterno. Verificare che all'identità di test in sola lettura siano negate le operazioni di scrittura e che l'identità di test con privilegi elevati possa eseguire sia operazioni di lettura sia di scrittura, in base ai ruoli o gruppi configurati per l'app.

Se si esegue la migrazione per fasi, utilizzare l'elenco di controllo dopo ogni fase.

Controllare il monitoraggio

Verificare che il monitoraggio configurato nel passaggio 2, Preparare, generi dati. Esamina i log di accesso e i dashboard personalizzati delle metriche delle estensioni.

Misurare i risultati in base ai criteri di esito positivo definiti nel passaggio 1, piano.

Esamina i risultati del test di carico pre-produzione della fase 2 come parte della validazione non funzionale. Dopo ogni fase, confronta i dati di telemetria di produzione con la baseline del test di carico pilota e verifica eventuali limitazioni, i timeout delle estensioni personalizzate e la latenza di coda.

Verifica il passaggio del traffico

Prima di disattivare il servizio, verifica che nessun traffico raggiunga Cognito:

• Controllare le metriche di Cognito CloudWatch per le richieste di accesso e token. Per i client del pool di utenti che vengono rimossi, le metriche come SignInSuccesses, FederationSuccessese TokenRefreshSuccesses devono rimanere a zero durante la finestra di osservazione.
• Controllare i log applicazioni per qualsiasi chiamata a un endpoint Cognito.
• Controllare le console per sviluppatori del provider di identità social per verificare l'eventuale utilizzo residuo degli URI di reindirizzamento di Cognito.

Osservare le metriche per alcuni giorni prima di rimuovere qualsiasi elemento.

Per le app per dispositivi mobili, controllare l'analisi dell'App Store per confermare l'adozione della nuova versione (quella che usa MSAL). Mantenere Cognito attivo (senza nuovi accessi consentiti) fino a quando la versione precedente dell'app non scende al di sotto della soglia accettabile (ad esempio, meno di 1% di utenti attivi). Non è possibile forzare l'aggiornamento delle app per dispositivi mobili. La rimozione di Cognito mentre le versioni precedenti sono in uso bloccano tali utenti.

Passaggio 5: Dismissione

Tutte le ondate hanno superato la fase di convalida e hai confermato l'assenza di traffico Cognito nel passaggio 4. Rimuovi l'infrastruttura obsoleta.

Archiviare i dati, rimuovere le risorse e notificare agli stakeholder

Quando sei sicuro che non ci sarà traffico verso Cognito:

1. Archiviare ciò che è necessario mantenere per la conformità: Esportare dati utente, log di controllo ed eventi CloudTrail. Archiviarli in base ai criteri di conservazione.
2. Garantire la continuità dei registri di controllo: Iniziare a esportare i registri di accesso e di controllo di External ID nel sistema SIEM prima del cutover, in modo che vi sia una sovrapposizione tra gli eventi di Cognito CloudTrail e i registri di External ID. In questo modo viene fornita una copertura di controllo continua per la conformità.
3. Convalidare i consumer downstream degli eventi: Verificare che gli allarmi CloudWatch sugli eventi di Cognito, le regole di EventBridge, i webhook di terze parti, le notifiche SNS/SQS e gli altri consumer degli eventi dello user pool siano stati migrati o dismessi. Convalidare le origini di sostituzione prima di eliminare Cognito in modo che i flussi di lavoro downstream non si interrompano automaticamente.
4. Rimuovere gli URI di reindirizzamento Cognito dalle console per sviluppatori di Google e Facebook: Questo passaggio impedisce a qualsiasi configurazione non aggiornata di inviare nuovamente il traffico.
5. Disabilitare o eliminare i client dell'app Cognito: Al termine della finestra di rollback, disabilitare o eliminare i client dell'app Cognito e rimuovere eventuali segreti client associati. Se si elimina il pool di utenti, i client dell'app vengono rimossi come parte di tale pulizia.
6. Disabilitare gli accessi: Disabilitare gli accessi sui client dell'app Cognito prima di eliminarli, così da poter individuare qualsiasi traffico che sia sfuggito.
7. Eliminare il pool di utenti e il pool di identità: Se si usa un utente o un pool di identità, eliminarli per evitare usi accidentali e arrestare eventuali costi associati.
8. Pulisci: Pulisci i trigger Lambda, i ruoli IAM e gli authorizer di API Gateway che facevano riferimento al pool di utenti.
9. Notifica agli stakeholder: Inviare una notifica al team operativo, al team di supporto e ai proprietari interni che avevano visibilità su Cognito. Se l'esperienza utente è cambiata in modo evidente, inviare una notifica agli utenti finali tramite un messaggio di posta elettronica o un messaggio in-app prima del cutover, non dopo.

Conclusione

A questo punto, gli utenti accedono tramite ID esterno, le API back-end convalidano i token ID esterni e Cognito è completamente rimosso. Se si verificano problemi dopo il passaggio, controlla prima i log di accesso di External ID. Molti problemi post-migrazione derivano da incongruenze nella mappatura delle attestazioni o da timeout delle estensioni personalizzate.

Contenuti correlati

Pianificazione

• Pianificazione della gestione delle identità e degli accessi dei clienti
• Limiti e restrizioni del servizio

Migrazione utente

• Eseguire la migrazione di utenti e credenziali a Microsoft Entra per ID esterno
• Migrazione delle password just-in-time verso Microsoft Entra per ID esterno

Token e attestazioni

• Piattaforma di identità Microsoft e flusso del codice di autorizzazione OAuth 2.0
• Informazioni di riferimento sulle attestazioni del token di accesso
• Informazioni di riferimento sulle attestazioni del token ID
• Configurare le attestazioni di gruppo per le applicazioni

Risorse per sviluppatori e logica personalizzata

• Centro per sviluppatori Microsoft Entra per ID esterno
• Estensioni di autenticazione personalizzate