更新 servicePrincipal

命名空间:microsoft.graph

重要

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

更新 servicePrincipal 对象的属性。

重要

不支持使用 PATCH 设置 passwordCredential。 使用 addPasswordremovePassword 方法更新 servicePrincipal 的密码或密钥。

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) Application.ReadWrite.All Directory.ReadWrite.All
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 Application.ReadWrite.OwnedBy Application.ReadWrite.All、Directory.ReadWrite.All

注意

  • 更新 customSecurityAttributes 属性:
    • 在委派方案中,必须为管理员分配 属性分配管理员 角色,并且应用授予 CustomSecAttributeAssignment.ReadWrite.All 委托权限。
    • 在使用 Microsoft Graph 权限的仅限应用方案中,必须向应用授予 CustomSecAttributeAssignment.ReadWrite.All 应用程序权限。

HTTP 请求

可以使用服务主体 IDappId 来寻址服务主体。 idappId 在 Microsoft Entra 管理中心 中的应用注册中分别称为“对象 ID”和“应用程序 (客户端) ID”。

PATCH /servicePrincipals/{id}
PATCH /servicePrincipals(appId='{appId}')

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Content-Type application/json. 必需。

请求正文

在请求正文中,提供应更新的相关字段的值。 请求正文中未包含的现有属性会保留其以前的值,或者根据对其他属性值的更改重新计算。 为了实现最佳性能,不得添加未变化的现有值。

属性 类型 说明
accountEnabled Boolean 如果服务主体帐户已启用,则为 true;否则,为 false
addIns addIn 定义使用服务可用于调用特定上下文中的应用的自定义行为。 例如,呈现文件流的应用程序可能会为其“FileHandler”功能设置 addIns 属性。 这样,Microsoft 365 等服务就可以在用户正在处理的文档上下文中调用应用程序。
alternativeNames 字符串集合 用于按订阅、标识资源组和托管标识的完整资源 ID 检索服务主体。
appRoleAssignmentRequired Boolean 指定在Microsoft Entra ID向应用程序颁发用户或访问令牌之前是否需要用户或组的 appRoleAssignment。 不可为 null。
appRoles appRole 集合 关联应用程序公开的应用程序角色。 有关详细信息,请参阅应用程序资源上的 appRoles 属性定义。 不可为空。
customSecurityAttributes customSecurityAttributeValue 保留分配给目录对象的自定义安全属性的值的开放式复杂类型。
  • 若要在委托方案中更新此属性,必须为调用主体分配“属性分配管理员”角色,并且应用被授予 CustomSecAttributeAssignment.ReadWrite.All 委托权限。
  • 若要在仅限应用的情况下使用 Microsoft Graph 权限更新此属性,必须向应用授予 CustomSecAttributeAssignment.ReadWrite.All 应用程序权限。
  • displayName String 服务主体的显示名称。
    homepage String 应用程序的主页或登录页面。
    keyCredentials keyCredential 集合 与服务帐户关联的密钥凭据集合。 不可为 null。
    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授权服务将使用的 URL,以便使用前端、后端通道或 SAML 注销协议注销用户。
    notificationEmailAddresses 字符串集合 指定在活动证书接近到期日期时,Microsoft Entra ID发送通知的电子邮件地址列表。 这仅适用于用于对 Microsoft Entra 库应用程序颁发的 SAML 令牌进行签名的证书。
    publishedPermissionScopes permissionScope 集合 关联应用程序的 OAuth 2.0 权限。 有关详细信息,请参阅应用程序资源上的 oauth2PermissionScopes 属性定义。 不可为 null。
    preferredSingleSignOnMode string 指定为此应用程序配置的单一登录模式。 Microsoft Entra ID使用首选的单一登录模式从 Microsoft 365 或 Microsoft Entra 我的应用启动应用程序。 支持的值有 password、saml、external 和 oidc。
    preferredTokenSigningKeyEndDateTime DateTimeOffset 指定用于令牌签名的 keyCredential 的到期日期,由 preferredTokenSigningKeyThumbprint 标记。
    preferredTokenSigningKeyThumbprint String 仅供内部使用。 请勿写入或以其他方式依赖此属性。 可能会在未来版本中删除。
    publisherName String 在其中指定关联应用程序的租户的显示名称。
    replyUrls String 集合 向其发送用户令牌以使用关联应用程序登录的 URL,或者为关联应用程序向其发送 OAuth 2.0 authorization 代码和访问令牌的重定向 URL。 不可为 null。
    samlSingleSignOnSettings samlSingleSignOnSettings 有关 saml 单一登录的设置的集合。
    servicePrincipalNames 字符串集合 包含从关联的应用程序中复制的 identifiersUris 列表。 可以将其他值添加到混合应用程序。 这些值可用于标识此应用在Microsoft Entra ID中公开的权限。 例如,
    • 请求对此资源的权限的客户端应用可以使用这些 URI 在其应用程序清单的 requiredResourceAccess 属性中或在应用注册体验的“API 权限”边栏选项卡中指定所需的权限。
    • 客户端应用可以指定一个资源 URI,该 URI 基于此属性的值来获取访问令牌,即在“aud”声明中返回的 URI。

    需要多值属性筛选器表达式的 any 运算符。 不可为空。
    标记 String 集合 不可为空。
    tokenEncryptionKeyId String 指定 keyCredentials 集合中的公共密钥的 keyId。 配置后,Microsoft Entra ID为此应用程序颁发使用此属性指定的密钥加密的令牌。 接收加密令牌的应用程序代码必须先使用匹配的私钥来解密该令牌,然后才能将该令牌用于登录用户。

    响应

    如果成功,此方法在响应正文中返回 204 No Content 响应代码和更新的 servicePrincipal 对象。

    示例

    示例 1:更新指定服务主体的属性

    请求

    以下示例显示了一个请求。

    PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
    Content-type: application/json
    
    {
      "appRoleAssignmentRequired": true
    }
    

    响应

    以下示例显示了相应的响应。 注意:为了提高可读性,可能缩短了此处显示的响应对象。

    HTTP/1.1 204 No Content
    

    示例 2:将具有字符串值的自定义安全属性分配给服务主体

    下面的示例演示如何将具有字符串值的自定义安全属性分配给服务主体。

    • 属性集: Engineering
    • 属性:ProjectDate
    • 属性数据类型:字符串
    • 属性值: "2022-10-01"

    若要分配自定义安全属性,必须为调用主体分配"属性分配管理员"角色,并且必须授予CustomSecAttributeAssignment.ReadWrite.All 权限。

    有关用户的其他类似示例,请参阅示例:使用Microsoft 图形 API分配、更新、列出或删除自定义安全属性分配

    请求

    PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
    Content-type: application/json
    
    {
        "customSecurityAttributes":
        {
            "Engineering":
            {
                "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
                "ProjectDate":"2022-10-01"
            }
        }
    }
    

    响应

    HTTP/1.1 204 No Content