通过

servicePrincipal 资源类型

命名空间：microsoft.graph

重要

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

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

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

Methods

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

属性

重要

仅当使用设置为 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 关联应用程序公开的显示名称。 最大长度为 256 个字符。
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）。 筛选器值区分大小写。
  • 若要读取此属性，必须为调用应用分配 CustomSecAttributeAssignment.Read.All 权限。 若要编写此属性，必须为调用应用分配 CustomSecAttributeAssignment.ReadWrite.All 权限。
  • 若要在委派方案中读取或写入此属性，必须为管理员分配 属性分配管理员 角色。
    		•
    deletedDateTime DateTimeOffset 删除服务主体的日期和时间。 只读。
    description 字符串 免费文本字段，提供面向内部最终用户的服务主体说明。 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。 注意： 此字段可能 null 适用于较旧的 SAML 应用和未自动设置的 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。
    claimsPolicy customClaimsPolicy 声明策略，允许应用程序管理员自定义将在受此策略影响的令牌中发出的声明。
    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。 支持 $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",
  "verifiedPublisher": {"@odata.type": "microsoft.graph.verifiedPublisher"}
}