Registrare un'applicazione

  • 12 minuti

Registrare un'applicazione

La registrazione dell'applicazione consente di stabilire una relazione di trust tra l'app e Microsoft Identity Platform. La relazione di trust è unidirezionale, ovvero l'app considera attendibile Microsoft Identity Platform e non viceversa.

  1. Accedere all'interfaccia di amministrazione di Microsoft Entra usando un account amministratore globale.

  2. Aprire il menu del portale e quindi selezionare Identità.

  3. Nel menu Identità, in Applicazioni, selezionare Registrazioni app.

  4. Nella pagina Registrazioni app scegliere + Nuova registrazione dal menu.

  5. Nela finestra di dialogo Registra un'applicazione registrare un'app denominata Demo app usando i valori predefiniti. Non è necessario immettere l'URI di reindirizzamento.

    Screenshot of the Register an application screen with the name and default settings highlighted.

  6. Al termine, verrà visualizzata la schermata Demo app.

Aggiungere un URI di reindirizzamento

Un URI di reindirizzamento corrisponde alla posizione a cui Microsoft Identity Platform reindirizza il client di un utente e invia i token di sicurezza dopo l'autenticazione. In un'applicazione Web di produzione, ad esempio, l'URI di reindirizzamento è spesso un endpoint pubblico in cui è in esecuzione l'app. Durante lo sviluppo è prassi comune aggiungere anche l'endpoint in cui l'app viene eseguita in locale.

Per aggiungere e modificare gli URI di reindirizzamento per le applicazioni registrate, configurare le impostazioni della piattaforma.

Configurare le impostazioni della piattaforma

Le impostazioni per ogni tipo di applicazione, inclusi gli URI di reindirizzamento, vengono configurate in Configurazioni della piattaforma nel portale di Azure. Con alcune piattaforme, ad esempio le applicazioni Web e a pagina singola, è necessario specificare manualmente un URI di reindirizzamento. Per altre piattaforme, ad esempio per applicazioni desktop e per dispositivi mobili, è possibile scegliere tra gli URI di reindirizzamento generati quando si configurano le altre impostazioni di tali piattaforme.

Per configurare le impostazioni dell'applicazione in base alla piattaforma o al dispositivo di destinazione:

  1. Selezionare l'applicazione in Registrazioni app nel portale di Azure.

  2. In Gestisci selezionare Autenticazione.

  3. In Configurazioni della piattaforma selezionare Aggiungi una piattaforma.

  4. In Configura le piattaforme selezionare il riquadro relativo al tipo di applicazione (piattaforma) per configurarne le impostazioni.

    Screenshot of the Platform configuration pane in the Microsoft Entra admin center.

    Piattaforma Impostazioni di configurazione
    Web Immettere un URI di reindirizzamento per l'app, ovvero la posizione a cui Microsoft Identity Platform reindirizza il client di un utente e invia i token di sicurezza dopo l'autenticazione. Selezionare questa piattaforma per le applicazioni Web standard eseguite in un server.
    Applicazione a pagina singola Immettere un URI di reindirizzamento per l'app, ovvero la posizione a cui Microsoft Identity Platform reindirizza il client di un utente e invia i token di sicurezza dopo l'autenticazione. Selezionare questa piattaforma se si sta creando un'app Web lato client in JavaScript o con un framework come Angular, Vue.js, React.js o Blazor WebAssembly.
    iOS/macOS Immettere il valore di ID bundle dell'app, disponibile in XCode in Info.plist o nelle impostazioni di compilazione. Quando si specifica un ID bundle, viene generato automaticamente un URI di reindirizzamento.
    Android Immettere il valore di Nome pacchetto per l'app, che è possibile trovare nel file AndroidManifest.xml, quindi generare e immettere il valore di Hash della firma. Quando si specificano queste impostazioni, viene generato automaticamente un URI di reindirizzamento.
    Applicazioni per dispositivi mobili e desktop Selezionare uno degli URI di reindirizzamento suggeriti oppure specificare un URI di reindirizzamento personalizzato. Per le applicazioni desktop, è consigliabile usare https://login.microsoftonline.com/common/oauth2/nativeclient. Selezionare questa piattaforma per le applicazioni per dispositivi mobili che non usano la versione più recente di Microsoft Authentication Library (MSAL) o che non usano un broker. Selezionare questa piattaforma anche per le applicazioni desktop.

  5. Selezionare Configura per completare la configurazione della piattaforma.

Aggiungi credenziali

Le credenziali vengono usate dalle applicazioni client riservate che accedono a un'API Web. Esempi di client riservati sono le app Web, altre API Web e applicazioni di tipo servizio e daemon. Le credenziali consentono all'applicazione di eseguire l'autenticazione in modo autonomo, senza richiedere alcuna interazione utente in fase di esecuzione.

È possibile aggiungere sia certificati che segreti client (una stringa) come credenziali della registrazione dell'app client riservata.

Screenshot of Azure portal showing the Certificates and secrets pane in app registration.

Aggiungere un certificato

I certificati, talvolta detti chiave pubblica, sono il tipo di credenziale consigliato perché offrono un livello di garanzia superiore rispetto a un segreto client. Quando si usa un certificato pubblico attendibile, è possibile aggiungere il certificato usando la funzionalità Certificati e segreti. Il tipo di file del certificato deve essere uno dei seguenti: .cer, .pem, .crt.

Aggiungere un segreto client

Il segreto client, detto anche password dell'applicazione, è un valore stringa che l'app può usare al posto di un certificato per identificarsi. Tra i due tipi di credenziali è quello più facile da usare. Viene spesso usato in fase di sviluppo, ma è considerato meno sicuro di un certificato. È infatti consigliabile usare i certificati nelle applicazioni in esecuzione nell'ambiente di produzione.

  1. Selezionare l'applicazione in Registrazioni app nel portale di Azure.
  2. Selezionare Certificati e segreti, quindi selezionare Nuovo segreto client.
  3. Aggiungere una descrizione per il segreto client.
  4. Selezionare una durata.
  5. Seleziona Aggiungi.
  6. Prendere nota del valore del segreto per usarlo nel codice dell'applicazione client in quanto non verrà più visualizzato dopo che si chiude questa pagina.

Registrare l'API Web

Per fornire l'accesso con ambito alle risorse nell'API Web, è necessario prima di tutto registrare l'API con Microsoft Identity Platform.

  1. Eseguire la procedura indicata in precedenza.
  2. Ignorare le sezioni Aggiungere un URI di reindirizzamento e Configurare le impostazioni della piattaforma. Non è necessario configurare un URI di reindirizzamento per un'API Web perché nessun utente è connesso in modo interattivo.
  3. Per il momento ignorare la sezione Aggiungere le credenziali. L'API necessita di credenziali solo se accede a un'API downstream, ma questo scenario non viene trattato in questo articolo.

Dopo aver registrato l'API Web, è possibile aggiungere gli ambiti che il codice API può usare per fornire l'autorizzazione granulare ai consumer dell'API.

Aggiungere un ambito

Per richiedere l'autorizzazione per eseguire le operazioni definite dall'API Web, il codice in un'applicazione client passa un token di accesso unitamente alle relative richieste alla risorsa protetta, ovvero l'API Web. L'API Web esegue quindi l'operazione richiesta solo se il token di accesso ricevuto contiene gli ambiti (noti anche come autorizzazioni delle applicazioni) necessari per l'operazione.

Prima di tutto, seguire questa procedura per creare un ambito di esempio denominato Employees.Read.All:

  1. Accedi al portale di Azure.

  2. Se si ha accesso a più tenant, usare il filtro Directory e sottoscrizione nel menu in alto per selezionare il tenant contenente la registrazione dell'app client.

  3. Selezionare Microsoft Entra ID, quindi Registrazioni app e poi selezionare la registrazione dell'app dell'API.

  4. Selezionare Esporre un'API, quindi Aggiungi un ambito.

    Screenshot of an app registration's Expose an API pane in the Microsoft Entra admin center.

  5. Se non è stato ancora configurato, viene richiesto di impostare un valore per URI ID applicazione. L'URI dell'ID applicazione funge da prefisso per gli ambiti a cui verrà fatto riferimento nel codice dell'API e deve essere univoco a livello globale. È possibile usare il valore predefinito fornito, in formato api://, oppure specificare un URI più leggibile, ad esempio https://contoso.com/api.

  6. Specificare quindi gli attributi dell'ambito nel riquadro Aggiungi un ambito. Per questa procedura dettagliata è possibile usare i valori di esempio o specificare valori personalizzati.

    Campo Descrizione Esempio
    Nome ambito Nome dell'ambito. Una convenzione di denominazione comune per l'ambito è risorsa.operazione.vincolo. Employees.Read.All
    Utenti che possono fornire il consenso L'amministrazione sceglie se il consenso per l'ambito può essere fornito dagli utenti oppure se è necessario il consenso amministratore. Selezionare Solo amministratori per autorizzazioni con privilegi più elevati. Amministratori e utenti
    Nome visualizzato consenso dell'amministratore Breve descrizione dello scopo dell'ambito che verrà visualizzata solo dagli amministratori. Accesso di sola lettura ai record dei dipendenti
    Descrizione consenso dell'amministratore Descrizione più dettagliata dell'autorizzazione concessa dall'ambito che verrà visualizzata solo dagli amministratori. Consentire all'applicazione l'accesso di sola lettura a tutti i dati dei dipendenti.
    Nome visualizzato per il consenso utente Breve descrizione dello scopo dell'ambito. Viene visualizzata agli utenti solo se si imposta Utenti che possono fornire il consenso su Amministratori e utenti. Accesso di sola lettura ai record dei dipendenti
    Descrizione del consenso utente Descrizione più dettagliata dell'autorizzazione concessa dall'ambito. Viene visualizzata agli utenti solo se si imposta Utenti che possono fornire il consenso su Amministratori e utenti. Consentire all'applicazione l'accesso di sola lettura a tutti i dati dei dipendenti.

  7. Impostare Stato su Abilitato e quindi selezionare Aggiungi ambito.

  8. (Facoltativo) Per rimuovere la richiesta del consenso degli utenti dell'app per gli ambiti definiti, è possibile pre-autorizzare l'accesso dell'applicazione client all'API Web. Pre-autorizzare solo le applicazioni client attendibili, perché gli utenti non hanno la possibilità di rifiutare il consenso.

    1. In Applicazioni client autorizzate selezionare Aggiungi applicazione client.
    2. Immettere il valore di ID applicazione (client) dell'applicazione client da pre-autorizzare, ad esempio quello di un'applicazione Web già registrata.
    3. In Ambiti autorizzatiselezionare gli ambiti per cui rimuovere la richiesta di consenso, quindi selezionare Aggiungi applicazione.
    4. Se è stato eseguito questo passaggio facoltativo, l'app client è ora un'app client pre-autorizzata e agli utenti non verrà richiesto il consenso per accedervi.

Aggiungere quindi un altro ambito di esempio denominato Employees.Write.All per il quale solo gli amministratori possono concedere il consenso. Gli ambiti che richiedono il consenso amministratore vengono usati in genere per fornire l'accesso a operazioni con privilegi più elevati, spesso da parte di applicazioni client che vengono eseguite come servizi back-end o daemon che non consentono l'accesso utente interattivo.

Per aggiungere l'ambito di esempio Employees.Write.All, seguire la procedura descritta in precedenza e specificare questi valori nel riquadro Aggiungi un ambito:

Campo Valore di esempio
Nome ambito Employees.Write.All
Utenti che possono fornire il consenso Solo amministratori
Nome visualizzato consenso dell'amministratore Accesso in scrittura ai record dei dipendenti
Descrizione consenso dell'amministratore Consentire all'applicazione l'accesso in scrittura a tutti i dati dei dipendenti.
Nome visualizzato per il consenso utente Nessuno (lasciare vuoto)
Descrizione del consenso utente Nessuno (lasciare vuoto)

Verificare gli ambiti esposti

Se sono stati aggiunti entrambi, gli ambiti di esempio descritti nelle sezioni precedenti verranno visualizzati nel riquadro Esporre un'API della registrazione dell'app dell'API Web, come illustrato nell'immagine seguente:

Screenshot of the Expose an API pane showing two exposed scopes for assignment in the app registration.

Come illustrato nell'immagine, la stringa completa di un ambito è costituita dalla concatenazione del valore URI ID applicazione dell'API Web e del valore di Nome ambito dell'ambito.

Se, ad esempio, l'URI ID applicazione dell'API Web è https://contoso.com/api e il nome dell'ambito è Employees.Read.All, l'ambito completo è:

https://contoso.com/api/Employees.Read.All

Uso degli ambiti esposti

Verrà quindi eseguita la configurazione della registrazione di un'app client con accesso all'API Web e agli ambiti definiti seguendo la procedura descritta in precedenza.

Dopo che a una registrazione dell'app del client è stata concessa l'autorizzazione per accedere all'API Web, Microsoft Identity Platform può rilasciare al client un token di accesso OAuth 2.0. Quando il client chiama l'API Web, presenta un token di accesso la cui attestazione di ambito (scp) è impostata sulle autorizzazioni specificate nella registrazione dell'app client.

Se necessario, è possibile esporre altri ambiti successivamente. Tenere presente che l'API Web può esporre più ambiti associati a operazioni diverse. La risorsa può controllare l'accesso all'API Web in fase di esecuzione, valutando le attestazioni di ambito (scp) nel token di accesso OAuth 2.0 ricevuto.

Cosa sta succedendo dietro le quinte

  • La registrazione dell'app viene creata nel tenant principale
  • L'app è istanziata con un'entità di sicurezza in Microsoft Entra ID
  • All'entità di sicurezza viene concesso il consenso dal primo utente o amministratore, in base alla configurazione dell'API esposta
  • All'entità di sicurezza viene concesso il token di sicurezza quando l'utente accede all'applicazione e usa l'API