Understand the app manifest (Microsoft Graph format)
The application manifest contains all the attributes and their values of an app registration in the Microsoft identity platform.
A Microsoft Graph app manifest is a JSON object that represents an app registration. It's also called the Microsoft Graph Application resource type or Microsoft Graph app object (application object). It contains all the attributes and their values of an app registration.
The application object you receive using Microsoft Graph Get Application method is the same JSON object you see in App Registration manifest page in the Microsoft Entra admin center.
Note
For apps registered with your personal Microsoft account (MSA account), you will continue to see app manifests in Azure AD Graph format in the Microsoft Entra admin center until further notice. For more information, see Microsoft Entra app manifest (Azure AD Graph format).
Configure the Microsoft Graph app manifest
If you would like to configure Microsoft Graph App Manifest programmatically, you can either use Microsoft Graph API or Microsoft Graph PowerShell SDK.
You can also configure the app manifest through the Microsoft Entra admin center. Most attributes can be configured using a UI element in App registrations. However, some attributes need to be configured by editing the app manifest directly in the Manifest page.
Configure the app manifest in the Microsoft Entra admin center
To configure the Microsoft Graph app 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 Overview page, select the Manifest section. 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 Microsoft Graph app manifest.
id attribute
Key | Value type |
---|---|
id | String |
This property is referred to as Object ID in the Microsoft Entra admin center. It's a unique identifier for the application object in the directory.
This ID isn't the identifier used to identify the app in any protocol transaction. It's used for the referencing the object in directory queries.
It's a not nullable and Read-only attribute.
Example:
"id": "f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd",
appId attribute
Key | Value type |
---|---|
appId | String |
This property is referred to as application (client) ID in the Microsoft Entra admin center. It's a unique identifier for the application object in the directory.
This ID is the identifier used to identify the app in any protocol transaction.
It's a not nullable and read-only attribute.
Example:
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
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": "968A844F-7A47-430C-9163-07AE7C31D407",
"type":" FileHandler",
"properties": [
{
"key": "version",
"value": "2"
}
]
}
],
appRoles
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": "00001111-aaaa-2222-bbbb-3333cccc4444",
"isEnabled": true,
"value": "ReadOnly"
}
],
groupMembershipClaims
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":{
"idToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"accessToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"saml2Token": [{"@odata.type": "microsoft.graph.optionalClaim"}]
}
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.
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/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed",
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
}
],
displayName attribute
Key | Value type |
---|---|
displayName | String |
The display name for the app.
Example:
" displayName": "MyRegisteredApp",
oauth2RequiredPostResponse attribute
Key | Value type |
---|---|
oauth2RequiredPostResponse | Boolean |
Specifies whether, as part of OAuth 2.0 token requests, Microsoft Entra ID allows POST requests, as opposed to GET requests. The default is false, which specifies that only GET requests will be 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 toAllow
,RequireConsentForPrivacyServices
,RequireConsentForMinors
,RequireConsentForKids
, orBlockMinors
.
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"
}
],
publisherDomain attribute
Key | Value type |
---|---|
publisherDomain | String |
The verified publisher domain for the application. Read-only. To edit the publisher domain of your app registration, please follow the steps listed in Configure an app's publisher domain.
Example:
"publisherDomain": "{tenant}.onmicrosoft.com",
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 theid
andtype
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",
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 tenantPersonalMicrosoftAccount
- 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.
Individual tags must be between 1 and 256 characters (inclusive). No whitespaces or duplicate tags are allowed. There is no specific limit on the number of tags that can be added, subject to general manifest size limits.
Example:
"tags": [
"ProductionApp"
],
isFallbackPublicClient attribute
Key | Value type |
---|---|
isFallbackPublicClient | Boolean |
Specifies the fallback application type as public client, such as an installed application running on a mobile device. The default value of this attribute is false, which means the fallback application type is confidential client such as a web app. There are certain scenarios where Microsoft Entra ID can't determine the client application type. For example, the ROPC flow where it's configured without specifying a redirect URI. In those cases Microsoft Entra ID interprets the application type based on the value of this property.
Example:
"isFallbackPublicClient ": "false",
info attribute
Key | Value type |
---|---|
info | informationalUrl |
Specifies basic profile information of the application including the app's marketing, support, terms of service, privacy statement and logo URLs.
Note that:
"logoUrl" is a read-only property. You can't edit it in app manifest. Navigate to "branding and property" page in your desired app registration and use "Upload new logo" to upload a new logo.
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:
Info: {
"termsOfService": "https://MyRegisteredApp/termsofservice",
"support": "https://MyRegisteredApp/support",
"privacy": "https://MyRegisteredApp/privacystatement",
"marketing": "https://MyRegisteredApp/marketing"
"logoUrl": "https://MyRegisteredApp/logoUrl",
}
api attribute
Key | Value type |
---|---|
api | apiApplication resource type |
Specifies settings for an application that implements a web API. It includes five properties:
Property | Type | Description |
---|---|---|
acceptMappedClaims | Boolean | When set to true, it 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 can't 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: Don't set acceptMappedClaims property to true for multitenant apps, which can allow malicious actors to create claims-mapping policies for your app. |
knownClientApplications | collection | Used for bundling consent if you have a solution that contains two parts: a client app and a custom web API app. If you set the appID of the client app to this value, the user only consents once to the client app. Microsoft Entra ID knows that consenting to the client means implicitly consenting to the web API and automatically provisions service principals for both APIs at the same time. Both the client and the web API app must be registered in the same tenant. |
oauth2PermissionScopes | permissionScope collection | The definition of the delegated permissions exposed by the web API represented by this application registration. These delegated permissions may be requested by a client application, and may be granted by users or administrators during consent. Delegated permissions are sometimes referred to as OAuth 2.0 scopes. |
preAuthorizedApplications | preAuthorizedApplication collection | Lists the client applications that are preauthorized with the specified delegated permissions to access this application's APIs. Users aren't required to consent to any preauthorized application (for the permissions specified). However, any other permissions not listed in preAuthorizedApplications (requested through incremental consent for example) will require user consent. |
requestedAccessTokenVersion | Int32 | Specifies the access token version expected by this resource. This 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 requestedAccessTokenVersion to indicate the supported access token format. Possible values for requestedAccessTokenVersion are 1, 2, or null. If the value is null, this defaults to 1, which corresponds to the v1.0 endpoint. If signInAudience on the application is configured as AzureADandPersonalMicrosoftAccount or PersonalMicrosoftAccount, the value for this property must be 2. |
Example:
Api:{
"acceptMappedClaims": true,
"knownClientApplications": ["f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd"],
"oauth2PermissionScopes": [
{
"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"
}
],
"preAuthorizedApplications": [{
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"permissionIds": [
"8748f7db-21fe-4c83-8ab5-53033933c8f1"
]
}],
"requestedAccessTokenVersion": 2
}
web attribute
Key | Value type |
---|---|
web | webApplication resource type |
Specifies settings for a web application. It includes four properties.
Property | Type | Description |
---|---|---|
homePageUrl | String | Home page or landing page of the application. |
implicitGrantSettings | implicitGrantSettings | Specifies whether this web application can request tokens using the OAuth 2.0 implicit flow. |
logoutUrl | String | Specifies the URL that is used by Microsoft's authorization service to sign out a user using front-channel, back-channel or SAML sign out protocols. |
redirectUris | String collection | Specifies the URLs where user tokens are sent for sign-in, or the redirect URIs where OAuth 2.0 authorization codes and access tokens are sent in the web platform. |
Example:
web: {
"homePageUrl": "String",
"implicitGrantSettings": {
"enableIdTokenIssuance": "Boolean",
"enableAccessTokenIssuance": "Boolean"}
"logoutUrl": "String",
"redirectUris": ["String"]
}
spa attribute
Key | Value type |
---|---|
spa | spaApplication resource type |
Specifies settings for a single-page application, including sign out URLs and redirect URIs for authorization codes and access tokens.
Property | Type | Description |
---|---|---|
redirectUris | String collection | Specifies the URLs where user tokens are sent for sign-in, or the redirect URIs where OAuth 2.0 authorization codes and access tokens are sent. |
Example:
spa: {
"redirectUris": ["String"]
}
publicClient attribute
Key | Value type |
---|---|
publicClient | publicClientApplication resource type |
Specifies settings for nonweb app or nonweb API (for example, iOS, Android, mobile or other public clients such as an installed application running on a desktop device).
Property | Type | Description |
---|---|---|
redirectUris | String collection | Specifies the URLs where user tokens are sent for sign-in, or the redirect URIs where OAuth 2.0 authorization codes and access tokens are sent. |
Example:
publicClient: {
"redirectUris": ["String"]
}
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 oauth2PermissionScopes. 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 appRoles 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."
Troubleshoot manifest migration from Azure AD Graph format to Microsoft Graph format
When you upload a previously downloaded app manifest in Azure AD Graph format, you may get the following error:
Failed to update {app name} application. Error detail: invalid property '{property name}'.**
This might be due to the migration from Azure AD Graph to Microsoft Graph app manifest. Firstly, you should check if the app manifest is in Azure AD Graph format. If it is, you should convert the app manifest to Microsoft Graph format.
I can't find the trustedCertificateSubjects attribute
trustedCertificateSubjects attribute is a Microsoft internal property. The Microsoft Entra admin center shows version 1.0 of the Microsoft Graph app manifest, trustedCertificateSubjects attribute is only present in beta version of the app manifest (Microsoft Graph format). Continue to edit this property using the app manifest (Azure AD Graph format) in the Microsoft Entra admin center.
ERROR: The application was not found. If the application was just created, wait a few minutes and refresh the page.**
If your application was not just created, you might be getting this error because you have added an invalid attribute in the Microsoft Graph app manifest. Please review attribute differences between Azure AD Graph and Microsoft Graph formats and see if you have added an attribute that is not supported in Microsoft Graph format v1.0 version that is shown in the portal.
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.