Create internalDomainFederation

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Create a new internalDomainFederation object.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

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.

Permission type	Least privileged permissions	Higher privileged permissions
Delegated (work or school account)	Domain.ReadWrite.All	Not available.
Delegated (personal Microsoft account)	Not supported.	Not supported.
Application	Domain.ReadWrite.All	Not available.

Important

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

For delegated scenarios, the calling user must be assigned at least one of the following Microsoft Entra roles:

• Domain Name Administrator
• External Identity Provider Administrator
• Hybrid Identity Administrator
• Security Administrator

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.

Note

Azure AD and MSOnline PowerShell modules are deprecated as of March 30, 2024. To learn more, read the deprecation update. After this date, support for these modules are limited to migration assistance to Microsoft Graph PowerShell SDK and security fixes. The deprecated modules will continue to function through March, 30 2025.

We recommend migrating to Microsoft Graph PowerShell to interact with Microsoft Entra ID (formerly Azure AD). For common migration questions, refer to the Migration FAQ. Note: Versions 1.0.x of MSOnline may experience disruption after June 30, 2024.

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 isn't supported.
• Once federatedIdpMfaBehavior property is set, Microsoft Entra ID ignores the SupportsMfa setting.
• If the federatedIdpMfaBehavior property is never set, Microsoft Entra ID continues to honor the SupportsMfa setting.
• If neither federatedIdpMfaBehavior nor SupportsMfa is set, Microsoft Entra ID defaults 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/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"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new InternalDomainFederation
{
	OdataType = "#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 = AuthenticationProtocol.WsFed,
	ActiveSignInUri = "https://sts.contoso.com/adfs/services/trust/2005/usernamemixed",
	SignOutUri = "https://sts.contoso.com/adfs/ls",
	PromptLoginBehavior = PromptLoginBehavior.NativeSupport,
	IsSignedAuthenticationRequestRequired = true,
	NextSigningCertificate = "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI",
	FederatedIdpMfaBehavior = FederatedIdpMfaBehavior.RejectMfaByFederatedIdp,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Domains["{domain-id}"].FederationConfiguration.PostAsync(requestBody);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta domains federation-configuration create --domain-id {domain-id} --body '{\
  "@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"\
}\
'

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewInternalDomainFederation()
displayName := "Contoso"
requestBody.SetDisplayName(&displayName) 
issuerUri := "http://contoso.com/adfs/services/trust"
requestBody.SetIssuerUri(&issuerUri) 
metadataExchangeUri := "https://sts.contoso.com/adfs/services/trust/mex"
requestBody.SetMetadataExchangeUri(&metadataExchangeUri) 
signingCertificate := "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI"
requestBody.SetSigningCertificate(&signingCertificate) 
passiveSignInUri := "https://sts.contoso.com/adfs/ls"
requestBody.SetPassiveSignInUri(&passiveSignInUri) 
preferredAuthenticationProtocol := graphmodels.WSFED_AUTHENTICATIONPROTOCOL 
requestBody.SetPreferredAuthenticationProtocol(&preferredAuthenticationProtocol) 
activeSignInUri := "https://sts.contoso.com/adfs/services/trust/2005/usernamemixed"
requestBody.SetActiveSignInUri(&activeSignInUri) 
signOutUri := "https://sts.contoso.com/adfs/ls"
requestBody.SetSignOutUri(&signOutUri) 
promptLoginBehavior := graphmodels.NATIVESUPPORT_PROMPTLOGINBEHAVIOR 
requestBody.SetPromptLoginBehavior(&promptLoginBehavior) 
isSignedAuthenticationRequestRequired := true
requestBody.SetIsSignedAuthenticationRequestRequired(&isSignedAuthenticationRequestRequired) 
nextSigningCertificate := "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI"
requestBody.SetNextSigningCertificate(&nextSigningCertificate) 
federatedIdpMfaBehavior := graphmodels.REJECTMFABYFEDERATEDIDP_FEDERATEDIDPMFABEHAVIOR 
requestBody.SetFederatedIdpMfaBehavior(&federatedIdpMfaBehavior) 

federationConfiguration, err := graphClient.Domains().ByDomainId("domain-id").FederationConfiguration().Post(context.Background(), requestBody, nil)

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

InternalDomainFederation internalDomainFederation = new InternalDomainFederation();
internalDomainFederation.setOdataType("#microsoft.graph.internalDomainFederation");
internalDomainFederation.setDisplayName("Contoso");
internalDomainFederation.setIssuerUri("http://contoso.com/adfs/services/trust");
internalDomainFederation.setMetadataExchangeUri("https://sts.contoso.com/adfs/services/trust/mex");
internalDomainFederation.setSigningCertificate("MIIE3jCCAsagAwIBAgIQQcyDaZz3MI");
internalDomainFederation.setPassiveSignInUri("https://sts.contoso.com/adfs/ls");
internalDomainFederation.setPreferredAuthenticationProtocol(AuthenticationProtocol.WsFed);
internalDomainFederation.setActiveSignInUri("https://sts.contoso.com/adfs/services/trust/2005/usernamemixed");
internalDomainFederation.setSignOutUri("https://sts.contoso.com/adfs/ls");
internalDomainFederation.setPromptLoginBehavior(PromptLoginBehavior.NativeSupport);
internalDomainFederation.setIsSignedAuthenticationRequestRequired(true);
internalDomainFederation.setNextSigningCertificate("MIIE3jCCAsagAwIBAgIQQcyDaZz3MI");
internalDomainFederation.setFederatedIdpMfaBehavior(FederatedIdpMfaBehavior.RejectMfaByFederatedIdp);
InternalDomainFederation result = graphClient.domains().byDomainId("{domain-id}").federationConfiguration().post(internalDomainFederation);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const internalDomainFederation = {
  '@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'
};

await client.api('/domains/contoso.com/federationConfiguration')
	.version('beta')
	.post(internalDomainFederation);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\InternalDomainFederation;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new InternalDomainFederation();
$requestBody->setOdataType('#microsoft.graph.internalDomainFederation');
$requestBody->setDisplayName('Contoso');
$requestBody->setIssuerUri('http://contoso.com/adfs/services/trust');
$requestBody->setMetadataExchangeUri('https://sts.contoso.com/adfs/services/trust/mex');
$requestBody->setSigningCertificate('MIIE3jCCAsagAwIBAgIQQcyDaZz3MI');
$requestBody->setPassiveSignInUri('https://sts.contoso.com/adfs/ls');
$requestBody->setPreferredAuthenticationProtocol(new AuthenticationProtocol('wsFed'));
$requestBody->setActiveSignInUri('https://sts.contoso.com/adfs/services/trust/2005/usernamemixed');
$requestBody->setSignOutUri('https://sts.contoso.com/adfs/ls');
$requestBody->setPromptLoginBehavior(new PromptLoginBehavior('nativeSupport'));
$requestBody->setIsSignedAuthenticationRequestRequired(true);
$requestBody->setNextSigningCertificate('MIIE3jCCAsagAwIBAgIQQcyDaZz3MI');
$requestBody->setFederatedIdpMfaBehavior(new FederatedIdpMfaBehavior('rejectMfaByFederatedIdp'));

$result = $graphServiceClient->domains()->byDomainId('domain-id')->federationConfiguration()->post($requestBody)->wait();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement

$params = @{
	"@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"
}

New-MgBetaDomainFederationConfiguration -DomainId $domainId -BodyParameter $params

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

from msgraph import GraphServiceClient
from msgraph.generated.models.internal_domain_federation import InternalDomainFederation

graph_client = GraphServiceClient(credentials, scopes)

request_body = InternalDomainFederation(
	odata_type = "#microsoft.graph.internalDomainFederation",
	display_name = "Contoso",
	issuer_uri = "http://contoso.com/adfs/services/trust",
	metadata_exchange_uri = "https://sts.contoso.com/adfs/services/trust/mex",
	signing_certificate = "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI",
	passive_sign_in_uri = "https://sts.contoso.com/adfs/ls",
	preferred_authentication_protocol = AuthenticationProtocol.WsFed,
	active_sign_in_uri = "https://sts.contoso.com/adfs/services/trust/2005/usernamemixed",
	sign_out_uri = "https://sts.contoso.com/adfs/ls",
	prompt_login_behavior = PromptLoginBehavior.NativeSupport,
	is_signed_authentication_request_required = True,
	next_signing_certificate = "MIIE3jCCAsagAwIBAgIQQcyDaZz3MI",
	federated_idp_mfa_behavior = FederatedIdpMfaBehavior.RejectMfaByFederatedIdp,
)

result = await graph_client.domains.by_domain_id('domain-id').federation_configuration.post(request_body)

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the 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"
}