Microsoft Entra 應用程式資訊清單 (Azure AD Graph 格式)

發行項
09/27/2024

應用程式資訊清單包含 Microsoft 身分識別平台中應用程式物件的所有屬性定義。它也可作為更新應用程式物件的機制。如需應用程式實體和其結構描述的詳細資訊，請參閱圖形 API 應用程式實體文件。

您可以透過 Microsoft Entra 系統管理中心或以程式設計方式使用 Microsoft Graph API 或 Microsoft Graph PowerShell SDK 來設定應用程式的屬性。不過，在某些情況下，您需要編輯應用程式資訊清單，才能設定應用程式的屬性。這些案例包括：

如果您已將應用程式註冊為 Microsoft Entra 多租用戶和個人 Microsoft 帳戶，則無法在 UI 中變更所支援的 Microsoft 帳戶。相反地，您必須使用應用程式資訊清單編輯器來變更支援的帳戶類型。
若要定義應用程式所支援的權限和角色，您必須修改應用程式資訊清單。

設定應用程式資訊清單

若要設定應用程式資訊清單：

以至少應用程式開發人員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。
選取您要設定的應用程式。
從應用程式的 [管理] 區段中，選取 [資訊清單]。網頁式資訊清單編輯器隨即開啟，讓您編輯資訊清單。或者，您也可以選取 [下載] 在本機編輯資訊清單，然後使用 [上傳] 將其重新套用到您的應用程式。

資訊清單參考

本節說明在應用程式資訊清單中找到的屬性。

id 屬性

機碼	值類型
id	String

目錄中應用程式的唯一識別碼。此識別碼不是用來在任何通訊協定交易中識別應用程式的識別碼。將其用於參考目錄查詢中的物件。

範例：

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

acceptMappedClaims 屬性

機碼	值類型
acceptMappedClaims	可為 Null 的布林值

如 apiApplication 資源類型上所記載，這可讓應用程式使用宣告對應，而不需要指定自訂簽署金鑰。應用程式接收權杖的前提是，宣告值是由 Microsoft Entra ID 所授權發出，而且無法篡改。不過，當您透過宣告對應原則修改權杖內容時，這些假設可能不再成立。應用程式必須明確認知到權杖是由宣告對應原則的建立者所修改，以避免受到惡意執行者建立的宣告對應原則所威脅。

警告

若為多租用戶應用程式，請不要將 acceptMappedClaims 屬性設定為 true，此舉可讓惡意執行者為您的應用程式建立宣告對應原則。

範例：

    "acceptMappedClaims": true,

accessTokenAcceptedVersion 屬性

機碼	值類型
accessTokenAcceptedVersion	可為 null 的 Int32

指定資源所需的存取權杖版本。所產生的 JWT 與用於要求存取權杖的端點或用戶端無關，此參數會變更其版本和格式。

由客戶端選擇的使用端點 v1.0 或 v2.0 僅影響 id_tokens 的版本。資源必須明確設定 accesstokenAcceptedVersion，以表示支援的存取權杖格式。

accesstokenAcceptedVersion 的可能值為 1、2 或 Null。如果值為 Null，此參數會預設為 1，其對應至 v1.0 端點。

如果 signInAudience 為 AzureADandPersonalMicrosoftAccount，此值必須是 2。

範例：

    "accessTokenAcceptedVersion": 2,

addIns 屬性

機碼	值類型
addIns	集合

定義取用服務可用來在特定內容中呼叫應用程式的自訂行為。例如，可轉譯檔案資料流的應用程式可能會為其 "FileHandler" 功能設定 addIns 屬性。此參數可讓 Microsoft 365 這類服務在使用者正在處理的文件內容中呼叫應用程式。

範例：

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

allowPublicClient 屬性

機碼	值類型
allowPublicClient	布林值

指定後援應用程式類型。根據預設，Microsoft Entra ID 會從 replyUrlsWithType 推斷應用程式類型。在某些情況下，Microsoft Entra ID 無法判斷用戶端應用程式類型。例如，其中一個這類案例是 ROPC 流程，其中的 HTTP 要求會在不需 URL 重新導向的情況下發生。在這些情況下，Microsoft Entra ID 會根據此屬性的值來解譯應用程式類型。如果此值設為 true，後援應用程式類型就會設定為公用用戶端，例如在行動裝置上執行的已安裝應用程式。預設值為 false，這表示後援應用程式類型是機密用戶端，例如 Web 應用程式。

範例：

    "allowPublicClient": false,

appId 屬性

機碼	值類型
appId	String

對於 Microsoft Entra ID 指派給應用程式的應用程式，指定唯一識別碼。

範例：

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

appRoles 屬性

機碼	值類型
appRoles	集合

指定應用程式可以宣告的角色集合。這些角色可以指派給使用者、群組或服務主體。如需更多範例和資訊，請參閱在您的應用程式中新增應用程式角色，並且在權杖中接收這些角色。

範例：

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

errorUrl 屬性

機碼	值類型
errorUrl	String

不支援。

groupMembershipClaims 屬性

機碼	值類型
groupMembershipClaims	String

可設定應用程式所需使用者或 OAuth 2.0 存取權杖中所發出的 groups 宣告。若要設定此屬性，請使用下列其中一個有效字串值：

"None"
"SecurityGroup" (適用於安全性群組和 Microsoft Entra 角色)
"ApplicationGroup" (此選項只會包含指派給應用程式的群組)
"DirectoryRole" (取得使用者所屬的 Microsoft Entra 目錄角色)
"All" (這會取得已登入使用者所屬的所有安全性群組、通訊群組和 Microsoft Entra 目錄角色)。

範例：

    "groupMembershipClaims": "SecurityGroup",

optionalClaims 屬性

機碼	值類型
optionalClaims	String

由此特定應用程式的安全性權杖服務在權杖中傳回的選擇性宣告。

同時支援個人帳戶和 Microsoft Entra ID 的應用程式無法使用選擇性宣告。不過，使用 v2.0 端點只註冊 Microsoft Entra ID 的應用程式，可以在資訊清單中取得所要求的選擇性宣告。如需詳細資訊，請參閱選用宣告。

範例：

    "optionalClaims": null,

identifierUris 屬性

機碼	值類型
identifierUris	字串陣列

使用者定義的 URI，可唯一識別其 Microsoft Entra 租用戶或已驗證客戶擁有網域內的 Web 應用程式。應用程式用作資源應用程式時，會使用 identifierUri 值來唯一識別以及存取資源。若為公用用戶端應用程式，不能有 identifierUris 的值。

支援下列 API 和以 HTTP 配置為基礎的應用程式識別碼 URI 格式。將預留位置值取代為下表清單中所述的項目。

支援的應用程式識別碼 URI 格式	範例應用程式識別碼 URI
api://<應用程式識別碼>	api://00001111-aaaa-2222-bbbb-3333cccc4444
api://<租用戶識別碼>/<應用程式識別碼>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
api://<租用戶識別碼>/<字串>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
api://<字串>/<應用程式識別碼>	api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444
https://<tenantInitialDomain>.onmicrosoft.com/<字串>	`https://contoso.onmicrosoft.com/productsapi`
https://<已驗證的自訂網域>/<字串>	`https://contoso.com/productsapi`
https://<字串>.<已驗證的自訂網域>	`https://product.contoso.com`
https://<字串>.<已驗證的自訂網域>/<字串>	`https://product.contoso.com/productsapi`

<appId>：應用程式物件的應用程式識別碼 (appId) 屬性。
<string>：主機或 API 路徑線段的字串值。
<tenantId>：Azure 所產生的 GUID，用來代表 Azure 內的租用戶。
<tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com，其中 <tenantInitialDomain> 是租用戶建立者在建立租用戶時指定的初始網域名稱。
<verifiedCustomDomain>：為 Microsoft Entra 租用戶設定的已驗證自訂網域。

注意

如果您使用 api:// 配置，請直接在 "api://" 之後新增字串值。例如 api://<字串>。該字串值可以是 GUID 或任意字串。如果您新增 GUID 值，其必須符合應用程式識別碼或租用戶識別碼。應用程式識別碼 URI 值對租用戶來說必須是唯一的。如果您新增 api://<租用戶識別碼> 作為應用程式識別碼 URI，其他人將無法在任何其他應用程式中使用該 URI。建議使用 api://<應用程式識別碼>，或改為使用 HTTP 配置。

重要

應用程式識別碼 URI 值不得以斜線 “/” 字元結尾。

範例：

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

informationalUrls 屬性

機碼	值類型
informationalUrls	String

指定應用程式服務條款和隱私權聲明的連結。使用者會透過使用者同意體驗看到服務條款和隱私權聲明。如需詳細資訊，請參閱如何：新增已註冊 Microsoft Entra 應用程式的服務條款和隱私權聲明。

範例：

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

keyCredentials 屬性

機碼	值類型
keyCredentials	集合

保留對應用程式指定認證、字串型的共用密碼以及 X.509 憑證的參考。要求存取權杖時會使用這些認證 (當應用程式作為用戶端，而不是資源時)。

範例：

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

knownClientApplications 屬性

機碼	值類型
knownClientApplications	字串陣列

如果您有包含兩個組件 (用戶端應用程式及自訂 Web API 應用程式) 的解決方案，則用來統合同意。如果您將此值輸入為用戶端應用程式的 appID ，則使用者只需同意用戶端應用程式一次。 Microsoft Entra ID 將會知道同意用戶端表示隱含地同意 Web API。其會同時自動佈建用戶端和 Web API 的服務主體。用戶端與 Web API 應用程式都必須在相同的租用戶中註冊。

範例：

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

logoUrl 屬性

機碼	值類型
logoUrl	String

唯讀值，指向已上傳標誌的 CDN URL。

範例：

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

logoutUrl 屬性

機碼	值類型
logoutUrl	String

用於登出應用程式的 URL。

範例：

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

name 屬性

機碼	值類型
NAME	String

應用程式的顯示名稱。

範例：

    "name": "MyRegisteredApp",

oauth2AllowImplicitFlow 屬性

機碼	值類型
oauth2AllowImplicitFlow	布林值

指定此 Web 應用程式可否要求 OAuth2.0 隱含流程存取權杖。預設值為 false。此旗標用於瀏覽器型應用程式，例如 JavaScript 單頁應用程式。若要進一步了解，請在目錄中輸入 OAuth 2.0 implicit grant flow 並查看隱含流程相關主題。不過，我們不建議在 SPA 中使用隱含授與，並建議搭配使用授權碼流程和 PKCE。

範例：

    "oauth2AllowImplicitFlow": false,

oauth2AllowIdTokenImplicitFlow 屬性

機碼	值類型
oauth2AllowIdTokenImplicitFlow	布林值

指定此 Web 應用程式可否要求 OAuth2.0 隱含流程識別碼權杖。預設值為 false。此旗標用於瀏覽器型應用程式，例如 JavaScript 單頁應用程式。不過，我們不建議在 SPA 中使用隱含授與，並建議搭配使用授權碼流程和 PKCE。

範例：

    "oauth2AllowIdTokenImplicitFlow": false,

oauth2Permissions 屬性

機碼	值類型
oauth2Permissions	集合

指定 Web API (資源) 應用程式公開給用戶端應用程式的 OAuth 2.0 權限範圍集合。這些權限範圍可能會在同意過程中授與用戶端應用程式。

範例：

    "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 屬性

機碼	值類型
oauth2RequiredPostResponse	布林值

指定 Microsoft Entra ID 在 OAuth 2.0 權杖要求期間是否將允許 POST 要求 (相對於 GET 要求)。預設值為 false，即指定只允許 GET 要求。

範例：

    "oauth2RequirePostResponse": false,

parentalControlSettings 屬性

機碼	值類型
parentalControlSettings	String

countriesBlockedForMinors 指定會對未成年人封鎖此應用程式的國家/區域。
legalAgeGroupRule 指定會套用到應用程式使用者的法定年齡群組規則。可以設定為 Allow、RequireConsentForPrivacyServices、RequireConsentForMinors、RequireConsentForKids 或 BlockMinors。

範例：

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

passwordCredentials 屬性

機碼	值類型
passwordCredentials	集合

請參閱 keyCredentials 屬性的描述。

範例：

    "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 屬性

機碼	值類型
preAuthorizedApplications	集合

列出需要隱含同意的應用程式和要求的權限。需要系統管理員同意應用程式。 preAuthorizedApplications 不需要使用者同意要求的權限。 PreAuthorizedApplications 中所列的權限不需要使用者同意。不過，preAuthorizedApplications 中未列出的任何其他要求權限則需要使用者同意。

範例：

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

publisherDomain 屬性

機碼	值類型
publisherDomain	String

應用程式的已驗證發行者網域。唯讀。

範例：

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

replyUrlsWithType 屬性

機碼	值類型
replyUrlsWithType	集合

傳回權杖時，此多重值屬性會保留 Microsoft Entra ID 將接受作為目的地的已註冊 redirect_uri 值清單。每個 URI 值皆應包含相關聯的應用程式類型值。支援的類型值如下：

Web
InstalledClient
Spa

若要深入了解，請參閱 replyUrl 限制。

範例：

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

requiredResourceAccess 屬性

機碼	值類型
requiredResourceAccess	集合

在動態同意的情況下，requiredResourceAccess 可對使用靜態同意的使用者，推動系統管理員同意體驗和使用者同意體驗。不過，此參數不會推動一般情況的使用者同意體驗。

resourceAppId 是應用程式所需存取資源的唯一識別碼。此值應該等於目標資源應用程式上宣告的 appId。
resourceAccess 是一個陣列，其中列出應用程式向指定的資源要求的 OAuth2.0 權限範圍和應用程式角色。包含所指定資源的 id 和 type 值。

範例：

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

samlMetadataUrl 屬性

機碼	值類型
samlMetadataUrl	String

應用程式 SAML 中繼資料的 URL。

範例：

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

signInUrl 屬性

機碼	值類型
signInUrl	String

指定應用程式首頁的 URL。

範例：

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

signInAudience 屬性

機碼	值類型
signInAudience	String

指定目前的應用程式支援哪些 Microsoft 帳戶。支援的值為：

AzureADMyOrg - 使用者具有我組織 Microsoft Entra 租用戶中的 Microsoft 公司或學校帳戶 (例如，單一租用戶)
AzureADMultipleOrgs - 使用者具有任何組織 Microsoft Entra 租用戶中的 Microsoft 公司或學校帳戶 (例如，多組織用戶共享)
AzureADandPersonalMicrosoftAccount - 使用者具有個人 Microsoft 帳戶，或任何組織 Microsoft Entra 租用戶中的公司或學校帳戶
PersonalMicrosoftAccount - 用於登入 Xbox 及 Skype 等服務的個人帳戶。

範例：

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

tags 屬性

機碼	值類型
標記	字串陣列

可用來分類及識別應用程式的自訂字串。

範例：

    "tags": [
       "ProductionApp"
    ],

常見問題

資訊清單限制

應用程式資訊清單有多個稱之為集合的屬性；例如，appRoles、keyCredentials、knownClientApplications、identifierUris、redirectUris、requiredResourceAccess 和 oauth2Permissions。在任何應用程式的完整應用程式資訊清單中，所有合併集合中的項目總數上限為 1200。如果您先前在應用程式資訊清單中指定 100 個重新導向 URI，則您只剩下 1,100 個剩餘項目可在構成資訊清單的所有其他合併集合中使用。

注意

如果您嘗試在應用程式資訊清單中新增超過 1200 個項目，您可能會看到錯誤「無法更新應用程式 xxxxxx。錯誤詳細資料：資訊清單的大小已超過其限制。請減少值的數目，然後重試您的要求。」

不支援的屬性

應用程式資訊清單代表 Microsoft Entra ID 中基礎應用程式模型的結構描述。隨著基礎結構描述的發展，資訊清單編輯器將會更新，不時地反映新的結構描述。因此，您可能會注意到應用程式資訊清單中顯示的新屬性。在少數的情況下，您可能會注意到現有屬性有語法或語義上的變更，或者您可能發現先前存在的屬性已不再受到支援。例如，您會在應用程式註冊中看到新屬性，其已知在應用程式註冊 (舊版) 體驗中具有不同的名稱。

應用程式註冊 (舊版)	應用程式註冊
`availableToOtherTenants`	`signInAudience`
`displayName`	`name`
`errorUrl`	-
`homepage`	`signInUrl`
`objectId`	`Id`
`publicClient`	`allowPublicClient`
`replyUrls`	`replyUrlsWithType`

如需這些屬性的說明，請參閱資訊清單參考一節。

當您嘗試上傳先前下載的資訊清單時，您可能會看到下列其中一個錯誤。此錯誤可能是因為資訊清單編輯器現在支援較新版的結構描述，這與您嘗試上傳的資訊清單不相符。

「無法更新 xxxxxx 應用程式。錯誤詳細資料：物件識別碼 'undefined' 無效。 },
「無法更新 xxxxxx 應用程式。錯誤詳細資料：指定的一或多個屬性值無效。 },
「無法更新 xxxxxx 應用程式。錯誤詳細資料：不允許在此 api 版本中設定 availableToOtherTenants 以進行更新。 },
「無法更新 xxxxxx 應用程式。錯誤詳細資料：不允許此應用程式更新 'replyUrls' 屬性。請改用 'replyUrlsWithType' 屬性。 },
「無法更新 xxxxxx 應用程式。錯誤詳細資料：發現沒有類型名稱的值，但沒有預期的類型可用。當指定模型時，裝載中的每個值都必須有類型，此類型可以在裝載中指定、由呼叫端明確指定，或從父值隱含推斷。

當您看到其中一個錯誤時，我們建議採取下列動作：

在資訊清單編輯器中個別地編輯屬性，而不是上傳先前下載的資訊清單。使用資訊清單參考資料表來了解舊屬性和新屬性的語法和語義，讓您可成功編輯您感興趣的屬性。
如果您的工作流程要求您在來源存放庫中儲存資訊清單以供稍後使用，建議以您在應用程式註冊體驗中看到的資訊清單，將存放庫中儲存的資訊清單重訂基底。

後續步驟

如需應用程式的應用程式與服務主體物件之間關係的詳細資訊，請參閱Microsoft Entra ID 中的應用程式和服務主體物件。
如需某些核心 Microsoft 身分識別平台開發人員概念的定義，請參閱Microsoft 身分識別平台開發人員詞彙。

使用下列意見區段來提供意見反應，以協助改善及塑造我們的內容。

共用方式為