Informazioni sul manifesto dell'applicazione in Azure Active DirectoryUnderstanding the Azure Active Directory application manifest

Le applicazioni che si integrano con Azure Active Directory (AD) devono essere registrate con un tenant di Azure AD, fornendo una configurazione dell'identità permanente per l'applicazione.Applications that integrate with Azure Active Directory (AD) must be registered with an Azure AD tenant, providing a persistent identity configuration for the application. Questa configurazione viene valutata in fase di esecuzione, rendendo possibili scenari che consentono a un'applicazione di eseguire l'outsourcing e negoziare le operazioni di autenticazione/autorizzazione tramite Azure AD.This configuration is consulted at runtime, enabling scenarios that allow an application to outsource and broker authentication/authorization through Azure AD. Per altre informazioni sul modello applicativo di Azure AD, vedere l'articolo relativo ad aggiunta, aggiornamento e rimozione di un'applicazione.For more information about the Azure AD application model, see the Adding, Updating, and Removing an Application article.

Aggiornamento della configurazione dell'identità di un'applicazioneUpdating an application's identity configuration

Per l'aggiornamento delle proprietà di configurazione dell'identità di un'applicazione esistono in effetti più opzioni, che variano per funzionalità e livelli di difficoltà, incluse le seguenti:There are actually multiple options available for updating the properties on an application's identity configuration, which vary in capabilities and degrees of difficulty, including the following:

  • L'interfaccia utente Web del portale di Azure consente di aggiornare le proprietà più comuni di un'applicazione.The Azure portal's Web user interface allows you to update the most common properties of an application. Questo è il modo più rapido e meno soggetto a errori di aggiornare le proprietà dell'applicazione, ma non consente l'accesso completo a tutte le proprietà come i due metodi seguenti.This is the quickest and least error prone way of updating your application's properties, but does not give you full access to all properties, like the next two methods.
  • Per gli scenari più avanzati in cui è necessario aggiornare proprietà non esposte nel portale di Azure classico, si può modificare il manifesto dell'applicazione.For more advanced scenarios where you need to update properties that are not exposed in the Azure classic portal, you can modify the application manifest. Questo è l'argomento su cui verte questo articolo, che verrà illustrato più dettagliatamente nella sezione successiva.This is the focus of this article and is discussed in more detail starting in the next section.
  • È anche possibile scrivere un'applicazione che usa l'API Graph per aggiornare l'applicazione, ma ciò richiede un impegno maggiore.It's also possible to write an application that uses the Graph API to update your application, which requires the most effort. Questa può tuttavia essere un'opzione interessante se si scrive software di gestione o se è necessario aggiornare le proprietà dell'applicazione a intervalli regolari e in modo automatico.This may be an attractive option though, if you are writing management software, or need to update application properties on a regular basis in an automated fashion.

Uso del manifesto dell'applicazione per aggiornare la configurazione dell'identità di un'applicazioneUsing the application manifest to update an application's identity configuration

Tramite il portale di Azure è possibile gestire la configurazione dell'identità dell'applicazione aggiornando il manifesto dell'applicazione mediante l'editor del manifesto inline.Through the Azure portal, you can manage your application's identity configuration by updating the application manifest using the inline manifest editor. È anche possibile scaricare e caricare il manifesto dell'applicazione come file JSON.You can also download and upload the application manifest as a JSON file. Nessun file effettivo viene archiviato nella directory,No actual file is stored in the directory. perché il manifesto dell'applicazione è semplicemente un'operazione GET HTTP sull'entità dell'applicazione API Graph di Azure AD e il caricamento è un'operazione PATCH HTTP sull'entità dell'applicazione.The application manifest is merely an HTTP GET operation on the Azure AD Graph API Application entity, and the upload is an HTTP PATCH operation on the Application entity.

Per comprendere il formato e le proprietà del manifesto dell'applicazione, sarà quindi necessario vedere la documentazione relativa all'entità applicazione dell'API Graph.As a result, in order to understand the format and properties of the application manifest, you will need to reference the Graph API Application entity documentation. Ecco alcuni esempi di aggiornamenti che possono essere eseguiti con il caricamento del manifesto dell'applicazione:Examples of updates that can be performed though application manifest upload include:

  • Dichiarare gli ambiti di autorizzazione (oauth2Permissions) esposti dall'API Web.Declare permission scopes (oauth2Permissions) exposed by your web API. Per informazioni sull'implementazione della rappresentazione dell'utente tramite l'ambito delle autorizzazioni delegate di oauth2Permissions, vedere l'argomento relativo all'esposizione delle API Web ad altre applicazioni in Integrazione di applicazioni con Azure Active Directory.See the "Exposing Web APIs to Other Applications" topic in Integrating Applications with Azure Active Directory for information on implementing user impersonation using the oauth2Permissions delegated permission scope. Come accennato in precedenza, tutte le proprietà dell'entità applicazione sono documentate nell'articolo di riferimento per entità e tipi complessi dell'API Graph, compresa la proprietà oauth2Permissions che è una raccolta di tipo OAuth2Permission.As mentioned previously, Application entity properties are documented in the Graph API Entity and Complex Type reference article, including the oauth2Permissions property which is a collection of type OAuth2Permission.
  • Dichiarare i ruoli applicazione (appRoles) esposti dall'app.Declare application roles (appRoles) exposed by your app. La proprietà appRoles dell'entità applicazione è una raccolta di tipo AppRole.The Application entity's appRoles property is a collection of type AppRole. Per un esempio di implementazione, vedere Role based access control in cloud applications using Azure AD (Controllo degli accessi in base al ruolo in applicazioni cloud tramite Azure AD).See the Role based access control in cloud applications using Azure AD article for an implementation example.
  • Dichiarare le applicazioni client note (knownClientApplications)che consentono di associare in modo logico il consenso delle applicazioni client specificate all'API Web o della risorsa.Declare known client applications (knownClientApplications), which allow you to logically tie the consent of the specified client application(s) to the resource/web API.
  • Richiedere ad Azure AD di rilasciare l'attestazione di appartenenza al gruppo per l'utente connesso (groupMembershipClaims).Request Azure AD to issue group memberships claim for the signed in user (groupMembershipClaims). Può anche essere configurato per il rilascio di attestazioni relative alle appartenenze ai ruoli della directory dell'utente.This can also be configured to issue claims about the user's directory roles memberships. Per un esempio di implementazione, vedere Authorization in Cloud Applications using AD Groups (Autorizzazione in applicazioni cloud con i gruppi di AD).See the Authorization in Cloud Applications using AD Groups article for an implementation example.
  • Consentire all'applicazione di supportare flussi di concessione implicita OAuth 2.0 (oauth2AllowImplicitFlow).Allow your application to support OAuth 2.0 Implicit grant flows (oauth2AllowImplicitFlow). Questo tipo di flusso di concessione viene usato con pagine Web con JavaScript incorporato o con applicazioni a pagina singola (Single Page Applications, SPA).This type of grant flow is used with embedded JavaScript web pages or Single Page Applications (SPA). Per altre informazioni sulla concessione implicita di autorizzazioni, vedere Informazioni sul flusso di concessione implicita OAuth2 in Azure Active Directory.For more information on the implicit authorization grant, see Understanding the OAuth2 implicit grant flow in Azure Active Directory.
  • Abilitare l'uso di certificati X509 come chiave privata (keyCredentials).Enable use of X509 certificates as the secret key (keyCredentials). Per esempi di implementazione, vedere Build service and daemon apps in Office 365 (Compilare app di servizio e daemon in Office 365) e Developer's guide to auth with Azure Resource Manager API (Guida per gli sviluppatori all'autorizzazione con l'API di Azure Resource Manager).See the Build service and daemon apps in Office 365 and Developer’s guide to auth with Azure Resource Manager API articles for implementation examples.
  • Aggiungere un nuovo URI ID app per l'applicazione (identifierURIs[]).Add a new App ID URI for your application (identifierURIs[]). Gli URI ID app vengono usati per identificare in modo univoco un'applicazione nel tenant di Azure AD (o in più tenant di Azure AD, per gli scenari multi-tenant quando vengono qualificati tramite un dominio personalizzato verificato).App ID URIs are used to uniquely identify an application within its Azure AD tenant (or across multiple Azure AD tenants, for multi-tenant scenarios when qualified via verified custom domain). Vengono usati quando si richiedono autorizzazioni a un'applicazione della risorsa o si acquisisce un token di accesso per un'applicazione della risorsa.They are used when requesting permissions to a resource application, or acquiring an access token for a resource application. Quando si aggiorna questo elemento, lo stesso aggiornamento viene eseguito nella raccolta servicePrincipalNames[] dell'entità servizio corrispondente, che si trova nel tenant home dell'applicazione.When you update this element, the same update is made to the corresponding service principal's servicePrincipalNames[] collection, which lives in the application's home tenant.

Il manifesto dell'applicazione fornisce anche un ottimo modo per tenere traccia dello stato di registrazione dell'applicazione.The application manifest also provides a good way to track the state of your application registration. Essendo disponibile in formato JSON, la rappresentazione del file può essere verificata nel controllo del codice sorgente insieme al codice sorgente della propria applicazione.Because it's available in JSON format, the file representation can be checked into your source control, along with your application's source code.

Esempio dettagliatoStep by step example

Si esamineranno ora i passaggi necessari per aggiornare la configurazione dell'identità dell'applicazione tramite il manifesto dell'applicazione.Now lets walk through the steps required to update your application's identity configuration through the application manifest. Verrà evidenziato uno degli esempi precedenti, che illustra come dichiarare un nuovo ambito di autorizzazione per un'applicazione della risorsa:We will highlight one of the preceding examples, showing how to declare a new permission scope on a resource application:

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Dopo essersi autenticati, scegliere il tenant di Azure AD selezionandolo nell'angolo superiore destro della pagina.After you've authenticated, choose your Azure AD tenant by selecting it from the top right corner of the page.
  3. Selezionare l'estensione Azure Active Directory dal pannello di navigazione a sinistra e fare clic su Registrazioni per l'app.Select Azure Active Directory extension from the left navigation panel and click on App Registrations.
  4. Trovare l'applicazione che si vuole aggiornare e fare clic sul nome.Find the application you want to update in the list and click on it.
  5. Nella pagina dell'applicazione fare clic su Manifesto per aprire l'editor di manifesto integrato.From the application page, click Manifest to open the inline manifest editor.
  6. È possibile modificare direttamente il manifesto usando l'editor.You can directly edit the manifest using this editor. Si noti che il manifesto segue lo schema per l'entità applicazione, come spiegato in precedenza. Supponendo ad esempio che si voglia implementare o esporre una nuova autorizzazione chiamata "Employees.Read.All" nell'applicazione della risorsa (API), è sufficiente aggiungere un elemento nuovo o un secondo elemento alla raccolta oauth2Permissions, ossia:Note that the manifest follows the schema for the Application entity as we mentioned earlier: For example, assuming we want to implement/expose a new permission called "Employees.Read.All" on our resource application (API), you would simply add a new/second element to the oauth2Permissions collection, ie:

     "oauth2Permissions": [
     {
     "adminConsentDescription": "Allow the application to access MyWebApplication on behalf of the signed-in user.",
     "adminConsentDisplayName": "Access MyWebApplication",
     "id": "aade5b35-ea3e-481c-b38d-cba4c78682a0",
     "isEnabled": true,
     "type": "User",
     "userConsentDescription": "Allow the application to access MyWebApplication on your behalf.",
     "userConsentDisplayName": "Access MyWebApplication",
     "value": "user_impersonation"
     },
     {
     "adminConsentDescription": "Allow the application to have read-only access to all Employee data.",
     "adminConsentDisplayName": "Read-only access to Employee records",
     "id": "2b351394-d7a7-4a84-841e-08a6a17e4cb8",
     "isEnabled": true,
     "type": "User",
     "userConsentDescription": "Allow the application to have read-only access to your Employee data.",
     "userConsentDisplayName": "Read-only access to your Employee records",
     "value": "Employees.Read.All"
     }
     ],
    

    La voce deve essere univoca, pertanto è necessario generare un nuovo ID univoco globale (GUID) per la proprietà "id" .The entry must be unique, and you must therefore generate a new Globally Unique ID (GUID) for the "id" property. In questo caso, poiché si è specificato "type": "User", è possibile concedere l'autorizzazione da qualsiasi account autenticato dal tenant di Azure AD nel quale è registrata l'applicazione API o della risorsa.In this case, because we specified "type": "User", this permission can be consented to by any account authenticated by the Azure AD tenant in which the resource/API application is registered. In questo modo, viene concessa all'applicazione client l'autorizzazione ad accedervi per conto dell'account.This grants the client application permission to access it on the account's behalf. Le stringhe del nome visualizzato e della descrizione vengono usate durante il processo di consenso e per la visualizzazione nel portale di Azure.The description and display name strings are used during consent and for display in the Azure portal.

  7. Dopo aver terminato l'aggiornamento del manifesto, fare clic su Salva per salvare il manifesto.When you're finished updating the manifest, click Save to save the manifest.

Dopo aver salvato il manifesto, è possibile concedere all'applicazione client registrata l'accesso alla nuova autorizzazione aggiunta in precedenza.Now that the manifest is saved, you can give a registered client application access to the new permission we added above. Questa volta è possibile usare l'interfaccia utente Web del portale di Azure invece di modificare il manifesto dell'applicazione client:This time you can use the Azure portal's Web UI instead of editing the client application's manifest:

  1. Accedere prima di tutto al pannello Impostazioni dell'applicazione client a cui si desidera aggiungere l'accesso alla nuova API, fare clic su Autorizzazioni necessarie e scegliere Selezionare un'API.First go to the Settings blade of the client application to which you wish to add access to the new API, click Required Permissions and choose Select an API.
  2. Verrà quindi visualizzato l'elenco delle applicazioni della risorsa registrate (API) nel tenant.Then you will be presented with the list of registered resource applications (APIs) in the tenant. Fare clic sull'applicazione della risorsa per selezionarla o digitare il nome dell'applicazione nella casella di ricerca.Click the resource application to select it, or type the name of the application the search box. Dopo avere individuato l'applicazione, fare clic su Seleziona.When you've found the application, click Select.
  3. Verrà visualizzata la pagina Autorizzazioni selezionare che consente di visualizzare l'elenco delle autorizzazioni per l'applicazione e delle autorizzazioni delegate disponibili per l'applicazione della risorsa.This will take you to the Select Permissions page, which will show the list of Application Permissions and Delegated Permissions available for the resource application. Selezionare la nuova autorizzazione per aggiungerla all'elenco delle autorizzazioni richieste dal client.Select the new permission in order to add it to the client's requested list of permissions. La nuova autorizzazione verrà archiviata nella configurazione dell'identità dell'applicazione client, nella proprietà della raccolta "requiredResourceAccess".This new permission will be stored in the client application's identity configuration, in the "requiredResourceAccess" collection property.

È tutto.That's it. Ora le applicazioni verranno eseguite usando la nuova configurazione dell'identità.Now your applications will run using their new identity configuration.

Passaggi successiviNext steps

La sezione dei commenti di seguito consente di fornire commenti e suggerimenti utili per migliorare e organizzare i contenuti disponibili.Please use the comments section below to provide feedback and help us refine and shape our content.