Manifesto dell'app Microsoft Entra

  • Articolo

Il manifesto dell'applicazione contiene una definizione di tutti gli attributi di un oggetto applicazione in Microsoft Identity Platform. Funge inoltre da meccanismo per laggiornamento dell'oggetto applicazione. Per altre informazioni sull'entità applicazione e il relativo schema, vedere la documentazione sull'entità applicazione dell'API Graph.

È possibile configurare gli attributi di un'app tramite l'interfaccia di amministrazione di Microsoft Entra o a livello di codice usando l'API Microsoft Graph o Microsoft Graph PowerShell SDK. Esistono tuttavia alcuni scenari in cui è necessario modificare il manifesto dell'app per configurare l'attributo di un'app. Questi scenari sono:

  • Se l'app è stata registrata come account Microsoft Entra multi-tenant e microsoft personali, non è possibile modificare gli account Microsoft supportati nell'interfaccia utente. Per modificare i tipi di account supportati è necessario usare l'editor del manifesto dell'applicazione.
  • Per definire autorizzazioni e ruoli supportati dall'app, è necessario modificare il manifesto dell'applicazione.

Configurare il manifesto dell'applicazione

Per configurare il manifesto dell'applicazione:

  1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno uno sviluppatore di applicazioni.
  2. Passare a Applicazioni> di identità>Registrazioni app.
  3. Selezionare l'applicazione da configurare.
  4. Nella pagina Panoramica dell'app selezionare la sezione Manifesto. Verrà aperto un editor manifesto basato sul Web che consente di modificare il manifesto. Facoltativamente è possibile selezionare Scarica, modificare il manifesto in locale e quindi usare Carica per riapplicarlo all'applicazione.

Riferimento del manifesto

Questa sezione descrive gli attributi trovati nel manifesto dell'applicazione.

Attributo id

Chiave Tipo di valore
id String

Identificatore univoco per l'app nella directory. Questo ID non è l'identificatore usato per identificare l'app nelle transazioni di protocollo. Usarlo per fare riferimento all'oggetto nelle query di directory.

Esempio:

    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",

attributo acceptMappedClaims

Chiave Tipo di valore
acceptMappedClaims Valore booleano nullable

Come documentato nel apiApplication tipo di risorsa, questo consente a un'applicazione di usare il mapping delle attestazioni senza specificare una chiave di firma personalizzata. Le applicazioni che ricevono token si basano sul fatto che i valori dell'attestazione vengono emessi in modo autorevole da Microsoft Entra ID e non possono essere manomessi. Tuttavia, quando si modifica il contenuto del token tramite criteri di mapping delle attestazioni, questi presupposti potrebbero non essere più corretti. Le applicazioni devono riconoscere in modo esplicito che i token sono stati modificati dall'autore dei criteri di mapping delle attestazioni per proteggersi dai criteri di mapping delle attestazioni creati da attori malintenzionati.

Avviso

Non impostare la acceptMappedClaims proprietà su true per le app multi-tenant, che possono consentire agli attori malintenzionati di creare criteri di mapping delle attestazioni per l'app.

Esempio:

    "acceptMappedClaims": true,

Attributo accessTokenAcceptedVersion

Chiave Tipo di valore
accessTokenAcceptedVersion Nullable Int32

Specifica la versione del token di accesso prevista dalla risorsa. Questo parametro modifica la versione e il formato del token JWT generato indipendentemente dall'endpoint o dal client usato per richiedere il token di accesso.

L'endpoint usato, v1.0 o v2.0, viene scelto dal client e influisce solo sulla versione di id_tokens. Le risorse devono configurare in modo esplicito accesstokenAcceptedVersion per indicare il formato di token di accesso supportato.

I valori possibili per accesstokenAcceptedVersion sono 1, 2 o Null. Se il valore è Null, il parametro usa l'impostazione predefinita 1 che corrisponde all'endpoint v1.0.

Se signInAudience è AzureADandPersonalMicrosoftAccount, il valore deve essere 2.

Esempio:

    "accessTokenAcceptedVersion": 2,

Attributo addIns

Chiave Tipo di valore
addIns Raccolta

Definisce il comportamento personalizzato che un servizio consumer può usare per chiamare un'app in contesti specifici. Ad esempio, le applicazioni in grado di eseguire il rendering di flussi di file possono impostare la proprietà addIns per la relativa funzionalità "FileHandler". Questo parametro consente ai servizi come Microsoft 365 di chiamare l'applicazione nel contesto di un documento su cui l'utente sta lavorando.

Esempio:

    "addIns": [
       {
        "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "type":" FileHandler",
        "properties": [
           {
              "key": "version",
              "value": "2"
           }
        ]
       }
    ],

Attributo allowPublicClient

Chiave Tipo di valore
allowPublicClient Booleano

Specifica il tipo di applicazione di fallback. L'ID Microsoft Entra deduce il tipo di applicazione da replyUrlsWithType per impostazione predefinita. Esistono alcuni scenari in cui Microsoft Entra ID non è in grado di determinare il tipo di app client. Ad esempio, uno scenario di questo tipo è il flusso ROPC in cui si verifica la richiesta HTTP senza un reindirizzamento URL. In questi casi, Microsoft Entra ID interpreta il tipo di applicazione in base al valore di questa proprietà. Se questo valore è impostato su true, il tipo di applicazione di fallback è impostato come client pubblico, ad esempio un'app installata in esecuzione in un dispositivo mobile. Il valore predefinito è false, il che significa che il tipo di applicazione di fallback è un client riservato, ad esempio l'app Web.

Esempio:

    "allowPublicClient": false,

Attributo appId

Chiave Tipo di valore
appId String

Specifica l'identificatore univoco per l'app assegnata a un'app dall'ID Microsoft Entra.

Esempio:

    "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",

Attributo appRoles

Chiave Tipo di valore
appRoles Raccolta

Specifica la raccolta di ruoli che un'app può dichiarare. Questi ruoli possono essere assegnati a utenti, gruppi o entità servizio. Per altri esempi e informazioni, vedere Aggiungere ruoli dell'app in un'applicazione e riceverli nel token.

Esempio:

    "appRoles": [
        {
           "allowedMemberTypes": [
               "User"
           ],
           "description": "Read-only access to device information",
           "displayName": "Read Only",
           "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
           "isEnabled": true,
           "value": "ReadOnly"
        }
    ],

Attributo errorUrl

Chiave Tipo di valore
errorUrl String

Non supportato.

Attributo groupMembershipClaims

Chiave Tipo di valore
groupMembershipClaims String

Configura l'attestazione groups rilasciata in un token di accesso utente oppure OAuth 2.0 previsto dall'app. Per impostare questo attributo, usare uno dei seguenti valori di stringa validi:

  • "None"
  • "SecurityGroup" (per i gruppi di sicurezza e i ruoli di Microsoft Entra)
  • "ApplicationGroup" Questa opzione include solo i gruppi assegnati all'applicazione.
  • "DirectoryRole" (ottiene i ruoli della directory Microsoft Entra di cui l'utente è membro)
  • "All" In questo modo verranno visualizzati tutti i gruppi di sicurezza, i gruppi di distribuzione e i ruoli della directory Microsoft Entra di cui l'utente connesso è membro.

Esempio:

    "groupMembershipClaims": "SecurityGroup",

Attributo optionalClaims

Chiave Tipo di valore
optionalClaims String

Le attestazioni facoltative restituite nel token dal servizio token di sicurezza per questa specifica app.

Le app che supportano sia gli account personali che l'ID Microsoft Entra non possono usare attestazioni facoltative. Tuttavia, le app registrate solo per l'ID Microsoft Entra usando l'endpoint v2.0 possono ottenere le attestazioni facoltative richieste nel manifesto. Per altre informazioni, vedere Attestazioni facoltative.

Esempio:

    "optionalClaims": null,

Attributo identifierUris

Chiave Tipo di valore
identifierUris String Array

URI definiti dall'utente che identificano in modo univoco un'app Web all'interno del tenant di Microsoft Entra o il dominio di proprietà del cliente verificato. Quando un'applicazione viene usata come app per le risorse, il valore identifierUri viene usato per identificare e accedere in modo univoco alla risorsa.

Sono supportati i formati URI DELL'ID applicazione e dell'API seguenti basati sullo schema HTTP. Sostituire i valori segnaposto come descritto nell'elenco che segue la tabella.

ID applicazione supportato
Formati URI		 URI ID app di esempio
<api:// appId> api://fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed
<api:// tenantId>/<appId> api://a8573488-ff46-450a-b09a-6eca0c6a02dc/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed
<api:// tenantId>/<string> api://a8573488-ff46-450a-b09a-6eca0c6a02dc/api
<api:// string>/<appId> api://productapi/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed
<https:// tenantInitialDomain.onmicrosoft.com/>< string> https://contoso.onmicrosoft.com/productsapi
<https:// verifiedCustomDomain>/<string> https://contoso.com/productsapi
<https:// string>.<verifiedCustomDomain> https://product.contoso.com
<https:// string>.<verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
  • <appId> : proprietà dell'identificatore dell'applicazione (appId) dell'oggetto applicazione.
  • <string> : valore stringa per l'host o il segmento di percorso api.
  • <tenantId> : GUID generato da Azure per rappresentare il tenant in Azure.
  • <tenantInitialDomain> - <tenantInitialDomain.onmicrosoft.com>, dove< tenantInitialDomain> è il nome di dominio iniziale specificato dall'autore del tenant durante la creazione del tenant.
  • <verifiedCustomDomain> : dominio personalizzato verificato configurato per il tenant di Microsoft Entra.

Nota

Se si usa lo schema di api:// , aggiungere un valore stringa direttamente dopo "api://". Ad esempio, api://< string>. Tale valore stringa può essere un GUID o una stringa arbitraria. Se si aggiunge un valore GUID, deve corrispondere all'ID app o all'ID tenant. Il valore URI ID applicazione deve essere univoco per il tenant. Se si aggiunge api://< tenantId> come URI ID applicazione, nessun altro potrà usare tale URI in qualsiasi altra app. È consigliabile usare api://< appId>, invece, o lo schema HTTP.

Importante

Il valore URI ID applicazione non deve terminare con una barra "/".

Esempio:

    "identifierUris": "https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444",

Attributo informationalUrls

Chiave Tipo di valore
informationalUrls String

Specifica i collegamenti alle condizioni d'uso del servizio e all'informativa sulla privacy dell'app. Le condizioni per l'utilizzo del servizio e l'informativa sulla privacy vengono presentate agli utenti tramite l'esperienza di consenso dell'utente Per altre info, vedi Procedura: Aggiungere le condizioni per il servizio e l'informativa sulla privacy per le app Microsoft Entra registrate.

Esempio:

    "informationalUrls": {
        "termsOfService": "https://MyRegisteredApp/termsofservice",
        "support": "https://MyRegisteredApp/support",
        "privacy": "https://MyRegisteredApp/privacystatement",
        "marketing": "https://MyRegisteredApp/marketing"
    },

Attributo keyCredentials

Chiave Tipo di valore
keyCredentials Raccolta

Contiene riferimenti a credenziali assegnate dall'app, segreti condivisi basati su stringa e certificati X.509. Queste credenziali vengono usate in fase di richiesta dei token di accesso (quando l'app funge da client, anziché da risorsa).

Esempio:

    "keyCredentials": [
        {
           "customKeyIdentifier":null,
           "endDateTime":"2018-09-13T00:00:00Z",
           "keyId":"<guid>",
           "startDateTime":"2017-09-12T00:00:00Z",
           "type":"AsymmetricX509Cert",
           "usage":"Verify",
           "value":null
        }
    ],

Attributo knownClientApplications

Chiave Tipo di valore
knownClientApplications String Array

Viene usato per unire il consenso se una soluzione contiene due parti, un'app client e un'app API Web personalizzata. Se si immette l'appID dell'app client in questo valore, l'utente deve fornire il consenso solo una volta per l'app client. Microsoft Entra ID saprà che il consenso al client implica il consenso implicito all'API Web. Esegue automaticamente il provisioning delle entità servizio sia per il client che per l'API Web contemporaneamente. Sia il client sia l'app dell'API Web devono essere registrati nello stesso tenant.

Esempio:

    "knownClientApplications": ["00001111-aaaa-2222-bbbb-3333cccc4444"],

Attributo logoUrl

Chiave Tipo di valore
logoUrl String

Valore di sola lettura che punta all'URL rete CDN al logo caricato.

Esempio:

    "logoUrl": "https://MyRegisteredAppLogo",

Attributo logoutUrl

Chiave Tipo di valore
logoutUrl String

URL per disconnettersi dall'app.

Esempio:

    "logoutUrl": "https://MyRegisteredAppLogout",

Attributo name

Chiave Tipo di valore
name string

Nome visualizzato dell'app.

Esempio:

    "name": "MyRegisteredApp",

Attributo oauth2AllowImplicitFlow

Chiave Tipo di valore
oauth2AllowImplicitFlow Booleano

Specifica se questa app Web può richiedere token di accesso di flusso implicito OAuth 2.0. L'impostazione predefinita è false. Questo flag viene usato per le app basate su browser, ad esempio le app JavaScript a pagina singola. Per altre informazioni, immettere OAuth 2.0 implicit grant flow nel sommario e vedere gli argomenti sul flusso implicito.

Esempio:

    "oauth2AllowImplicitFlow": false,

Attributo oauth2AllowIdTokenImplicitFlow

Chiave Tipo di valore
oauth2AllowIdTokenImplicitFlow Booleano

Specifica se questa app Web può richiedere token ID flusso implicito OAuth 2.0. L'impostazione predefinita è false. Questo flag viene usato per le app basate su browser, ad esempio le app JavaScript a pagina singola.

Esempio:

    "oauth2AllowIdTokenImplicitFlow": false,

Attributo oauth2Permissions

Chiave Tipo di valore
oauth2Permissions Raccolta

Specifica la raccolta di ambiti di autorizzazione OAuth 2.0 che l'app dell'API Web (risorsa) espone alle app client. Questi ambiti di autorizzazione possono essere concessi alle app client durante il consenso.

Esempio:

    "oauth2Permissions": [
       {
          "adminConsentDescription": "Allow the app to access resources on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access resource1",
          "id": "<guid>",
          "isEnabled": true,
          "type": "User",
          "userConsentDescription": "Allow the app to access resource1 on your behalf.",
          "userConsentDisplayName": "Access resources",
          "value": "user_impersonation"
        }
    ],

Attributo oauth2RequiredPostResponse

Chiave Tipo di valore
oauth2RequiredPostResponse Booleano

Specifica se, come parte delle richieste di token OAuth 2.0, Microsoft Entra ID consentirà le richieste POST, anziché le richieste GET. Il valore predefinito è false, che specifica che sono consentite solo le richieste GET.

Esempio:

    "oauth2RequirePostResponse": false,

Attributo parentalControlSettings

Chiave Tipo di valore
parentalControlSettings String
  • countriesBlockedForMinors specifica i paesi e le aree in cui l'app è bloccata per i minori.
  • legalAgeGroupRule specifica la regola gruppo relativa all'età legale che si applica agli utenti dell'app. Può essere impostata su Allow, RequireConsentForPrivacyServices, RequireConsentForMinors, RequireConsentForKids o BlockMinors.

Esempio:

    "parentalControlSettings": {
        "countriesBlockedForMinors": [],
        "legalAgeGroupRule": "Allow"
    },

Attributo passwordCredentials

Chiave Tipo di valore
passwordCredentials Raccolta

Vedere la descrizione per la proprietà keyCredentials.

Esempio:

    "passwordCredentials": [
      {
        "customKeyIdentifier": null,
        "displayName": "Generated by App Service",
        "endDateTime": "2022-10-19T17:59:59.6521653Z",
        "hint": "Nsn",
        "keyId": "<guid>",
        "secretText": null,        
        "startDateTime":"2022-10-19T17:59:59.6521653Z"
      }
    ],

Attributo preAuthorizedApplications

Chiave Tipo di valore
preAuthorizedApplications Raccolta

Elenca le applicazioni e le autorizzazioni necessarie per il consenso implicito. Richiede a un amministratore di fornire il consenso all'applicazione. preAuthorizedApplications non richiede il consenso utente alle autorizzazioni richieste. Le autorizzazioni elencate in preAuthorizedApplications non richiedono il consenso utente. Tuttavia, le autorizzazioni richieste aggiuntive non elencate in preAuthorizedApplications richiedono il consenso utente.

Esempio:

    "preAuthorizedApplications": [
       {
          "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "permissionIds": [
             "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
            ]
        }
    ],

Attributo publisherDomain

Chiave Tipo di valore
publisherDomain String

Dominio del server di pubblicazione verificato per l'applicazione. Sola lettura.

Esempio:

    "publisherDomain": "{tenant}.onmicrosoft.com",

Attributo replyUrlsWithType

Chiave Tipo di valore
replyUrlsWithType Raccolta

Questa proprietà multivalore contiene l'elenco dei valori di redirect_uri registrati che l'ID di Microsoft Entra accetterà come destinazioni durante la restituzione dei token. Ogni valore di URI deve contenere un valore per il tipo di app associato. I valori supportati sono:

  • Web
  • InstalledClient
  • Spa

Per altre informazioni, vedere Restrizioni e limitazioni di replyUrl.

Esempio:

    "replyUrlsWithType": [
       {
          "url": "https://localhost:4400/services/office365/redirectTarget.html",
          "type": "InstalledClient"
       }
    ],

Attributo requiredResourceAccess

Chiave Tipo di valore
requiredResourceAccess Raccolta

Con il consenso dinamico, requiredResourceAccess attiva l'esperienza di consenso dell'amministratore e l'esperienza di consenso dell'utente per gli utenti che usano il consenso statico. Questo parametro non attiva, tuttavia, l'esperienza di consenso dell'utente per i casi generici.

  • resourceAppId è l'identificatore univoco per la risorsa a cui l'app richiede l'accesso. Questo valore deve essere uguale all'appId dichiarato nell'app della risorsa di destinazione.
  • resourceAccess è una matrice che contiene l'elenco dei ruoli delle app e degli ambiti delle autorizzazioni OAuth 2.0 che l'app richiede dalla risorsa specificata. Contiene i valori di tipo id e type per le risorse specificate.

Esempio:

    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
                    "type": "Scope"
                }
            ]
        }
    ],

Attributo samlMetadataUrl

Chiave Tipo di valore
samlMetadataUrl String

URL dei metadati SAML per l'app.

Esempio:

    "samlMetadataUrl": "https://MyRegisteredAppSAMLMetadata",

Attributo signInUrl

Chiave Tipo di valore
signInUrl String

Specifica l'URL della home page dell'app.

Esempio:

    "signInUrl": "https://MyRegisteredApp",

Attributo signInAudience

Chiave Tipo di valore
signInAudience String

Specifica gli account Microsoft supportati per l'applicazione corrente. I valori supportati sono:

  • AzureADMyOrg - Utenti con un account microsoft aziendale o dell'istituto di istruzione nel tenant di Microsoft Entra dell'organizzazione (ad esempio, tenant singolo)
  • AzureADMultipleOrgs - Utenti con un account microsoft aziendale o dell'istituto di istruzione nel tenant di Microsoft Entra di qualsiasi organizzazione (ad esempio, multi-tenant)
  • AzureADandPersonalMicrosoftAccount - Utenti con un account Microsoft personale o un account aziendale o dell'istituto di istruzione nel tenant Microsoft Entra di qualsiasi organizzazione
  • PersonalMicrosoftAccount: account personali usati per accedere a servizi quali Xbox e Skype.

Esempio:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

Attributo tags

Chiave Tipo di valore
tag String Array

Stringhe personalizzate che possono essere usate per classificare e identificare l'applicazione.

Esempio:

    "tags": [
       "ProductionApp"
    ],

Problemi comuni

Limiti del manifesto

Un manifesto dell'applicazione ha più attributi detti raccolte, ad esempio appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess e oauth2Permissions. All'interno del manifesto dell'applicazione completo per qualsiasi applicazione, il numero totale di voci in tutte le raccolte combinate è stato limitato a 1200. Se si specificano 100 URI di reindirizzamento nel manifesto dell'applicazione, rimarranno solo 1100 voci da usare in tutte le altre raccolte combinate che compongono il manifesto.

Nota

Se si tenta di aggiungere più di 1200 voci nel manifesto dell'applicazione, potrebbe essere visualizzato un errore "Impossibile aggiornare l'applicazione xxxxxx. Dettagli errore: la dimensione del manifesto ha superato il limite. Ridurre il numero di valori e ripetere la richiesta."

Attributi non supportati

Il manifesto dell'applicazione rappresenta lo schema del modello di applicazione sottostante in Microsoft Entra ID. Con l'evolversi dello schema sottostante, l'editor del manifesto verrà aggiornato in modo che rifletta il nuovo schema di tanto in tanto. Di conseguenza, è possibile notare che i nuovi attributi vengono visualizzati nel manifesto dell'applicazione. In rare occasioni, è possibile notare una modifica sintattica o semantica negli attributi esistenti oppure è possibile trovare un attributo precedentemente esistente che non è più supportato. Ad esempio, verranno visualizzati nuovi attributi in Registrazioni app, noti con un nome diverso nell'esperienza Registrazioni app (legacy).

Registrazioni app (legacy) Registrazioni app
availableToOtherTenants signInAudience
displayName name
errorUrl -
homepage signInUrl
objectId Id
publicClient allowPublicClient
replyUrls replyUrlsWithType

Per le descrizioni di questi attributi, vedere la sezione Riferimento del manifesto.

Quando si tenta di caricare un manifesto scaricato in precedenza, è possibile che venga visualizzato un errore simile a quelli elencati di seguito. Questo errore è probabilmente dovuto al fatto che l'editor del manifesto supporta ora una versione più recente dello schema, che non corrisponde a quella che si sta provando a caricare.

  • "Non è stato possibile aggiornare l'applicazione xxxxxx. Dettagli errore: identificatore di oggetto non valido 'undefined'. []."
  • "Non è stato possibile aggiornare l'applicazione xxxxxx. Dettagli errore: uno o più valori di proprietà specificati non sono validi. []."
  • "Non è stato possibile aggiornare l'applicazione xxxxxx. Dettagli errore: non è consentito impostare availableToOtherTenants in questa versione dell'API per l'aggiornamento. []."
  • "Non è stato possibile aggiornare l'applicazione xxxxxx. Dettagli errore: Aggiornamenti alla proprietà 'replyUrls' non è consentita per questa applicazione. Usare invece la proprietà 'replyUrlsWithType'. []."
  • "Non è stato possibile aggiornare l'applicazione xxxxxx. Dettagli errore: è stato trovato un valore senza un nome di tipo e non è disponibile alcun tipo previsto. Se il modello è specificato, ogni valore nel payload deve disporre di un tipo che può essere specificato nel payload in modo esplicito dal chiamante o dedotto in modo implicito dal valore padre. []"

Se viene visualizzato uno di questi errori, è consigliabile eseguire le operazioni seguenti:

  1. Modificare gli attributi singolarmente nell'editor del manifesto anziché caricare un manifesto scaricato in precedenza. Usare la tabella in Riferimento del manifesto per comprendere la sintassi e la semantica degli attributi vecchi e nuovi, in modo da poter modificare correttamente gli attributi a cui si è interessati.
  2. Se il flusso di lavoro richiede di salvare i manifesti nel repository di origine per usarli in seguito, è consigliabile riassegnare i manifesti salvati nel repository a quello visualizzato nell'esperienza Registrazioni app.

Passaggi successivi

Usare la sezione dei commenti seguente per offrire commenti e suggerimenti utili per migliorare e organizzare i contenuti disponibili.