servicePrincipal 资源类型

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

表示目录中的一个应用程序实例。 继承自 directoryObject。

该资源支持通过提供 delta 函数使用增量查询跟踪增量添加、删除和更新。 此资源是允许传入其他属性的开放类型。

Methods

方法 返回类型 说明
List servicePrincipals servicePrincipal 集合 检索 servicePrincipal 对象列表。
创建 servicePrincipal servicePrincipal 创建一个新的 servicePrincipal 对象。
Get servicePrincipal servicePrincipal 读取 servicePrincipal 对象的属性和关系。
更新 servicePrincipal 无 更新 servicePrincipal 对象。
Upsert servicePrincipal servicePrincipal 创建新的 servicePrincipal（如果不存在），或更新现有 servicePrincipal 的属性。
删除 servicePrincipal 无 删除 servicePrincipal 对象。
列出已删除的 servicePrincipal directoryObject 集合 检索最近删除的 servicePrincipal 对象的列表。
获取已删除的 servicePrincipal directoryObject 检索最近删除的 servicePrincipal 对象的属性。
永久删除 servicePrincipal 无 永久删除 servicePrincipal 对象。
还原已删除的 servicePrincipal directoryObject 还原最近删除的 servicePrincipal 对象。
List createdObjects directoryObject 集合 获取 createdObject 对象集合。
List ownedObjects directoryObject collection 获取 ownedObject 对象集合。
delta servicePrincipal 集合 获取服务主体的增量更改。
创建 remoteDesktopSecurityConfiguration remoteDesktopSecurityConfiguration 在 servicePrincipal 上创建新的 remoteDesktopSecurityConfiguration 对象。
获取 remoteDesktopSecurityConfiguration remoteDesktopSecurityConfiguration 获取 servicePrincipal 上的 remoteDesktopSecurityConfiguration 对象。
删除 remoteDesktopSecurityConfiguration 无 删除 servicePrincipal 上的 remoteDesktopSecurityConfiguration 对象。
应用角色分配
列出 appRoleAssignments appRoleAssignment 集合 获取此服务主体分配的应用角色。
添加 appRoleAssignment appRoleAssignment 向此服务主体分配一个应用角色。
删除 appRoleAssignment 无 从此服务主体中删除一个应用角色分配。
列出 appRoleAssignedTo appRoleAssignment 集合 获取用户、组和服务主体为此服务主体分配的应用角色。
添加 appRoleAssignedTo appRoleAssignment 向用户、组或服务主体分配此服务主体的应用角色。
移除 appRoleAssignedTo 无 从用户、组或服务主体中移除此服务主体的应用角色分配。
证书和密码
添加密码 passwordCredential 将强密码或机密添加到 servicePrincipal。
添加 tokenSigningCertificate selfSignedCertificate 向服务主体添加自签名证书。 主要用于从 Microsoft Entra 库中配置基于 SAML 的 SSO 应用程序。
删除密码 passwordCredential 从 servicePrincipal 中删除密码或机密。
加号键 keyCredential 向 servicePrincipal 添加密钥凭据。
删除键 无 从 servicePrincipal 中移除密钥凭据。
委派权限分类
列出委派权限分类 delegatedPermissionClassification 集合 获取此服务主体公开的委派权限的权限分类。
添加委派权限分类 delegatedPermissionClassification 添加此服务主体公开的委派权限的权限分类。
删除委派权限分类 无 删除此服务主体公开的委派权限的权限分类。
委派权限授予
List oauth2PermissionGrants oAuth2PermissionGrant 集合 获取授权此服务主体代表已登录用户访问 API 的委派权限授予。
Membership
List memberOf directoryObject 集合 从 memberOf 导航属性中获取此服务主体是其直接成员的组。
列出 transitive memberOf directoryObject 集合 列出此服务主体所属的组。 此操作是可传递的，并包括此服务主体以嵌套方式所属的组。
checkMemberGroups String 集合 检查指定组列表中的成员身份。
checkMemberObjects String 集合 检查组、目录角色或管理单元对象指定列表中的成员身份。
getMemberGroups String 集合 获取此服务主体所属的组列表。
getMemberObjects String collection 获取此服务主体所属的组、管理单元和目录角色的列表。
Owners
List owners directoryObject 集合 获取服务主体的所有者。
添加所有者 directoryObject 将所有者分配到服务主体。 服务主体所有者可以是用户或其他服务主体。
Remove owner 无 从服务主体中删除所有者。 作为建议的最佳做法，服务主体应至少具有两个所有者。
策略
分配 claimsMappingPolicy claimsMappingPolicy 集合 向此对象分配 claimsMappingPolicy。
列出 claimsMappingPolicies claimsMappingPolicy 集合 为此对象分配的 claimsMappingPolicies。
删除 claimsMappingPolicy claimsMappingPolicy 集合 从此对象中移除 claimsMappingPolicy。
分配 homeRealmDiscoveryPolicy homeRealmDiscoveryPolicy 集合 向此对象分配 homeRealmDiscoveryPolicy。
列出 homeRealmDiscoveryPolicy homeRealmDiscoveryPolicy 集合 为此对象分配的 homeRealmDiscoveryPolicies。
删除 homeRealmDiscoveryPolicy homeRealmDiscoveryPolicy 集合 从此对象中删除 homeRealmDiscoveryPolicy。
分配 tokenIssuancePolicy tokenIssuancePolicy 集合 分配 tokenIssuancePolicy 至此对象。
列出 tokenIssuancePolicies tokenIssuancePolicy 集合 获取已分配至此对象的所有 tokenIssuancePolicies。
删除 tokenIssuancePolicy tokenIssuancePolicy 集合 从此对象中删除 tokenIssuancePolicy。
分配 tokenLifetimePolicy tokenLifetimePolicy 集合 向此对象分配 tokenLifetimePolicy。
列出 tokenLifetimePolicies tokenLifetimePolicy 集合 获取已分配至此对象的所有 tokenLifetimePolicies。
删除 tokenLifetimePolicy tokenLifetimePolicy 集合 从此对象中删除 tokenLifetimePolicy。
List permissionGrantPreApprovalPolicy permissionGrantPreApprovalPolicy 集合 获取分配给此对象的 permissionGrantPreApprovalPolicy。
Assign permissionGrantPreApprovalPolicy permissionGrantPreApprovalPolicy 集合 为此对象分配 permissionGrantPreApprovalPolicy。
Remove permissionGrantPreApprovalPolicy permissionGrantPreApprovalPolicy 集合 从此对象中删除 permissionGrantPreApprovalPolicy。
单一登录
createPasswordSingleSignOnCredentials passwordSingleSignOnCredentialSet 为正文中指定的用户或组创建凭据集。
getPasswordSingleSignOnCredentials passwordSingleSignOnCredentialSet 为正文中指定的用户或组获取凭据集。
updatePasswordSingleSignOnCredentials 无 为正文中指定的用户或组更新凭据集。
deletePasswordSingleSignOnCredentials 无 删除正文中指定的用户或组的凭据集。

属性

重要

仅当使用设置为 eventual 和 $count 的 ConsistencyLevel 标头时，才支持 $filter 和 $search 查询参数的特定用法。 有关详细信息，请参阅 目录对象的高级查询功能。

属性 类型 说明
accountEnabled Boolean 如果已启用服务主体帐户，则为 true；否则，为 false。 如果设置为 false，则任何用户都无法登录到此应用，即使他们已分配到此应用。 支持 $filter（eq、ne、not、in）。
addIns addIn 集合 定义使用服务可用于调用特定上下文中的应用的自定义行为。 例如，呈现文件流的应用程序可能会为其“FileHandler”功能设置 addIns 属性。 这样，Microsoft 365 等服务就可以在用户正在处理的文档上下文中调用应用程序。
alternativeNames 字符串集合 用于按订阅检索服务主体，标识 托管标识的资源组和完整资源 ID。 支持 $filter（eq、not、ge、le、startsWith）。
应用说明 String 相关应用程序公开的说明。
appDisplayName String 关联应用程序公开的显示名称。
appId String 关联应用程序的唯一标识符（其 appId 属性）。 备用键。 支持 $filter （eq、 ne、 not、 in、 startsWith）。
applicationTemplateId String applicationTemplate 的唯一标识符。 支持 $filter（eq、not、ne）。 此为只读属性。 null 如果应用不是从应用程序模板创建的，则为 。
appOwnerOrganizationId Guid 包含在其中注册应用程序的租户 ID。 这仅适用于应用程序支持的服务主体。 支持 $filter（eq、ne、NOT、ge、le）。
appRoleAssignmentRequired 布尔 指定在用户登录或应用可以获取令牌前，是否需要先向用户或其他服务主体授予此服务主体的应用角色分配。 默认值为 false。 不可为空。

支持 $filter（eq、ne、NOT）。
appRoles appRole 集合 此服务主体表示的应用程序公开的角色。 有关详细信息，请参阅应用程序实体上的 appRoles 属性定义。 不可为空。
customSecurityAttributes customSecurityAttributeValue 保留分配给目录对象的自定义安全属性的值的开放式复杂类型。 可为 NULL。

仅在 $select 上返回。 支持 $filter （eq、 ne、 not、 startsWith）。 筛选器值区分大小写。
deletedDateTime DateTimeOffset 删除服务主体的日期和时间。 只读。
说明 字符串 免费文本字段，提供面向内部最终用户的服务主体说明。 MyApps 等最终用户门户在此字段中显示应用程序说明。 允许的最大大小为 1,024 个字符。 支持 $filter（eq、ne、not、ge、le、startsWith）和 $search。
disabledByMicrosoftStatus String 指定 Microsoft 是否已禁用已注册应用程序。 可能值是：null (默认值)、NotDisabled 和 DisabledDueToViolationOfServicesAgreement (原因可能包括可疑、滥用或恶意活动，或违反 Microsoft 服务协议)。

支持 $filter（eq、ne、not）。
displayName String 服务主体的显示名称。 支持 $filter（eq、ne、not、ge、le、in、startsWith 和 null 值上的 eq）、$search 和 $orderby。
errorUrl String 已弃用。 请勿使用。
homepage String 应用程序的主页或登录页面。
id String 服务主体的唯一标识符。 继承自 directoryObject。 键。 不可为 null。 只读。 支持 $filter （eq、 ne、 not、 in）。
info informationalUrl 所获取应用程序的基本配置文件信息，如应用的市场营销、支持、服务条款和隐私声明 URL。 服务条款和隐私声明通过用户同意体验展示给用户。 有关详细信息，请参阅如何：为已注册Microsoft Entra应用添加服务条款和隐私声明。

支持 $filter（eq、ne、not、ge、le 和 null 值上的 eq）。
keyCredentials keyCredential 集合 与服务帐户关联的密钥凭据集合。 不可为 null。 支持 $filter（eq、not、ge、le）。
loginUrl String 指定服务提供商将用户重定向到Microsoft Entra ID进行身份验证的 URL。 Microsoft Entra ID使用 URL 从 Microsoft 365 或Microsoft Entra 我的应用启动应用程序。 如果为空，Microsoft Entra ID对配置了基于 SAML 的单一登录的应用程序执行 IdP 发起的登录。 用户从 Microsoft 365、Microsoft Entra 我的应用或Microsoft Entra SSO URL 启动应用程序。
logoutUrl String 指定 Microsoft 授权服务使用 OpenId Connect 前端通道、 后通道或 SAML 注销协议注销用户的 URL。
notes String 免费文本字段，用于捕获有关服务主体的信息，通常用于操作。 允许的最大大小为 1,024 个字符。
notificationEmailAddresses 字符串集合 指定在活动证书接近到期日期时，Microsoft Entra ID发送通知的电子邮件地址列表。 这仅适用于用于对 Microsoft Entra 库应用程序颁发的 SAML 令牌进行签名的证书。
passwordCredentials passwordCredential 集合 与服务帐户关联的密码凭据集合。 不可为 null。
passwordSingleSignOnSettings passwordSingleSignOnSettings 有关密码单一登录的设置的集合。 使用 $select=passwordSingleSignOnSettings 读取属性。 对 applicationTemplates（自定义 applicationTemplates 除外）只读。
preferredSingleSignOnMode string 指定为此应用程序配置的单一登录模式。 Microsoft Entra ID使用首选的单一登录模式从 Microsoft 365 或 Microsoft Entra 我的应用启动应用程序。 支持的值是：password、saml、notSupported 和 oidc。
permissionGrantPreApprovalPolicies permissionGrantPreApprovalPolicy 集合 已分配给服务主体的预批准策略列表。
preferredTokenSigningKeyEndDateTime DateTimeOffset 指定用于令牌签名的 keyCredential 的到期日期，由 preferredTokenSigningKeyThumbprint 标记。 当前不支持更新此属性。 有关详细信息，请参阅 ServicePrincipal 属性差异。
preferredTokenSigningKeyThumbprint String 此属性可用于 SAML 应用程序 (将 preferredSingleSignOnMode 设置为 saml) 的应用，以控制用于对 SAML 响应进行签名的证书。 对于不是 SAML 的应用程序，请勿写入或以其他方式依赖此属性。
publishedPermissionScopes permissionScope 集合 应用程序公开的委派权限。 有关详细信息，请参阅应用程序实体的 api 属性上的 oauth2PermissionScopes 属性。 不可为 null。
注意： 此属性在 v1.0 中命名为 oauth2PermissionScopes。
publisherName String 发布应用程序的Microsoft Entra租户的名称。
replyUrls String 集合 向其发送用户令牌以使用关联应用程序登录的 URL，或者为关联应用程序向其发送 OAuth 2.0 authorization 代码和访问令牌的重定向 URL。 不可为空。
samlMetadataUrl String 服务用于公开联合身份验证的 SAML 元数据的 URL。
samlSingleSignOnSettings samlSingleSignOnSettings 有关 saml 单一登录的设置的集合。
servicePrincipalNames 字符串集合 包含从关联的应用程序中复制的 identifiersUris 列表。 可以向混合应用程序添加更多值。 这些值可用于标识此应用在Microsoft Entra ID中公开的权限。 例如，
  • 客户端应用可以指定一个资源 URI，该 URI 基于此属性的值来获取访问令牌，即在“aud”声明中返回的 URI。

需要多值属性筛选器表达式的 any 运算符。 不可为 null。

支持 $filter（eq、not、ge、le、startsWith）。
servicePrincipalType String 标识服务主体是表示应用程序还是托管标识。 这是由内部Microsoft Entra ID设置的。 对于表示应用程序的服务主体，此选项设置为“Application”。 对于表示 托管标识 的服务主体，将其设置为 ManagedIdentity。 SocialIdp类型供内部使用。
signInAudience String 指定当前应用程序支持的 Microsoft 帐户。 只读。

支持的值为：
  • AzureADMyOrg：在组织的Microsoft Entra租户中具有 Microsoft 工作或学校帐户的用户 (单租户) 。
  • AzureADMultipleOrgs：在任何组织的Microsoft Entra租户中具有 Microsoft 工作或学校帐户的用户 (多租户) 。
  • AzureADandPersonalMicrosoftAccount：在任何组织的Microsoft Entra租户中具有 Microsoft 个人帐户或工作或学校帐户的用户。
  • PersonalMicrosoftAccount：仅限拥有个人 Microsoft 帐户的用户。
tags 字符串集合 可用于分类和标识服务主体的自定义字符串。 不可为 null。 值是此处和关联 应用程序 实体的 tags 属性上设置的字符串的并集。

支持 $filter（eq、not、ge、le、startsWith）。
tokenEncryptionKeyId String 指定 keyCredentials 集合中的公共密钥的 keyId。 配置后，Microsoft Entra ID为此应用程序颁发使用此属性指定的密钥加密的令牌。 接收加密令牌的应用程序代码必须先使用匹配的私钥来解密该令牌，然后才能将该令牌用于登录用户。
verifiedPublisher verifiedPublisher 指定链接到此服务主体的应用程序的已验证发布者。

关系

重要

仅当使用设置为 eventual 和 $count的 ConsistencyLevel 标头时，才支持查询参数的特定用法$filter。 有关详细信息，请参阅 目录对象的高级查询功能。

关系 类型 说明
appManagementPolicies appManagementPolicy 集合 应用到此服务主体的 appManagementPolicy。
appRoleAssignedTo appRoleAssignment 此应用或服务的应用角色分配，已授予用户、组和其他服务主体。支持 $expand。
appRoleAssignments appRoleAssignment 集合 另一个应用或服务的应用角色分配，已授予此服务主体的。 支持 $expand。
claimsMappingPolicies claimsMappingPolicy 集合 为此服务主体分配的 claimsMappingPolicies。 支持 $expand。
createdObjects directoryObject 集合 此服务主体所创建的目录对象。 只读。 可为 Null。
delegatedPermissionClassifications delegatedPermissionClassification 集合 此服务主体公开的委派权限的权限分类。 支持 $expand。
endpoints endpoint 集合 可供发现的终结点。 Sharepoint 等服务使用特定于租户的 SharePoint 终结点填充此属性，其他应用程序可以在他们的体验中发现并使用这些终结点。
homeRealmDiscoveryPolicies homeRealmDiscoveryPolicy 集合 为此服务主体分配的 homeRealmDiscoveryPolicies。 支持 $expand。
memberOf directoryObject 集合 此服务主体所属的角色。 HTTP 方法：GET 只读。 可为空。 支持 $expand。
oauth2PermissionGrants oAuth2PermissionGrant 集合 授权此服务主体代表已登录用户访问 API 的委派权限授予。 只读。 可为 Null。
ownedObjects directoryObject 集合 此服务主体所拥有的目录对象。 只读。 可为 NULL。 支持 $expand 和 $filter (/$count eq 0、 /$count ne 0、 /$count eq 1) /$count ne 1 。
owners directoryObject 集合 servicePrincipal 所述的目录对象。 所有者是一组允许修改此对象的非管理员用户或 servicePrincipal。 此为只读属性。 可为 NULL。 支持 $expand 和 $filter (/$count eq 0、 /$count ne 0、 /$count eq 1) /$count ne 1 。
remoteDesktopSecurityConfiguration remoteDesktopSecurityConfiguration 应用于此服务主体的 remoteDesktopSecurityConfiguration 对象。 支持 $filterisRemoteDesktopProtocolEnabled 属性的 (eq) 。
同步 同步 表示通过 Microsoft 图形 API Microsoft Entra标识同步的功能。
tokenIssuancePolicies tokenIssuancePolicy 集合 为此服务主体分配的 tokenIssuancePolicies。 支持 $expand。
tokenLifetimePolicies tokenLifetimePolicy 集合 为此服务主体分配的 tokenLifetimePolicies。 支持 $expand。

JSON 表示形式

以下 JSON 表示形式显示了资源类型。

{
  "accountEnabled": true,
  "addIns": [{"@odata.type": "microsoft.graph.addIn"}],
  "alternativeNames": "String",
  "appDisplayName": "String",
  "appId": "String",
  "appOwnerOrganizationId": "Guid",
  "applicationTemplateId": "String",
  "appRoleAssignmentRequired": true,
  "appRoles": [{"@odata.type": "microsoft.graph.appRole"}],
  "customSecurityAttributes": {
    "@odata.type": "microsoft.graph.customSecurityAttributeValue"
  },
  "disabledByMicrosoftStatus": "String",
  "displayName": "String",
  "errorUrl": "String",
  "homepage": "String",
  "id": "String (identifier)",
  "info": {"@odata.type": "microsoft.graph.informationalUrl"},
  "keyCredentials": [{"@odata.type": "microsoft.graph.keyCredential"}],
  "loginUrl": "String",
  "logoutUrl": "String",
  "notes": "String",
  "notificationEmailAddresses": ["String"],
  "publishedPermissionScopes": [{"@odata.type": "microsoft.graph.permissionScope"}],
  "passwordCredentials": [{"@odata.type": "microsoft.graph.passwordCredential"}],
  "passwordSingleSignOnSettings": {"@odata.type": "microsoft.graph.passwordSingleSignOnSettings"},
  "preferredSingleSignOnMode": "String",
  "preferredTokenSigningKeyEndDateTime": "DateTime",
  "preferredTokenSigningKeyThumbprint": "String",
  "publisherName": "String",
  "replyUrls": ["String"],
  "samlMetadataUrl": "String",
  "samlSingleSignOnSettings": "microsoft.DirectoryServices.SamlSingleSignOnSettings",
  "servicePrincipalNames": ["String"],
  "servicePrincipalType": "String",
  "signInAudience": "String",
  "tags": ["String"],
  "tokenEncryptionKeyId": "String",
  "useCustomTokenSigningKey": false,
  "verifiedPublisher": {"@odata.type": "microsoft.graph.verifiedPublisher"}
}