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 )。 筛选器值区分大小写。 |
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中公开的权限。 例如,
需要多值属性筛选器表达式的 any 运算符。 不可为 null。 支持 $filter (eq 、not 、ge 、le 、startsWith )。 |
servicePrincipalType | String | 标识服务主体是表示应用程序还是托管标识。 这是由内部Microsoft Entra ID设置的。 对于表示应用程序的服务主体,此选项设置为“Application”。 对于表示 托管标识 的服务主体,将其设置为 ManagedIdentity。 SocialIdp类型供内部使用。 |
signInAudience | String | 指定当前应用程序支持的 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。 只读。 可为 Null。 支持 $expand 和 $filter (/$count eq 0 、 /$count ne 0 、 /$count eq 1 ) /$count ne 1 。 |
remoteDesktopSecurityConfiguration | remoteDesktopSecurityConfiguration | 应用于此服务主体的 remoteDesktopSecurityConfiguration 对象。 支持 $filter isRemoteDesktopProtocolEnabled 属性的 (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"}
}