通过

创建 internalDomainFederation

  • 项目

命名空间：microsoft.graph

重要

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

创建新的 internalDomainFederation 对象。

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

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

权限

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

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Domain.ReadWrite.All 不可用。
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 Domain.ReadWrite.All 不可用。

重要

此方法存在 已知权限问题 ，可能需要同意委派方案的 Directory.AccessAsUser.All 权限。

重要

在具有工作或学校帐户的委托方案中，必须为登录用户分配受支持的Microsoft Entra角色或具有支持的角色权限的自定义角色。 此操作支持以下最低特权角色。

  • 域名管理员
  • 外部标识提供者管理员
  • 混合标识管理员
  • 安全管理员

HTTP 请求

POST /domains/{domainsId}/federationConfiguration

请求标头

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

请求正文

在请求正文中，提供 internalDomainFederation 对象的 JSON 表示形式。

创建 internalDomainFederation 时，可以指定以下属性。

属性 类型 说明
activeSignInUri String 使用 Microsoft Entra ID 中为单一登录设置的联合域进行身份验证时活动客户端使用的终结点的 URL。 对应于 Set-MsolDomainFederationSettings MSOnline v1 PowerShell cmdlet 的 ActiveLogOnUri 属性。
displayName String 联合标识提供者的显示名称。
federatedIdpMfaBehavior federatedIdpMfaBehavior 确定当联合用户访问受需要 MFA 的条件访问策略管理的应用程序时，Microsoft Entra ID是否接受联合 IdP 执行的 MFA。 可能的值包括 acceptIfMfaDoneByFederatedIdp、enforceMfaByFederatedIdp、rejectMfaByFederatedIdp、unknownFutureValue。 有关详细信息，请参阅 federatedIdpMfaBehavior 值。
isSignedAuthenticationRequestRequired 布尔值 如果为 true，则当 SAML 身份验证请求发送到联合 SAML IDP 时，Microsoft Entra ID使用 OrgID 签名密钥对这些请求进行签名。 如果 false (默认) ，则不会对发送到联合 IDP 的 SAML 身份验证请求进行签名。
issuerUri String 联合服务器的颁发者 URI。
metadataExchangeUri String 用于从富客户端应用程序进行身份验证的元数据交换终结点的 URI。
nextSigningCertificate String 主签名证书过期时用于对令牌进行签名的回退令牌签名证书。 格式为联合 IdP 令牌签名证书的公共部分的 Base 64 编码字符串。 需要与 X509Certificate2 类兼容。 与 signingCertificate 非常类似，如果在自动注册更新之外需要滚动更新、正在设置新的联合身份验证服务，或者在更新联合身份验证服务证书后联合身份验证属性中不存在新的令牌签名证书，则使用 nextSigningCertificate 属性。
passiveSignInUri String 登录Microsoft Entra服务时，基于 Web 的客户端定向到的 URI。
passwordResetUri String 客户端重定向到以重置其密码的 URI。
preferredAuthenticationProtocol authenticationProtocol 首选身份验证协议。 必须显式配置此参数，联合被动身份验证流才能正常工作。 可能的值包括 wsFed、saml、unknownFutureValue。
promptLoginBehavior promptLoginBehavior 设置登录提示的首选行为。 可能的值包括 translateToFreshPasswordAuthentication、nativeSupport、disabled、unknownFutureValue。
signingCertificate String 用于对传递到Microsoft 标识平台的令牌进行签名的当前证书。 证书的格式设置为联合 IdP 令牌签名证书的公共部分的 Base 64 编码字符串，并且必须与 X509Certificate2 类兼容。
此属性在以下方案中使用：
  • 如果在自动注册更新之外需要滚动更新
  • 正在设置新的联合身份验证服务
  • 如果在更新联合身份验证服务证书后联合身份验证属性中不存在新的令牌签名证书。
    Microsoft Entra ID通过自动注册过程更新证书，在该过程中，它尝试在当前证书到期前 30 天从联合身份验证服务元数据中检索新证书。 如果新证书不可用，Microsoft Entra ID每天监视元数据，并在新证书可用时更新域的联合设置。
    		•
    signOutUri String 客户端注销Microsoft Entra服务时重定向到的 URI。 对应于 Set-MsolDomainFederationSettings MSOnline v1 PowerShell cmdlet 的LogOffUri 属性。
    signingCertificateUpdateStatus signingCertificateUpdateStatus 提供签名证书上次更新的状态和时间戳。

    注意

    自 2024 年 3 月 30 日起，Azure AD 和 MSOnline PowerShell 模块已弃用。 若要了解详细信息，请阅读 弃用更新。 在此日期之后，对这些模块的支持仅限于Microsoft Graph PowerShell SDK 和安全修补程序的迁移帮助。 弃用的模块将继续运行到 2025 年 3 月 30 日。

    建议迁移到 Microsoft Graph PowerShell，以便与以前的 Azure AD) Microsoft Entra ID (交互。 有关常见的迁移问题，请参阅 迁移常见问题解答。 注意： MSOnline 1.0.x 版可能会在 2024 年 6 月 30 日之后遇到中断。

    federatedIdpMfaBehavior 值

    成员 说明
    acceptIfMfaDoneByFederatedIdp Microsoft Entra ID接受联合标识提供者执行的 MFA。 如果联合标识提供者未执行 MFA，Microsoft Entra ID执行 MFA。
    enforceMfaByFederatedIdp Microsoft Entra ID接受联合标识提供者执行的 MFA。 如果联合标识提供者未执行 MFA，它会将请求重定向到联合标识提供者以执行 MFA。
    rejectMfaByFederatedIdp Microsoft Entra ID始终执行 MFA 并拒绝联合标识提供者执行的 MFA。

    注意：federatedIdpMfaBehavior 是 Set-MsolDomainFederationSettings MSOnline v1 PowerShell cmdlet 的 SupportsMfa 属性的演变版本。

    • 不支持在 federatedIdpMfaBehavior 和 SupportsMfa 之间切换。
    • 设置 federatedIdpMfaBehavior 属性后，Microsoft Entra ID将忽略 SupportsMfa 设置。
    • 如果从未设置 federatedIdpMfaBehavior 属性，Microsoft Entra ID继续遵循 SupportsMfa 设置。
    • 如果未设置 federatedIdpMfaBehavior 和 SupportsMfa，Microsoft Entra ID默认为acceptIfMfaDoneByFederatedIdp行为。

    响应

    如果成功，此方法在 201 Created 响应正文中返回响应代码和 internalDomainFederation 对象。

    示例

    请求

    POST https://graph.microsoft.com/beta/domains/contoso.com/federationConfiguration
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.internalDomainFederation",
  "displayName": "Contoso",
  "issuerUri": "http://contoso.com/adfs/services/trust",
  "metadataExchangeUri": "https://sts.contoso.com/adfs/services/trust/mex",
  "signingCertificate": "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI",
  "passiveSignInUri": "https://sts.contoso.com/adfs/ls",
  "preferredAuthenticationProtocol": "wsFed",
  "activeSignInUri": "https://sts.contoso.com/adfs/services/trust/2005/usernamemixed",
  "signOutUri": "https://sts.contoso.com/adfs/ls",
  "promptLoginBehavior": "nativeSupport",
  "isSignedAuthenticationRequestRequired": true,
  "nextSigningCertificate": "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI",
  "federatedIdpMfaBehavior": "rejectMfaByFederatedIdp",
  "passwordResetUri": "https://sts.contoso.com/adfs/passwordReset"
}

    响应

    注意：为了提高可读性，可能缩短了此处显示的响应对象。

    HTTP/1.1 201 Created
Content-Type: application/json

{
  "@odata.type": "#microsoft.graph.internalDomainFederation",
  "id": "6601d14b-d113-8f64-fda2-9b5ddda18ecc",
   "displayName": "Contoso",
   "issuerUri": "http://contoso.com/adfs/services/trust",
   "metadataExchangeUri": "https://sts.contoso.com/adfs/services/trust/mex",
   "signingCertificate": "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI",
   "passiveSignInUri": "https://sts.contoso.com/adfs/ls",
   "preferredAuthenticationProtocol": "wsFed",
   "activeSignInUri": "https://sts.contoso.com/adfs/services/trust/2005/usernamemixed",
   "signOutUri": "https://sts.contoso.com/adfs/ls",
   "promptLoginBehavior": "nativeSupport",
   "isSignedAuthenticationRequestRequired": true,
   "nextSigningCertificate": "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI",
   "signingCertificateUpdateStatus": {
        "certificateUpdateResult": "Success",
        "lastRunDateTime": "2021-08-25T07:44:46.2616778Z"
    },
   "federatedIdpMfaBehavior": "rejectMfaByFederatedIdp",
   "passwordResetUri": "https://sts.contoso.com/adfs/passwordReset"
}