optionalClaims 资源类型

命名空间:microsoft.graph

声明应用程序请求的可选声明。 应用程序可以配置在三种类型的令牌中返回的可选声明, (ID 令牌、访问令牌、SAML 2 令牌) 它可以从安全令牌服务接收。 应用程序可以配置要在每个令牌类型中返回的不同可选声明集。 应用程序的 optionalClaims 属性是一个 optionalClaims 对象。

应用程序开发人员可以在其 Microsoft Entra 应用中配置可选声明,以指定 Microsoft 安全令牌服务发送到其应用程序的令牌中所需的声明。 有关详细信息,请参阅向 Microsoft Entra 应用提供可选声明。

属性

属性 类型 说明
accessToken optionalClaim 集合 JWT 访问令牌中返回的可选声明。
idToken optionalClaim 集合 JWT ID 令牌中返回的可选声明。
kerberosTicket optionalClaim 集合 用于控制 Kerberos 票证的组 SID 解析的可选声明。 受支持的声明名称为 groups。
saml2Token optionalClaim 集合 SAML 令牌中返回的可选声明。

要配置 kerberosTicket,请添加一个 optionalClaim ,其 名称 属性设置为 groups。 在 additionalProperties 集合中,指定以下一个或多个区分大小写的值:

  • cloud_only_group_sids:包括没有本地 SID 的组的云 SID。
  • hybrid_group_cloud_sids:包括同时保留本地 SID 的组的 Microsoft Entra 云 SID 表示形式。
  • hybrid_group_onpremises_sids:包括保留本地 SID 的组的原始本地 SID 表示形式。

组类别取决于本地 SID 和云 SID 的存在,而不是组的颁发机构来源或当前管理的位置。 可以组合这些值。 忽略服务返回的未知值。 不再支持已替代的 GA 前值hybrid_group_sidsonpremises_group_sids。

配置 kerberosTicket 的每个应用程序的 groupMembershipClaims 属性进一步限制所选 SID 类别中符合条件的成员身份:

groupMembershipClaims 值 可选的组 SID 行为
All 包括所选 SID 类别中的所有成员身份。
ApplicationGroup 仅包括分配给配置 kerberosTicket 的应用程序的组。
DirectoryRole 不包括可选的组 SID,除非与另一个受支持的组成员身份值结合使用。
SecurityGroup 仅包括所选 SID 类别中启用安全机制的组。

客户端应用程序和资源应用程序可以各自配置 kerberosTicket。 当两者都进行配置时,返回的 SID 是两个应用程序请求的 SID 类别和合格成员身份的联合。

对于混合用户,强制本地 PAC Groups 投影继续包括所有适用的本地组。 groupMembershipClaims 设置仅限定通过 kerberosTicket 选择的可选组 SID 类别的范围。

在 更新应用程序之前,请阅读其现有的 optionalClaims 配置。 使用应用程序的对象 ID,而不是其应用程序 (客户端) ID,并发送完整的 optionalClaims 对象,因为该属性使用写入时替换语义。 保留所有令牌声明集合中的现有条目。

以下配置包括没有本地 SID 的启用安全功能的组的云 SID,以及保留一个 SID 的启用安全功能的组的原始本地 SID。 此示例假定应用程序未配置其他可选声明。

{
  "groupMembershipClaims": "SecurityGroup",
  "optionalClaims": {
    "accessToken": [],
    "idToken": [],
    "kerberosTicket": [
      {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": [
          "cloud_only_group_sids",
          "hybrid_group_onpremises_sids"
        ]
      }
    ],
    "saml2Token": []
  }
}

要清除 Kerberos 配置,请将 kerberosTicket 设置为空集合,同时保留其他令牌声明集合。 当 kerberosTicket 不存在或为空时,应用服务的默认 Kerberos 组解析行为。

关系

无。

JSON 表示形式

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

{
  "idToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
  "accessToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
  "kerberosTicket": [{"@odata.type": "microsoft.graph.optionalClaim"}],
  "saml2Token": [{"@odata.type": "microsoft.graph.optionalClaim"}]
}