Skip to content

Latest commit

 

History

History
203 lines (165 loc) · 11.9 KB

domain-post-federationconfiguration.md

File metadata and controls

203 lines (165 loc) · 11.9 KB
Raw
title description author ms.localizationpriority ms.custom ms.subservice doc_type
Create internalDomainFederation
Create a new internalDomainFederation object.
rahul-nagraj
medium
has-azure-ad-ps-ref, azure-ad-ref-level-one-done
entra-sign-in
apiPageType

Create internalDomainFederation

Namespace: microsoft.graph

Create a new internalDomainFederation object.

[!INCLUDE national-cloud-support]

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

[!INCLUDE permissions-table]

Important

This method has a known permissions issue and might require consenting to the Directory.AccessAsUser.All permission for delegated scenarios.

[!INCLUDE rbac-domainfederation-apis-write]

HTTP request

POST /domains/{domainsId}/federationConfiguration

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, supply a JSON representation of the internalDomainFederation object.

You can specify the following properties when creating an internalDomainFederation.

Property Type Description
displayName String The display name of the federated identity provider.
issuerUri String Issuer URI of the federation server.
metadataExchangeUri String URI of the metadata exchange endpoint used for authentication from rich client applications.
signingCertificate String Current certificate used to sign tokens passed to the Microsoft identity platform. The certificate is formatted as a Base 64 encoded string of the public portion of the federated IdP's token signing certificate and must be compatible with the X509Certificate2 class.
This property is used in the following scenarios:
  • If a rollover is required outside of the autorollover update
  • A new federation service is being set up
  • If the new token signing certificate isn't present in the federation properties after the federation service certificate has been updated.
    Microsoft Entra ID updates certificates via an autorollover process in which it attempts to retrieve a new certificate from the federation service metadata, 30 days before expiry of the current certificate. If a new certificate isn't available, Microsoft Entra ID monitors the metadata daily and updates the federation settings for the domain when a new certificate is available.
    		•
    passiveSignInUri String URI that web-based clients are directed to when signing in to Microsoft Entra services.
    preferredAuthenticationProtocol authenticationProtocol Preferred authentication protocol. The possible values are: wsFed, saml, unknownFutureValue.
    activeSignInUri String URL of the endpoint used by active clients when authenticating with federated domains set up for single sign-on in Microsoft Entra ID. Corresponds to the ActiveLogOnUri property of the Set-MsolDomainFederationSettings MSOnline v1 PowerShell cmdlet.
    signOutUri String URI that clients are redirected to when they sign out of Microsoft Entra services. Corresponds to the LogOffUri property of the Set-MsolDomainFederationSettings MSOnline v1 PowerShell cmdlet.
    promptLoginBehavior promptLoginBehavior Sets the preferred behavior for the sign-in prompt. The possible values are: translateToFreshPasswordAuthentication, nativeSupport, disabled, unknownFutureValue.
    isSignedAuthenticationRequestRequired Boolean If true, when SAML authentication requests are sent to the federated SAML IDP, Microsoft Entra ID signs those requests using the OrgID signing key. If false (default), the SAML authentication requests sent to the federated IDP aren't signed.
    nextSigningCertificate String Fallback token signing certificate that is used to sign tokens when the primary signing certificate expires. Formatted as Base 64 encoded strings of the public portion of the federated IdP's token signing certificate. Needs to be compatible with the X509Certificate2 class. Much like the signingCertificate, the nextSigningCertificate property is used if a rollover is required outside of the autorollover update, a new federation service is being set up, or if the new token signing certificate isn't present in the federation properties after the federation service certificate has been updated.
    signingCertificateUpdateStatus signingCertificateUpdateStatus Provides status and timestamp of the last update of the signing certificate.
    federatedIdpMfaBehavior federatedIdpMfaBehavior Determines whether Microsoft Entra ID accepts the MFA performed by the federated IdP when a federated user accesses an application that is governed by a conditional access policy that requires MFA. The possible values are: acceptIfMfaDoneByFederatedIdp, enforceMfaByFederatedIdp, rejectMfaByFederatedIdp, unknownFutureValue. For more information, see federatedIdpMfaBehavior values.

    [!INCLUDE Azure AD PowerShell deprecation note]

    federatedIdpMfaBehavior values

    Member Description
    acceptIfMfaDoneByFederatedIdp Microsoft Entra ID accepts MFA that's performed by the federated identity provider. If the federated identity provider didn't perform MFA, Microsoft Entra ID performs the MFA.
    enforceMfaByFederatedIdp Microsoft Entra ID accepts MFA that's performed by federated identity provider. If the federated identity provider didn't perform MFA, it redirects the request to federated identity provider to perform MFA.
    rejectMfaByFederatedIdp Microsoft Entra ID always performs MFA and rejects MFA that's performed by the federated identity provider.

    Note

    federatedIdpMfaBehavior is an evolved version of the SupportsMfa property of the Set-MsolDomainFederationSettings MSOnline v1 PowerShell cmdlet.

    • Switching between federatedIdpMfaBehavior and SupportsMfa is not supported.
    • When federatedIdpMfaBehavior property is set, Microsoft Entra ID ignores the SupportsMfa setting.
    • If the federatedIdpMfaBehavior property is never set, Microsoft Entra ID will continue to honor the SupportsMfa setting.
    • If neither federatedIdpMfaBehavior nor SupportsMfa is set, Microsoft Entra ID will default to acceptIfMfaDoneByFederatedIdp behavior.

    Response

    If successful, this method returns a 201 Created response code and an internalDomainFederation object in the response body.

    Examples

    Request

    HTTP

    POST https://graph.microsoft.com/v1.0/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"
}

    C#

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    CLI

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    Go

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    Java

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    JavaScript

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    PHP

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    PowerShell

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    Python

    [!INCLUDE sample-code] [!INCLUDE sdk-documentation]

    Response

    Note: The response object shown here might be shortened for readability.

    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"
}