了解應用程式資訊清單 (Microsoft Graph 格式)
應用程式資訊清單包含 Microsoft 身分識別平台中應用程式註冊的所有屬性及其值。
Microsoft Graph 應用程式資訊清單是代表應用程式註冊的 JSON 物件。 它也稱為 Microsoft Graph 應用程式資源類型 或 Microsoft Graph 應用程式物件 (application object)。 它包含應用程式註冊的所有屬性及其值。
您使用 Microsoft Graph Get Application 方法接收的應用程式物件與您在 Microsoft Entra 系統管理中心的應用程式註冊資訊清單頁面中看到的 JSON 物件相同。
注意
對於個人Microsoft 帳戶 (MSA 帳戶) 註冊的應用程式,您將繼續看到 Microsoft Entra 系統管理中心中 Azure AD Graph 格式的應用程式資訊清單,直到進一步通知為止。 如需詳細資訊,請參閱<Microsoft Entra 應用程式資訊清單 (Azure AD Graph 格式)>。
設定 Microsoft Graph 應用程式資訊清單
如果您想要以程式設計方式設定 Microsoft Graph 應用程式資訊清單,您可以使用 Microsoft Graph API 或 Microsoft Graph PowerShell SDK。
您也可以透過 Microsoft Entra 系統管理中心來設定應用程式資訊清單。 大部分的屬性都可以使用 [應用程式註冊] 中的 UI 元素來設定。 不過,某些屬性必須透過直接在 [資訊清單] 頁面中編輯應用程式資訊清單來設定。
在 Microsoft Entra 系統管理中心設定應用程式資訊清單
若要設定 Microsoft Graph 應用程式資訊清單:
瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。
選取您要設定的應用程式。
從應用程式的 [概觀] 頁面,選取 [資訊清單] 區段。 網頁式資訊清單編輯器隨即開啟,讓您編輯資訊清單。 或者,您也可以選取 [下載] 在本機編輯資訊清單,然後使用 [上傳] 將其重新套用到您的應用程式。
資訊清單參考
本節說明在 Microsoft Graph 應用程式資訊清單中找到的屬性。
id 屬性
機碼 | 值類型 |
---|---|
id | 字串 |
此屬性在 Microsoft Entra 系統管理中心稱為物件識別碼。 它是目錄中應用程式物件的唯一識別碼。
此識別碼不是用來在任何通訊協定交易中識別應用程式的識別碼。 它被用於參考目錄查詢中的物件。
此屬性不可為 Null 且為唯讀屬性。
範例:
"id": "f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd",
appId 屬性
機碼 | 值類型 |
---|---|
appId | String |
此屬性在 Microsoft Entra 系統管理中心中被稱為應用程式 (用戶端) 識別碼。 它是目錄中應用程式物件的唯一識別碼。
此識別碼是用來在任何通訊協定交易中識別應用程式的識別碼。
此屬性不可為 Null 且為唯讀屬性。
範例:
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
addIns 屬性
機碼 | 值類型 |
---|---|
addIns | 集合 |
定義取用服務可用來在特定內容中呼叫應用程式的自訂行為。 例如,可轉譯檔案資料流的應用程式可能會為其 "FileHandler" 功能設定 addIns
屬性。 此參數可讓 Microsoft 365 這類服務在使用者正在處理的文件內容中呼叫應用程式。
範例:
"addIns": [
{
"id": "968A844F-7A47-430C-9163-07AE7C31D407",
"type":" FileHandler",
"properties": [
{
"key": "version",
"value": "2"
}
]
}
],
appRoles
機碼 | 值類型 |
---|---|
appRoles | 集合 |
指定應用程式可以宣告的角色集合。 這些角色可以指派給使用者、群組或服務主體。 如需更多範例和資訊,請參閱在您的應用程式中新增應用程式角色,並且在權杖中接收這些角色。
範例:
"appRoles": [
{
"allowedMemberTypes": [
"User"
],
"description": "Read-only access to device information",
"displayName": "Read Only",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"isEnabled": true,
"value": "ReadOnly"
}
],
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":{
"idToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"accessToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"saml2Token": [{"@odata.type": "microsoft.graph.optionalClaim"}]
}
identifierUris 屬性
機碼 | 值類型 |
---|---|
identifierUris | 字串陣列 |
使用者定義的 URI,可唯一識別其 Microsoft Entra 租用戶或已驗證客戶擁有網域內的 Web 應用程式。 應用程式用作資源應用程式時,會使用 identifierUri 值來唯一識別以及存取資源。
支援下列 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/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed",
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
}
],
displayName 屬性
機碼 | 值類型 |
---|---|
displayName | String |
應用程式的顯示名稱。
範例:
" displayName": "MyRegisteredApp",
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"
}
],
publisherDomain 屬性
機碼 | 值類型 |
---|---|
publisherDomain | String |
應用程式的已驗證發行者網域。 唯讀。 若要編輯應用程式註冊的發行者網域,請遵循<設定應用程式的發行者網域>中所述的步驟。
範例:
"publisherDomain": "{tenant}.onmicrosoft.com",
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",
signInAudience 屬性
機碼 | 值類型 |
---|---|
signInAudience | String |
指定目前的應用程式支援哪些 Microsoft 帳戶。 支援的值為:
AzureADMyOrg
- 使用者具有我組織 Microsoft Entra 租用戶中的 Microsoft 公司或學校帳戶 (例如,單一租用戶)AzureADMultipleOrgs
- 使用者具有任何組織 Microsoft Entra 租用戶中的 Microsoft 公司或學校帳戶 (例如,多組織用戶共享)AzureADandPersonalMicrosoftAccount
- 使用者具有個人 Microsoft 帳戶,或任何組織 Microsoft Entra 租用戶中的公司或學校帳戶PersonalMicrosoftAccount
- 用於登入 Xbox 及 Skype 等服務的個人帳戶。
範例:
"signInAudience": "AzureADandPersonalMicrosoftAccount",
tags 屬性
機碼 | 值類型 |
---|---|
標記 | 字串陣列 |
可用來分類及識別應用程式的自訂字串。
範例:
"tags": [
"ProductionApp"
],
isFallbackPublicClient 屬性
機碼 | 值類型 |
---|---|
isFallbackPublicClient | 布林值 |
指定後援應用程式類型為公用用戶端,例如在行動裝置上執行的已安裝應用程式。 此屬性的預設值為 false,這表示後援應用程式類型是機密用戶端,例如 Web 應用程式。 在某些情況下,Microsoft Entra ID 無法判斷用戶端應用程式類型。 例如,未指定重新導向 URI 的 ROPC 流程。 在這些情況下,Microsoft Entra ID 會根據此屬性的值來解譯應用程式類型。
範例:
"isFallbackPublicClient ": "false",
info 屬性
機碼 | 值類型 |
---|---|
資訊 | informationalUrl |
指定應用程式的基本設定檔資訊,包括應用程式的行銷、支援、服務條款、隱私權聲明和標誌 URL。
請注意:
"logoUrl" 是唯讀屬性。 您無法在應用程式資訊清單中編輯此屬性。 瀏覽至所需應用程式註冊中的 [商標和屬性] 頁面,並使用 [上傳新標誌] 來上傳新的標誌。
使用者會透過使用者同意體驗看到服務條款和隱私權聲明。 如需詳細資訊,請參閱如何:新增已註冊 Microsoft Entra 應用程式的服務條款和隱私權聲明。
範例:
Info: {
"termsOfService": "https://MyRegisteredApp/termsofservice",
"support": "https://MyRegisteredApp/support",
"privacy": "https://MyRegisteredApp/privacystatement",
"marketing": "https://MyRegisteredApp/marketing"
"logoUrl": "https://MyRegisteredApp/logoUrl",
}
api 屬性
機碼 | 值類型 |
---|---|
api | apiApplication 資源類型 |
指定實作 Web API 的應用程式設定。 它包含五個屬性:
屬性 | 類型 | 描述 |
---|---|---|
acceptMappedClaims | 布林值 | 設定為 true 時,可讓應用程式使用宣告對應,而不需指定自訂簽署金鑰。 應用程式接收權杖的前提是,宣告值是由 Microsoft Entra ID 所授權發出,而且無法篡改。 不過,當您透過宣告對應原則修改權杖內容時,這些假設可能不再成立。 應用程式必須明確認知到權杖是由宣告對應原則的建立者所修改,以避免受到惡意執行者建立的宣告對應原則所威脅。 警告:若為多組織用戶共享應用程式,請不要將 acceptMappedClaims 屬性設定為 true,此舉可讓惡意執行者為您的應用程式建立宣告對應原則。 |
ownClientApplications | 集合 | 如果您有包含兩個組件 (用戶端應用程式及自訂 Web API 應用程式) 的解決方案,則用來統合同意。 如果您將此值設定為用戶端應用程式的 appID ,則使用者僅同意用戶端應用程式一次。 Microsoft Entra ID 知道同意用戶端表示隱含地同意 Web API,並同時自動為這兩個 API 布建服務主體。 用戶端與 Web API 應用程式都必須在相同的租用戶中註冊。 |
ownClientApplications | 集合 | 如果您有包含兩個組件 (用戶端應用程式及自訂 Web API 應用程式) 的解決方案,則用來統合同意。 如果您將此值設定為用戶端應用程式的 appID ,則使用者僅同意用戶端應用程式一次。 Microsoft Entra ID 知道同意用戶端表示隱含地同意 Web API,並同時自動為這兩個 API 布建服務主體。 用戶端與 Web API 應用程式都必須在相同的租用戶中註冊。 |
oauth2PermissionScopes | permissionScope 集合 | 此應用程式註冊所代表之 Web API 所公開之委派權限的定義。 用戶端應用程式可能會要求這些委派權限,並在同意期間由使用者或管理員授與。 委派權限有時稱為 OAuth 2.0 範圍。 |
preAuthorizedApplications | preAuthorizedApplication 集合 | 列出使用指定委派權限預先授權的用戶端應用程式,以存取此應用程式的 API。 使用者不需要同意任何預先授權的應用程式 (針對指定的權限)。 不過,在 preAuthorizedApplications 中未列出的任何其他權限 (例如透過累加同意要求) 都需要使用者同意。 |
requestedAccessTokenVersion | Int32 | 指定此資源所需的存取權杖版本。 所產生的 JWT 與用於要求存取權杖的端點或用戶端無關,這會變更其版本和格式。 由客戶端選擇的使用端點 v1.0 或 v2.0 僅影響 id_tokens 的版本。 資源必須明確設定 requestedAccessTokenVersion,以表示支援的存取權杖格式。 requestedAccessTokenVersion 的可能值為 1、2 或 null。 如果值為 Null,此值會預設為 1,其對應至 v1.0 端點。 如果 應用程式的 signInAudience 設定為 AzureADandPersonalMicrosoftAccount 或 PersonalMicrosoftAccount,則此屬性的值必須是 2。 |
範例:
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 屬性
機碼 | 值類型 |
---|---|
web | webApplication 資源類型 |
指定 Web 應用程式的設定。 它包含四個屬性。
屬性 | 類型 | 描述 |
---|---|---|
homePageUrl | String | 應用程式的首頁或登陸頁面。 |
implicitGrantSettings | implicitGrantSettings | 指定此 Web 應用程式可否要求使用 OAuth 2.0 隱含流程的權杖。 |
logoutUrl | String | 指定 Microsoft 授權服務用來使用前端通道、後端通道或 SAML 登出通訊協議來登出使用者的 URL。 |
redirectUris | 字串集合 | 指定將使用者權杖傳送給登入的 URL,或是在 Web 平台中傳送 OAuth 2.0 授權碼和存取令牌的重新導向 URI。 |
範例:
web: {
"homePageUrl": "String",
"implicitGrantSettings": {
"enableIdTokenIssuance": "Boolean",
"enableAccessTokenIssuance": "Boolean"}
"logoutUrl": "String",
"redirectUris": ["String"]
}
spa 屬性
機碼 | 值類型 |
---|---|
spa | spaApplication 資源類型 |
指定單頁應用程式的設定,包括登出 URL,以及授權碼和存取權杖的重新導向 URI。
屬性 | 類型 | 描述 |
---|---|---|
redirectUris | 字串集合 | 指定傳送使用者權杖以進行登入的 URL,或傳送 OAuth 2.0 授權碼和存取權杖的重新導向 URI。 |
範例:
spa: {
"redirectUris": ["String"]
}
publicClient 屬性
機碼 | 值類型 |
---|---|
publicClient | publicClientApplication 資源類型 |
指定非 Web 應用程式或非 Web API 的設定 (例如 iOS、Android、行動裝置或其他公用用戶端,例如在電腦裝置上執行的應用程式)。
屬性 | 類型 | 描述 |
---|---|---|
redirectUris | 字串集合 | 指定傳送使用者權杖以進行登入的 URL,或傳送 OAuth 2.0 授權碼和存取權杖的重新導向 URI。 |
範例:
publicClient: {
"redirectUris": ["String"]
}
常見問題
資訊清單限制
應用程式資訊清單有多個稱之為集合的屬性;例如,appRoles、keyCredentials、knownClientApplications、identifierUris、redirectUris、requiredResourceAccess 和 oauth2PermissionScopes。 在任何應用程式的完整應用程式資訊清單中,所有合併集合中的項目總數上限為 1200。 如果您先前在應用程式資訊清單中指定 100 個 appRole,則您只剩下 1100 個剩餘項目可在構成資訊清單的所有其他合併集合中使用。
注意
如果您嘗試在應用程式資訊清單中新增超過 1200 個項目,您可能會看到錯誤「無法更新應用程式 xxxxxx。錯誤詳細資料:資訊清單的大小已超過其限制。請減少值的數目,然後重試您的要求。」
針對從 Azure AD Graph 格式移轉至 Microsoft Graph 格式的資訊清單進行疑難排解
當您以 Azure AD Graph 格式上傳先前下載的應用程式資訊清單時,可能會收到下列錯誤:
無法更新 (應用程式名稱) 應用程式。 錯誤詳細資料:無效的屬性 '{屬性名稱}'.**
這可能是因為從 Azure AD Graph 移轉至 Microsoft Graph 應用程式資訊清單。 首先,您應該檢查應用程式資訊清單是否為 Azure AD Graph 格式。 如果是,您應該將應用程式資訊清單轉換成 Microsoft Graph 格式。
找不到 trustedCertificateSubjects 屬性
trustedCertificateSubjects 屬性是 Microsoft 內部屬性。 Microsoft Entra 系統管理中心會顯示 1.0 版的 Microsoft Graph 應用程式資訊清單,trustedCertificateSubjects 屬性只存在於應用程式資訊清單的 beta 版 (Microsoft Graph 格式) 中。 繼續在 Microsoft Entra 系統管理中心使用應用程式資訊清單 (Azure AD Graph 格式) 編輯此屬性。
錯誤:找不到應用程式。 如果應用程式為剛建立,請等候幾分鐘並重新整理頁面。**
如果您的應用程式並非剛建立,您會收到此錯誤,可能是因為您在 Microsoft Graph 應用程式資訊清單中新增了無效的屬性。 請檢閱 Azure AD Graph 與 Microsoft Graph 格式之間的屬性差異,並查看您是否已新增在入口網站中顯示的 Microsoft Graph 格式 v1.0 版本中不支援的屬性。
下一步
如需應用程式的應用程式與服務主體物件之間關係的詳細資訊,請參閱Microsoft Entra ID 中的應用程式和服務主體物件。
如需某些核心 Microsoft 身分識別平台開發人員概念的定義,請參閱Microsoft 身分識別平台開發人員詞彙。
使用下列意見區段來提供意見反應,以協助改善及塑造我們的內容。