Microsoft Entra 應用程式資訊清單

  • 文章

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

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

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

設定應用程式指令清單

若要設定應用程式指令清單：

  1. 以至少應用程式開發人員身分登入 Microsoft Entra 系統管理中心。
  2. 流覽至 [身分>識別應用程式> 應用程式註冊]。
  3. 選取您要設定的應用程式。
  4. 從應用程式的 [ 概觀] 頁面中，選取 [ 指令清單] 區段。 Web 型指令清單編輯器隨即開啟，可讓您編輯指令清單。 您可以選擇性地選取 [ 下載 ] 在本機編輯指令清單，然後使用 [上傳 ] 將它重新套用至您的應用程式。

指令清單參考

本節描述應用程式指令清單中找到的屬性。

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

設定 groups 應用程式預期在使用者或 OAuth 2.0 存取令牌中發出的宣告。 若要設定此屬性，請使用下列其中一個有效的字串值：

  • "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 值會用來唯一識別及存取資源。

支援下列 API 和 HTTP 配置型應用程式識別碼 URI 格式。 請取代下表後面的清單中所述的佔位元值。

支援的應用程式識別碼
URI 格式		 範例應用程式識別碼 URI
<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> - 應用程式物件的應用程式識別碼 （appId） 屬性。
  • <string> - 主機或 API 路徑區段的字串值。
  • <tenantId> - Azure 產生的 GUID，代表 Azure 內的租使用者。
  • <tenantInitialDomain tenantInitialDomain.onmicrosoft.com>< - ，其中 <tenantInitialDomain>> 是租使用者建立者在租使用者建立時指定的初始功能變數名稱。
  • <verifiedCustomDomain> - 為 Microsoft Entra 租使用者設定的已驗證自定義網域 。

注意

如果您使用 api:// 配置，則直接在 「api://」 後面新增字串值。 例如，api:// string>。< 該字串值可以是 GUID 或任意字串。 如果您新增 GUID 值，它必須符合應用程式識別碼或租使用者識別碼。 應用程式識別碼 URI 值對租使用者而言必須是唯一的。 如果您將 api://< tenantId> 新增為應用程式識別碼 URI，則任何其他應用程式都無法使用該 URI。 建議改為使用 api://< appId> 或 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 ，並查看隱含流程的相關主題。

範例：

    "oauth2AllowImplicitFlow": false,

oauth2AllowIdTokenImplicitFlow 屬性

機碼 值類型
oauth2AllowIdTokenImplicitFlow 布林值

指定此 Web 應用程式是否可以要求 OAuth2.0 隱含流程識別碼令牌。 預設值為 false。 此旗標用於瀏覽器型應用程式，例如 JavaScript 單頁應用程式。

範例：

    "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 布林值

指定在 OAuth 2.0 令牌要求中，Microsoft Entra ID 是否允許 POST 要求，而不是 GET 要求。 默認值為 false，指定只允許 GET 要求。

範例：

    "oauth2RequirePostResponse": false,

parentalControl 設定 屬性

機碼 值類型
parentalControl 設定 String
  • countriesBlockedForMinors 指定針對未成年人封鎖應用程式的國家/地區。
  • legalAgeGroupRule 指定適用於應用程式使用者的法律年齡群組規則。 可以設定為Allow、、RequireConsentForPrivacyServicesRequireConsentForMinors、 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 Entra 租使用者中具有個人 Microsoft 帳戶或公司或學校帳戶的使用者
  • PersonalMicrosoftAccount - 用來登入 Xbox 和 Skype 等服務的個人帳戶。

範例：

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

tags 屬性

機碼 值類型
標記 字串陣列

可用來分類和識別應用程式的自定義字串。

範例：

    "tags": [
       "ProductionApp"
    ],

常見問題

指令清單限制

應用程式指令清單有多個稱為集合的屬性;例如，appRoles、keyCredentials、knownClientApplications、identifierUris、redirectUris、requiredResourceAccess 和 oauth2Permissions。 在任何應用程式的完整應用程式指令清單中，合併的所有集合中的項目總數上限為1200。 如果您先前在應用程式指令清單中指定100個重新導向URI，則您只剩下1100個剩餘專案，以用於組成指令清單的所有其他集合。

注意

如果您嘗試在應用程式指令清單中新增超過 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 應用程式。 錯誤詳細數據：找不到沒有類型名稱的值，而且沒有預期的類型可供使用。 指定模型時，承載中的每個值都必須具有可在承載中指定的類型，由呼叫端明確指定，或從父值隱含推斷。 []"

當您看到下列其中一個錯誤時，建議您執行下列動作：

  1. 在指令清單編輯器中個別編輯屬性，而不是上傳先前下載的指令清單。 使用指令清單參考數據表來瞭解新舊屬性的語法和語意，以便您成功編輯感興趣的屬性。
  2. 如果您的工作流程要求您在來源存放庫中儲存指令清單以供稍後使用，建議您使用您在 應用程式註冊 體驗中看到的存放庫中儲存的指令清單。

下一步

使用下列批注區段來提供意見反應，以協助精簡和塑造我們的內容。