Microsoft Entra app manifest (Azure AD Graph format)

บทความ
09/27/2024

The application manifest contains a definition of all the attributes of an application object in the Microsoft identity platform. It also serves as a mechanism for updating the application object. For more info on the Application entity and its schema, see the Graph API Application entity documentation.

You can configure an app's attributes through the Microsoft Entra admin center or programmatically using Microsoft Graph API or Microsoft Graph PowerShell SDK. However, there are some scenarios where you need to edit the app manifest to configure an app's attribute. These scenarios include:

If you registered the app as Microsoft Entra multitenant and personal Microsoft accounts, you can't change the supported Microsoft accounts in the UI. Instead, you must use the application manifest editor to change the supported account type.
To define permissions and roles that your app supports, you must modify the application manifest.

Configure the app manifest

To configure the application manifest:

Sign in to the Microsoft Entra admin center as at least an Application Developer.
Browse to Identity > Applications > App registrations.
Select the app you want to configure.
From the app's Manage section, select Manifest. A web-based manifest editor opens, allowing you to edit the manifest. Optionally, you can select Download to edit the manifest locally, and then use Upload to reapply it to your application.

Manifest reference

This section describes the attributes found in the application manifest.

id attribute

Key	Value type
id	String

The unique identifier for the app in the directory. This ID is not the identifier used to identify the app in any protocol transaction. Use it for the referencing the object in directory queries.

Example:

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

acceptMappedClaims attribute

Key	Value type
acceptMappedClaims	Nullable Boolean

As documented on the apiApplication resource type, this allows an application to use claims mapping without specifying a custom signing key. Applications that receive tokens rely on the fact that the claim values are authoritatively issued by Microsoft Entra ID and cannot be tampered with. However, when you modify the token contents through claims-mapping policies, these assumptions may no longer be correct. Applications must explicitly acknowledge that tokens have been modified by the creator of the claims-mapping policy to protect themselves from claims-mapping policies created by malicious actors.

Warning

Do not set acceptMappedClaims property to true for multi-tenant apps, which can allow malicious actors to create claims-mapping policies for your app.

Example:

    "acceptMappedClaims": true,

accessTokenAcceptedVersion attribute

Key	Value type
accessTokenAcceptedVersion	Nullable Int32

Specifies the access token version expected by the resource. This parameter changes the version and format of the JWT produced independent of the endpoint or client used to request the access token.

The endpoint used, v1.0 or v2.0, is chosen by the client and only impacts the version of id_tokens. Resources need to explicitly configure accesstokenAcceptedVersion to indicate the supported access token format.

Possible values for accesstokenAcceptedVersion are 1, 2, or null. If the value is null, this parameter defaults to 1, which corresponds to the v1.0 endpoint.

If signInAudience is AzureADandPersonalMicrosoftAccount, the value must be 2.

Example:

    "accessTokenAcceptedVersion": 2,

addIns attribute

Key	Value type
addIns	Collection

Defines custom behavior that a consuming service can use to call an app in specific contexts. For example, applications that can render file streams may set the addIns property for its "FileHandler" functionality. This parameter lets services like Microsoft 365 call the application in the context of a document the user is working on.

Example:

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

allowPublicClient attribute

Key	Value type
allowPublicClient	Boolean

Specifies the fallback application type. Microsoft Entra ID infers the application type from the replyUrlsWithType by default. There are certain scenarios where Microsoft Entra ID can't determine the client app type. For example, one such scenario is the ROPC flow where HTTP request happens without a URL redirection). In those cases, Microsoft Entra ID interprets the application type based on the value of this property. If this value is set to true the fallback application type is set as public client, such as an installed app running on a mobile device. The default value is false, which means the fallback application type is confidential client such as web app.

Example:

    "allowPublicClient": false,

appId attribute

Key	Value type
appId	String

Specifies the unique identifier for the app that is assigned to an app by Microsoft Entra ID.

Example:

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

appRoles attribute

Key	Value type
appRoles	Collection

Specifies the collection of roles that an app may declare. These roles can be assigned to users, groups, or service principals. For more examples and info, see Add app roles in your application and receive them in the token.

Example:

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

errorUrl attribute

Key	Value type
errorUrl	String

Unsupported.

groupMembershipClaims attribute

Key	Value type
groupMembershipClaims	String

Configures the groups claim issued in a user or OAuth 2.0 access token that the app expects. To set this attribute, use one of the following valid string values:

"None"
"SecurityGroup" (for security groups and Microsoft Entra roles)
"ApplicationGroup" (this option includes only groups that are assigned to the application)
"DirectoryRole" (gets the Microsoft Entra directory roles the user is a member of)
"All" (this gets all of the security groups, distribution groups, and Microsoft Entra directory roles that the signed-in user is a member of).

Example:

    "groupMembershipClaims": "SecurityGroup",

optionalClaims attribute

Key	Value type
optionalClaims	String

The optional claims returned in the token by the security token service for this specific app.

Apps that support both personal accounts and Microsoft Entra ID can't use optional claims. However, apps registered for just Microsoft Entra ID using the v2.0 endpoint can get the optional claims they requested in the manifest. For more info, see Optional claims.

Example:

    "optionalClaims": null,

identifierUris attribute

Key	Value type
identifierUris	String Array

User-defined URIs that uniquely identify a web app within its Microsoft Entra tenant or verified customer owned domain. When an application is used as a resource app, the identifierUri value is used to uniquely identify and access the resource. For a public client application it cannot have value for identifierUris.

The following API and HTTP scheme-based application ID URI formats are supported. Replace the placeholder values as described in the list following the table.

Supported application ID URI formats	Example app ID URIs
api://<appId>	api://00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<appId>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<string>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
api://<string>/<appId>	api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444
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> - The application identifier (appId) property of the application object.
<string> - The string value for the host or the api path segment.
<tenantId> - A GUID generated by Azure to represent the tenant within Azure.
<tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com, where <tenantInitialDomain> is the initial domain name the tenant creator specified at tenant creation.
<verifiedCustomDomain> - A verified custom domain configured for your Microsoft Entra tenant.

Note

If you use the api:// scheme, you add a string value directly after the "api://". For example, api://<string>. That string value can be a GUID or an arbitrary string. If you add a GUID value, it must match either the app ID or the tenant ID. The application ID URI value must be unique for your tenant. If you add api://<tenantId> as the application ID URI, no one else will be able to use that URI in any other app. The recommendation is to use api://<appId>, instead, or the HTTP scheme.

Important

The application ID URI value must not end with a slash "/" character.

Example:

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

informationalUrls attribute

Key	Value type
informationalUrls	String

Specifies the links to the app's terms of service and privacy statement. The terms of service and privacy statement are surfaced to users through the user consent experience. For more info, see How to: Add Terms of service and privacy statement for registered Microsoft Entra apps.

Example:

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

keyCredentials attribute

Key	Value type
keyCredentials	Collection

Holds references to app-assigned credentials, string-based shared secrets and X.509 certificates. These credentials are used when requesting access tokens (when the app is acting as a client rather that as a resource).

Example:

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

knownClientApplications attribute

Key	Value type
knownClientApplications	String Array

Used for bundling consent if you have a solution that contains two parts: a client app and a custom web API app. If you enter the appID of the client app into this value, the user will only have to consent once to the client app. Microsoft Entra ID will know that consenting to the client means implicitly consenting to the web API. It automatically provisions service principals for both the client and web API at the same time. Both the client and the web API app must be registered in the same tenant.

Example:

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

logoUrl attribute

Key	Value type
logoUrl	String

Read only value that points to the CDN URL to logo that was uploaded.

Example:

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

logoutUrl attribute

Key	Value type
logoutUrl	String

The URL to sign out of the app.

Example:

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

name attribute

Key	Value type
name	String

The display name for the app.

Example:

    "name": "MyRegisteredApp",

oauth2AllowImplicitFlow attribute

Key	Value type
oauth2AllowImplicitFlow	Boolean

Specifies whether this web app can request OAuth2.0 implicit flow access tokens. The default is false. This flag is used for browser-based apps, like JavaScript single-page apps. To learn more, enter OAuth 2.0 implicit grant flow in the table of contents and see the topics about implicit flow. We, however, discourage the use of implicit grant even in SPAs and recommend using the authorization code flow with PKCE.

Example:

    "oauth2AllowImplicitFlow": false,

oauth2AllowIdTokenImplicitFlow attribute

Key	Value type
oauth2AllowIdTokenImplicitFlow	Boolean

Specifies whether this web app can request OAuth2.0 implicit flow ID tokens. The default is false. This flag is used for browser-based apps, like JavaScript single-page apps. We, however, discourage the use of implicit grant even in SPAs and recommend using the authorization code flow with PKCE.

Example:

    "oauth2AllowIdTokenImplicitFlow": false,

oauth2Permissions attribute

Key	Value type
oauth2Permissions	Collection

Specifies the collection of OAuth 2.0 permission scopes that the web API (resource) app exposes to client apps. These permission scopes may be granted to client apps during consent.

Example:

    "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"
        }
    ],

oauth2RequiredPostResponse attribute

Key	Value type
oauth2RequiredPostResponse	Boolean

Specifies whether, as part of OAuth 2.0 token requests, Microsoft Entra ID will allow POST requests, as opposed to GET requests. The default is false, which specifies that only GET requests are allowed.

Example:

    "oauth2RequirePostResponse": false,

parentalControlSettings attribute

Key	Value type
parentalControlSettings	String

countriesBlockedForMinors specifies the countries/regions in which the app is blocked for minors.
legalAgeGroupRule specifies the legal age group rule that applies to users of the app. Can be set to Allow, RequireConsentForPrivacyServices, RequireConsentForMinors, RequireConsentForKids, or BlockMinors.

Example:

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

passwordCredentials attribute

Key	Value type
passwordCredentials	Collection

See the description for the keyCredentials property.

Example:

    "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"
      }
    ],

preAuthorizedApplications attribute

Key	Value type
preAuthorizedApplications	Collection

Lists applications and requested permissions for implicit consent. Requires an admin to provide consent to the application. preAuthorizedApplications do not require the user to consent to the requested permissions. Permissions listed in preAuthorizedApplications do not require user consent. However, any additional requested permissions not listed in preAuthorizedApplications require user consent.

Example:

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

publisherDomain attribute

Key	Value type
publisherDomain	String

The verified publisher domain for the application. Read-only.

Example:

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

replyUrlsWithType attribute

Key	Value type
replyUrlsWithType	Collection

This multi-value property holds the list of registered redirect_uri values that Microsoft Entra ID accepts as destinations when returning tokens. Each URI value should contain an associated app type value. Supported type values are:

Web
InstalledClient
Spa

To learn more, see replyUrl restrictions and limitations.

Example:

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

requiredResourceAccess attribute

Key	Value type
requiredResourceAccess	Collection

With dynamic consent, requiredResourceAccess drives the admin consent experience and the user consent experience for users who are using static consent. However, this parameter doesn't drive the user consent experience for the general case.

resourceAppId is the unique identifier for the resource that the app requires access to. This value should be equal to the appId declared on the target resource app.
resourceAccess is an array that lists the OAuth2.0 permission scopes and app roles that the app requires from the specified resource. Contains the id and type values of the specified resources.

Example:

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

samlMetadataUrl attribute

Key	Value type
samlMetadataUrl	String

The URL to the SAML metadata for the app.

Example:

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

signInUrl attribute

Key	Value type
signInUrl	String

Specifies the URL to the app's home page.

Example:

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

signInAudience attribute

Key	Value type
signInAudience	String

Specifies what Microsoft accounts are supported for the current application. Supported values are:

AzureADMyOrg - Users with a Microsoft work or school account in my organization's Microsoft Entra tenant (for example, single tenant)
AzureADMultipleOrgs - Users with a Microsoft work or school account in any organization's Microsoft Entra tenant (for example, multitenant)
AzureADandPersonalMicrosoftAccount - Users with a personal Microsoft account, or a work or school account in any organization's Microsoft Entra tenant
PersonalMicrosoftAccount - Personal accounts that are used to sign in to services like Xbox and Skype.

Example:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

tags attribute

Key	Value type
tags	String Array

Custom strings that can be used to categorize and identify the application.

Example:

    "tags": [
       "ProductionApp"
    ],

Common issues

Manifest limits

An application manifest has multiple attributes that are referred to as collections; for example, appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess, and oauth2Permissions. Within the complete application manifest for any application, the total number of entries in all the collections combined has been capped at 1200. If you previously specify 100 redirect URIs in the application manifest, then you're only left with 1,100 remaining entries to use across all other collections combined that make up the manifest.

Note

In case you try to add more than 1200 entries in the application manifest, you may see an error "Failed to update application xxxxxx. Error details: The size of the manifest has exceeded its limit. Please reduce the number of values and retry your request."

Unsupported attributes

The application manifest represents the schema of the underlying application model in Microsoft Entra ID. As the underlying schema evolves, the manifest editor is updated to reflect the new schema from time to time. As a result, you may notice new attributes showing up in the application manifest. In rare occasions, you may notice a syntactic or semantic change in the existing attributes or you may find an attribute that existed previously aren't supported anymore. For example, you'll see new attributes in the App registrations, which are known with a different name in the App registrations (Legacy) experience.

App registrations (Legacy)	App registrations
`availableToOtherTenants`	`signInAudience`
`displayName`	`name`
`errorUrl`	-
`homepage`	`signInUrl`
`objectId`	`Id`
`publicClient`	`allowPublicClient`
`replyUrls`	`replyUrlsWithType`

For descriptions for these attributes, see the manifest reference section.

When you try to upload a previously downloaded manifest, you may see one of the following errors. This error is likely because the manifest editor now supports a newer version of the schema, which doesn't match with the one you're trying to upload.

"Failed to update xxxxxx application. Error detail: Invalid object identifier 'undefined'. []."
"Failed to update xxxxxx application. Error detail: One or more property values specified are invalid. []."
"Failed to update xxxxxx application. Error detail: Not allowed to set availableToOtherTenants in this api version for update. []."
"Failed to update xxxxxx application. Error detail: Updates to 'replyUrls' property isn't allowed for this application. Use 'replyUrlsWithType' property instead. []."
"Failed to update xxxxxx application. Error detail: A value without a type name was found and no expected type is available. When the model is specified, each value in the payload must have a type that can be either specified in the payload, explicitly by the caller or implicitly inferred from the parent value. []"

When you see one of these errors, we recommend the following actions:

Edit the attributes individually in the manifest editor instead of uploading a previously downloaded manifest. Use the manifest reference table to understand the syntax and semantics of old and new attributes so that you can successfully edit the attributes you're interested in.
If your workflow requires you to save the manifests in your source repository for use later, we suggest rebasing the saved manifests in your repository with the one you see in the App registrations experience.

Next steps

For more information on the relationship between an app's application and service principal objects, see Application and service principal objects in Microsoft Entra ID.
See the Microsoft identity platform developer glossary for definitions of some core Microsoft identity platform developer concepts.

Use the following comments section to provide feedback that helps refine and shape our content.

แชร์ผ่าน

Microsoft Entra app manifest (Azure AD Graph format)

Configure the app manifest

Manifest reference

id attribute

acceptMappedClaims attribute

accessTokenAcceptedVersion attribute

addIns attribute

allowPublicClient attribute

appId attribute

appRoles attribute

errorUrl attribute

groupMembershipClaims attribute

optionalClaims attribute

identifierUris attribute

informationalUrls attribute

keyCredentials attribute

knownClientApplications attribute

logoUrl attribute

logoutUrl attribute

name attribute

oauth2AllowImplicitFlow attribute

oauth2AllowIdTokenImplicitFlow attribute

oauth2Permissions attribute

oauth2RequiredPostResponse attribute

parentalControlSettings attribute

passwordCredentials attribute

preAuthorizedApplications attribute

publisherDomain attribute

replyUrlsWithType attribute

requiredResourceAccess attribute

samlMetadataUrl attribute

signInUrl attribute

signInAudience attribute

tags attribute

Common issues

Manifest limits

Unsupported attributes

Next steps

คำติชม

แหล่งทรัพยากรเพิ่มเติม