Microsoft.Graph 服務Principals
權限
選擇標示為此 API 最低許可權的許可權。 只有在您的應用程式需要許可權時，才使用較高的特殊許可權或許可權。 如需委派和應用程式許可權的詳細資訊，請參閱 許可權類型。 若要深入瞭解這些許可權，請參閱 許可權參考。
注意
個人Microsoft帳戶的許可權無法用來部署 Bicep 檔案中宣告的 Microsoft Graph 資源。
資源部署
從下表選擇最低許可權許可權，以建立或更新 Microsoft.Graph/servicePrincipals 資源。
| 權限類型 | 最低許可權 | 較高許可權的許可權 |
|---|---|---|
| 已委派 (工作或學校帳戶) | Application.ReadWrite.All | Directory.ReadWrite.All |
| 已委派（個人 Microsoft 帳戶） | 不支援。 | 不支援。 |
| 應用程式 | Application.ReadWrite.OwnedBy | Application.ReadWrite.All、Directory.ReadWrite.All |
僅讀取現有的資源
從下表選擇最低許可權許可權，以使用 existing 關鍵詞讀取 Microsoft.Graph/servicePrincipals 資源。
| 權限類型 | 最低許可權 | 較高許可權的許可權 |
|---|---|---|
| 已委派 (工作或學校帳戶) | Application.Read.All | Application.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All |
| 已委派（個人 Microsoft 帳戶） | 不支援。 | 不支援。 |
| 應用程式 | Application.Read.All | Application.ReadWrite.OwnedBy、Application.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All |
資源格式
若要建立 Microsoft.Graph/servicePrincipals 資源，請將下列 Bicep 新增至範本。
resource symbolicname 'Microsoft.Graph/servicePrincipals@v1.0' = {
accountEnabled: bool
addIns: [
{
id: 'string'
properties: [
{
key: 'string'
value: 'string'
}
]
type: 'string'
}
]
alternativeNames: [
'string'
]
appDescription: 'string'
appDisplayName: 'string'
appId: 'string'
appRoleAssignmentRequired: bool
appRoles: [
{
allowedMemberTypes: [
'string'
]
description: 'string'
displayName: 'string'
id: 'string'
isEnabled: bool
value: 'string'
}
]
customSecurityAttributes: any
description: 'string'
disabledByMicrosoftStatus: 'string'
displayName: 'string'
homepage: 'string'
info: {
marketingUrl: 'string'
privacyStatementUrl: 'string'
supportUrl: 'string'
termsOfServiceUrl: 'string'
}
keyCredentials: [
{
customKeyIdentifier: 'string'
displayName: 'string'
endDateTime: 'string'
key: 'string'
keyId: 'string'
startDateTime: 'string'
type: 'string'
usage: 'string'
}
]
loginUrl: 'string'
logoutUrl: 'string'
notes: 'string'
notificationEmailAddresses: [
'string'
]
oauth2PermissionScopes: [
{
adminConsentDescription: 'string'
adminConsentDisplayName: 'string'
id: 'string'
isEnabled: bool
type: 'string'
userConsentDescription: 'string'
userConsentDisplayName: 'string'
value: 'string'
}
]
passwordCredentials: [
{
displayName: 'string'
endDateTime: 'string'
keyId: 'string'
startDateTime: 'string'
}
]
preferredSingleSignOnMode: 'string'
preferredTokenSigningKeyThumbprint: 'string'
replyUrls: [
'string'
]
samlSingleSignOnSettings: {
relayState: 'string'
}
servicePrincipalNames: [
'string'
]
servicePrincipalType: 'string'
tags: [
'string'
]
tokenEncryptionKeyId: 'string'
}
屬性值
servicePrincipals
| 名稱 | 描述 | 值 |
|---|---|---|
| accountEnabled | 如果已啟用服務主體帳戶，則為 true;否則為 false。 如果設定為 false，則即使使用者被指派給此應用程式，也無法登入此應用程式 | bool |
| addIns | 定義取用服務可用來在特定內容中呼叫應用程式的自訂行為。 例如，可以轉譯檔案數據流的應用程式可能會為其 『FileHandler』 功能設定 addIns 屬性。 這可讓Microsoft 365 等服務在使用者正在處理的文件內容中呼叫應用程式。 | MicrosoftGraphAddIn[] |
| alternativeNames | 用來依訂用帳戶擷取服務主體，識別受控識別的資源群組和完整資源標識符 | string[] |
| apiVersion | 資源 API 版本 | 'v1.0' （ReadOnly） |
| appDescription | 相關聯應用程式所公開的描述。 | 字串 |
| appDisplayName | 相關聯應用程式公開的顯示名稱。 長度上限為 256 個字元。 | 字串 |
| appId | 相關聯應用程式的唯一標識碼（其 appId 屬性）。 其他索引鍵 | 字串 （必要） |
| applicationTemplateId | applicationTemplate 的唯一標識符。 唯讀。 如果未從應用程式範本建立服務主體，則為 null。 | string （ReadOnly） |
| appOwnerOrganizationId | 包含註冊應用程式的租用戶標識碼。 這隻適用於應用程式所支援的服務主體 | string （ReadOnly） 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| appRoleAssignmentRequired | 指定使用者或其他服務主體是否需要為此服務主體授與應用程式角色指派，使用者才能登入或應用程式取得令牌。 預設值為 false。 不可為 Null | bool |
| appRoles | 連結至此服務主體的應用程式所公開的角色。 如需詳細資訊，請參閱應用程式實體上的 appRoles 屬性定義。 不可為 Null。 | MicrosoftGraphAppRole[] |
| customSecurityAttributes | 開啟的複雜類型，保存指派給目錄物件的自定義安全性屬性值。 可為 Null。 篩選值區分大小寫。 若要讀取此屬性，呼叫的應用程式必須指派 CustomSecAttributeAssignment.Read.All 許可權。 若要寫入此屬性，呼叫的應用程式必須指派 CustomSecAttributeAssignment.ReadWrite.All 許可權。 若要在委派的案例中讀取或寫入此屬性，系統管理員必須指派屬性指派系統管理員角色。 | 任意 |
| deletedDateTime | 刪除此物件的日期和時間。 當物件尚未刪除時，一律為 Null。 | string （ReadOnly） |
| description | 免費文字欄位，以提供服務主體的內部用戶對應描述。 使用者入口網站，例如 MyApps 會顯示此欄位中的應用程式描述。 允許的大小上限為 1,024 個字元 | 字串 |
| disabledByMicrosoftStatus | 指定Microsoft是否已停用已註冊的應用程式。 可能的值為：null（預設值）、NotDisabled 和 DisabledDueToViolationOfServicesAgreement（原因包括可疑、濫用或惡意活動，或違反Microsoft服務合約） | 字串 |
| displayName | 服務主體的顯示名稱 | 字串 |
| 首頁 | 應用程式的首頁或登陸頁面。 | 字串 |
| id | 實體的唯一標識碼。 唯讀。 | string （ReadOnly） |
| 資訊 | 所取得應用程式的基本配置檔資訊，例如應用程式的行銷、支援、服務條款和隱私聲明 URL。 使用者會透過使用者同意體驗看到服務條款和隱私權聲明。 如需詳細資訊，請參閱如何：新增已註冊Microsoft Entra 應用程式的服務條款和隱私聲明 | MicrosoftGraphInformationalUrl |
| keyCredentials | 與服務主體相關聯的金鑰認證集合。 不可為 Null | MicrosoftGraphKeyCredential[] |
| loginUrl | 指定服務提供者將使用者重新導向至要驗證Microsoft Entra ID 的 URL。 Microsoft Entra 標識符會使用 URL 從 Microsoft 365 或 Microsoft Entra 我的應用程式 啟動應用程式。 當空白時，Microsoft Entra ID 會針對使用 SAML 型單一登錄設定的應用程式執行 IdP 起始的登入。 使用者會從 Microsoft 365、Microsoft Entra 我的應用程式 或 Microsoft Entra SSO URL 啟動應用程式。 | 字串 |
| logoutUrl | 指定Microsoft授權服務用來使用 OpenID Connect 前端通道、後端通道或 SAML 註銷通訊協定註銷使用者的 URL。 | 字串 |
| 附註 | 用來擷取服務主體相關信息的免費文字欄位，通常用於操作用途。 允許的大小上限為 1,024 個字元。 | 字串 |
| notificationEmailAddresses | 指定當使用中憑證接近到期日時，Microsoft Entra ID 傳送通知的電子郵件地址清單。 這隻適用於用來簽署 Microsoft針對 entra Gallery 應用程式發行之 SAML 令牌的憑證。 | string[] |
| oauth2PermissionScopes | 應用程式公開的委派許可權。 如需詳細資訊，請參閱應用程式實體 API 屬性上的 oauth2PermissionScopes 屬性。 不可為 Null。 | MicrosoftGraphPermissionScope[] |
| passwordCredentials | 與應用程式相關聯的密碼認證集合。 不可為 Null。 | MicrosoftGraphPasswordCredential[] |
| preferredSingleSignOnMode | 指定為此應用程式設定的單一登錄模式。 Microsoft Entra ID 會使用慣用的單一登錄模式，從 Microsoft 365 或 我的應用程式 入口網站啟動應用程式。 支援的值為 password、saml、notSupported 和 oidc。 注意：對於較舊的 SAML 應用程式和未自動設定的 OIDC 應用程式，此字段可能是 Null。 | 字串 |
| preferredTokenSigningKeyThumbprint | 這個屬性可用於 SAML 應用程式（已將 preferredSingleSignOnMode 設定為 saml 的應用程式），以控制用來簽署 SAML 回應的憑證。 對於非 SAML 的應用程式，請勿寫入或依賴這個屬性。 | 字串 |
| replyUrls | 使用者令牌要用來登入相關聯應用程式的 URL，或 OAuth 2.0 授權碼和存取令牌的重新導向 URI 會傳送給相關聯的應用程式。 不可為 Null。 | string[] |
| resourceSpecificApplicationPermissions | 此應用程式公開的資源特定應用程式許可權。 目前，只有使用 Microsoft Graph 存取特定聊天和小組的 Teams 應用程式才支援資源特定許可權。 唯讀。 | MicrosoftGraphResourceSpecificPermission[] （ReadOnly） |
| samlSingleSignOnSettings | 與saml單一登入相關的設定集合。 | MicrosoftGraphSamlSingleSignOnSettings |
| servicePrincipalNames | 包含從相關聯應用程式複製的identifiersUris清單。 您可以將其他值新增至混合式應用程式。 這些值可用來識別此應用程式在 Microsoft Entra 識別符內公開的許可權。 例如，用戶端應用程式可以根據此屬性的值來指定資源 URI，以取得存取令牌，這是 『aud』 宣告中傳回的 URI。在多重值屬性上篩選表達式需要任何運算元。 不可為 Null | string[] |
| servicePrincipalType | 識別服務主體是否代表應用程式、受控識別或舊版應用程式。 這是由內部Microsoft Entra ID 所設定。 servicePrincipalType 屬性可以設定為三個不同的值：Application - 代表應用程式或服務的服務主體。 appId 屬性會識別相關聯的應用程式註冊，並符合應用程式的應用程式標識碼，可能來自不同租使用者。 如果遺漏相關聯的應用程式註冊，則不會針對服務主體發出令牌。ManagedIdentity - 代表受控識別的服務主體。 代表受控識別的服務主體可以授與存取權和許可權，但無法直接更新或修改。舊版 - 服務主體，代表在應用程式註冊之前建立的應用程式，或透過舊版體驗建立的應用程式。 舊版服務主體可以有認證、服務主體名稱、回復 URL 和其他屬性，這些屬性可由授權用戶編輯，但沒有相關聯的應用程式註冊。 appId 值不會將服務主體與應用程式註冊產生關聯。 服務主體只能在建立服務主體的租使用者中使用。SocialIdp - 供內部使用。 | 字串 |
| signInAudience | 指定目前應用程式支援的Microsoft帳戶。 唯讀。 支援的值為：AzureADMyOrg：我的組織Microsoft Entra 租使用者（單一租使用者）中具有Microsoft公司或學校帳戶的使用者。AzureADMultipleOrgs：任何組織Microsoft Entra 租使用者（多租使用者）中具有Microsoft公司或學校帳戶的使用者。AzureADandPersonalMicrosoftAccount：具有個人Microsoft帳戶的使用者，或任何組織Microsoft Entra 租使用者中的公司或學校帳戶。PersonalMicrosoftAccount：只有個人Microsoft帳戶的使用者。 | string （ReadOnly） |
| tags | 可用來分類和識別服務主體的自定義字串。 不可為 Null | string[] |
| tokenEncryptionKeyId | 從keyCredentials集合指定公鑰的keyId。 設定時，Microsoft Entra ID 會使用此屬性所指定的密鑰來發行此應用程式加密的令牌。 接收加密權杖的應用程式程式碼必須先使用對應的私密金鑰來將權杖解密，才能將該權杖用於登入的使用者。 | 字串 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| type | 資源類型 | 'Microsoft.Graph/servicePrincipals' （ReadOnly） |
| verifiedPublisher | 指定連結至此服務主體之應用程式的已驗證發行者。 | MicrosoftGraphVerifiedPublisher （ReadOnly） |
MicrosoftGraphKeyValue
| 名稱 | 描述 | 值 |
|---|---|---|
| key | 索引鍵/值組的索引鍵。 | 字串 |
| value | 機碼/值組的值。 | 字串 |
MicrosoftGraphAddIn
| 名稱 | 描述 | 值 |
|---|---|---|
| id | addIn 物件的唯一標識碼。 | 字串 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| 內容 | 索引鍵/值組的集合，定義取用服務可以使用或呼叫的參數。 您必須在 addIns 集合上執行 POST 或 PATCH 作業時指定這個屬性。 必要。 | MicrosoftGraphKeyValue[] |
| type | 應用程式所公開之功能的唯一名稱。 | 字串 |
MicrosoftGraphAppRole
| 名稱 | 描述 | 值 |
|---|---|---|
| allowedMemberTypes | 指定此應用程式角色是否可以指派給使用者和群組（藉由將 ['User']] 設定為 ['User']）、其他應用程式的 （藉由設定為 ['Application'] 或兩者 （藉由設定為 ['User'， 'Application']]。 支援指派給其他應用程式服務主體的應用程式角色也稱為應用程式許可權。 應用程式實體上定義的應用程式角色僅支援 『Application』 值。 | string[] |
| description | 應用程式角色的描述。 當應用程式角色被指派時，如果應用程式角色在同意體驗期間作為應用程式許可權，就會顯示此專案。 | 字串 |
| displayName | 顯示在應用程式角色指派和同意體驗中之許可權的顯示名稱。 | 字串 |
| id | appRoles 集合內的唯一角色標識符。 建立新的應用程式角色時，必須提供新的 GUID 識別碼。 | 字串 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| isEnabled | 建立或更新應用程式角色時，這必須設定為 true（這是預設值）。 若要刪除角色，這必須先設定為 false。 此時，在後續的呼叫中，可能會移除此角色。 | bool |
| origin | 指定應用程式角色是否定義於應用程式物件或 servicePrincipal 實體上。 不得包含在任何 POST 或 PATCH 要求中。 唯讀。 | string （ReadOnly） |
| value | 指定要包含在標識元令牌中角色宣告中的值，以及驗證指派的用戶或服務主體的存取令牌。 長度不得超過 120 個字元。 允許的字元為 ： 。 # $ % & ' ( ) * + , -. / : ;= ? @ [ ] ^ + _ { } ~，以及範圍 0-9、A-Z 和 a-z 中的字元。 不允許任何其他字元，包括空格符。 可能不是以 .開頭。 | 字串 |
MicrosoftGraphInformationalUrl
| 名稱 | 描述 | 值 |
|---|---|---|
| logoUrl | 應用程式標誌的 CDN URL，唯讀的。 | string （ReadOnly） |
| marketingUrl | 連結至應用程式的行銷頁面。 例如，https://www.contoso.com/app/marketing | 字串 |
| privacyStatementUrl | 連結至應用程式的隱私聲明。 例如，https://www.contoso.com/app/privacy | 字串 |
| supportUrl | 連結至應用程式的支持頁面。 例如，https://www.contoso.com/app/support | 字串 |
| termsOfServiceUrl | 連結至應用程式的服務條款語句。 例如，https://www.contoso.com/app/termsofservice | 字串 |
MicrosoftGraphKeyCredential
| 名稱 | 描述 | 值 |
|---|---|---|
| customKeyIdentifier | 可用來識別認證的 40 個字元二進位類型。 選擇性。 在承載中未提供時，預設為憑證的指紋。 | 字串 |
| displayName | 索引鍵的易記名稱，長度上限為 90 個字元。 接受較長的值，但已縮短。 選擇性。 | 字串 |
| endDateTime | 認證到期的日期和時間。 DateTimeOffset 類型代表使用 ISO 8601 格式的日期和時間資訊，且一律為 UTC 時間。 例如，2014 年 1 月 1 日午夜 UTC 是 2014-01-01T00：00：00Z。 | 字串 |
| key | 位元組數位中憑證的原始資料已轉換成Base64字串。 從.cer憑證中，您可以使用 Convert.ToBase64String（） 方法來讀取密鑰。 如需詳細資訊，請參閱取得憑證金鑰。 | 字串 |
| keyId | 金鑰的唯一識別碼 （GUID）。 | 字串 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| startDateTime | 認證生效的日期和時間。Timestamp 類型代表使用 ISO 8601 格式的日期和時間資訊，且一律為 UTC 時間。 例如，2014 年 1 月 1 日午夜 UTC 是 2014-01-01T00：00：00Z。 | 字串 |
| type | 金鑰認證的類型;例如 Symmetric、AsymmetricX509Cert。 | 字串 |
| 用法 | 字串，描述可以使用密鑰的目的;例如，驗證。 | 字串 |
MicrosoftGraphPermissionScope
| 名稱 | 描述 | 值 |
|---|---|---|
| adminConsentDescription | 代表所有使用者授與許可權的系統管理員所要讀取之委派許可權的描述。 此文字會出現在全租用戶系統管理員同意體驗中。 | 字串 |
| adminConsentDisplayName | 許可權的標題，是要由系統管理員代表所有使用者授與許可權的讀取。 | 字串 |
| id | 資源應用程式所定義委派許可權集合內的唯一委派許可權標識符。 | 字串 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| isEnabled | 當您建立或更新許可權時，此屬性必須設定為 true（這是預設值）。 若要刪除許可權，必須先將此屬性設定為 false。 此時，在後續呼叫中，可能會移除許可權。 | bool |
| type | 可能的值為：使用者和系統管理員。指定是否應該將此委派許可權視為安全，讓非系統管理員使用者代表自己同意，或是否一律需要系統管理員同意。 雖然 Microsoft Graph 會定義每個許可權的預設同意需求，但租用戶系統管理員可能會覆寫其組織中的行為（允許、限制或限制使用者同意此委派的許可權）。 如需詳細資訊，請參閱設定使用者同意應用程式的方式。 | 字串 |
| userConsentDescription | 委派許可權的描述，這是使用者代表自己授與許可權時所要讀取的。 此文字會出現在使用者只代表自己同意的同意體驗中。 | 字串 |
| userConsentDisplayName | 許可權的標題，是要由使用者代表自己授與許可權來讀取。 此文字會出現在使用者只代表自己同意的同意體驗中。 | 字串 |
| value | 指定要包含在存取令牌中 scp （scope） 宣告中的值。 長度不得超過 120 個字元。 允許的字元為 ： 。 # $ % & ' ( ) * + , -. / : ;= ? @ [ ] ^ + _ { } ~，以及範圍 0-9、A-Z 和 a-z 中的字元。 不允許任何其他字元，包括空格符。 可能不是以 .開頭。 | 字串 |
MicrosoftGraphPasswordCredential
| 名稱 | 描述 | 值 |
|---|---|---|
| displayName | 密碼的易記名稱。 選擇性。 | 字串 |
| endDateTime | 使用 ISO 8601 格式表示之密碼到期的日期和時間，且一律為 UTC 時間。 例如，2014 年 1 月 1 日午夜 UTC 是 2014-01-01T00：00：00Z。 選擇性。 | 字串 |
| hint | 包含密碼的前三個字元。 唯讀。 | string （ReadOnly） |
| keyId | 密碼的唯一標識碼。 | 字串 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| secretText | 唯讀;包含Microsoft Entra標識符所產生的強密碼，長度為 16-64 個字元。 產生的密碼值只會在初始 POST 要求期間傳回 addPassword。 未來無法擷取此密碼。 | string （ReadOnly） |
| startDateTime | 密碼生效的日期和時間。 Timestamp 類型代表使用 ISO 8601 格式的日期和時間資訊，且一律為 UTC 時間。 例如，2014 年 1 月 1 日午夜 UTC 是 2014-01-01T00：00：00Z。 選擇性。 | 字串 |
MicrosoftGraphResourceSpecificPermission
| 名稱 | 描述 | 值 |
|---|---|---|
| description | 描述資源特定許可權所代表的存取層級。 | 字串 |
| displayName | 資源特定許可權的顯示名稱。 | 字串 |
| id | 資源特定應用程式許可權的唯一標識符。 | 字串 約束： 最小長度 = 36 最大長度 = 36 Pattern = ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$ |
| isEnabled | 指出是否啟用許可權。 | bool |
| value | 許可權的值。 | 字串 |
MicrosoftGraphSamlSingleSignOnSettings
| 名稱 | 描述 | 值 |
|---|---|---|
| relayState | 服務提供者會在完成單一登錄流程之後，重新導向至的相對 URI。 | 字串 |
MicrosoftGraphVerifiedPublisher
| 名稱 | 描述 | 值 |
|---|---|---|
| addedDateTime | 第一次新增或最近更新已驗證發行者時的時間戳。 | 字串 |
| displayName | 來自應用程式發行者合作夥伴中心帳戶的已驗證發行者名稱。 | 字串 |
| verifiedPublisherId | 來自應用程式發行者的合作夥伴中心帳戶中已驗證發行者的標識碼。 | 字串 |