Update x509CertificateAuthenticationMethodConfiguration

아티클
04/04/2024

Namespace: microsoft.graph

Update the properties of the X.509 certificate authentication method.

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)	Policy.ReadWrite.AuthenticationMethod	Not available.
Delegated (personal Microsoft account)	Not supported.	Not supported.
Application	Policy.ReadWrite.AuthenticationMethod	Not available.

Important

In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role with a supported role permission. Authentication Policy Administrator is the least privileged role supported for this operation.

HTTP request

PATCH /policies/authenticationMethodsPolicy/authenticationMethodConfigurations/x509Certificate

Request headers

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

Request body

The following properties can be updated.

Property	Type	Description
state	authenticationMethodState	The possible values are: `enabled`, `disabled`. Inherited from authenticationMethodConfiguration.
certificateUserBindings	x509CertificateUserBinding collection	Defines fields in the X.509 certificate that map to attributes of the Microsoft Entra user object in order to bind the certificate to the user. The priority of the object determines the order in which the binding is carried out. The first binding that matches will be used and the rest ignored.
authenticationModeConfiguration	x509CertificateAuthenticationModeConfiguration	Defines strong authentication configurations. This configuration includes the default authentication mode and the different rules for strong authentication bindings.

Note: The @odata.type property with a value of #microsoft.graph.x509CertificateAuthenticationMethodConfiguration must be included in the body.

Response

If successful, this method returns a 204 No Content response code. It doesn't return anything in the response body.

Examples

Request

The following is an example of an update request with the following settings:

Enables the x509 certificate authentication method in the tenant.
Configures only one user binding between the certificate PrincipalName and the Microsoft Entra ID onPremisesUserPrincipalName properties.
Defines multi-factor authentication as requirement.
Configures the binding rules for the strong authentication method against the rule type.

PATCH https://graph.microsoft.com/v1.0/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/x509Certificate
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.x509CertificateAuthenticationMethodConfiguration",
    "id": "X509Certificate",
    "state": "enabled",
    "certificateUserBindings": [
        {
            "x509CertificateField": "PrincipalName",
            "userProperty": "onPremisesUserPrincipalName",
            "priority": 1
        }
    ],
    "authenticationModeConfiguration": {
        "x509CertificateAuthenticationDefaultMode": "x509CertificateMultiFactor",
        "rules": [
            {
                "x509CertificateRuleType": "issuerSubject",
                "identifier": "CN=ContosoCA,DC=Contoso,DC=org ",
                "x509CertificateAuthenticationMode": "x509CertificateMultiFactor"
            },
            {
                "x509CertificateRuleType": "policyOID",
                "identifier": "1.2.3.4",
                "x509CertificateAuthenticationMode": "x509CertificateMultiFactor"
            }
        ]
    },
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "isRegistrationRequired": false
        }
    ]
}


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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new X509CertificateAuthenticationMethodConfiguration
{
	OdataType = "#microsoft.graph.x509CertificateAuthenticationMethodConfiguration",
	Id = "X509Certificate",
	State = AuthenticationMethodState.Enabled,
	CertificateUserBindings = new List<X509CertificateUserBinding>
	{
		new X509CertificateUserBinding
		{
			X509CertificateField = "PrincipalName",
			UserProperty = "onPremisesUserPrincipalName",
			Priority = 1,
		},
	},
	AuthenticationModeConfiguration = new X509CertificateAuthenticationModeConfiguration
	{
		X509CertificateAuthenticationDefaultMode = X509CertificateAuthenticationMode.X509CertificateMultiFactor,
		Rules = new List<X509CertificateRule>
		{
			new X509CertificateRule
			{
				X509CertificateRuleType = X509CertificateRuleType.IssuerSubject,
				Identifier = "CN=ContosoCA,DC=Contoso,DC=org ",
				X509CertificateAuthenticationMode = X509CertificateAuthenticationMode.X509CertificateMultiFactor,
			},
			new X509CertificateRule
			{
				X509CertificateRuleType = X509CertificateRuleType.PolicyOID,
				Identifier = "1.2.3.4",
				X509CertificateAuthenticationMode = X509CertificateAuthenticationMode.X509CertificateMultiFactor,
			},
		},
	},
	IncludeTargets = new List<AuthenticationMethodTarget>
	{
		new AuthenticationMethodTarget
		{
			TargetType = AuthenticationMethodTargetType.Group,
			Id = "all_users",
			IsRegistrationRequired = false,
		},
	},
};

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

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



mgc policies authentication-methods-policy authentication-method-configurations patch --authentication-method-configuration-id {authenticationMethodConfiguration-id} --body '{\
    "@odata.type": "#microsoft.graph.x509CertificateAuthenticationMethodConfiguration",\
    "id": "X509Certificate",\
    "state": "enabled",\
    "certificateUserBindings": [\
        {\
            "x509CertificateField": "PrincipalName",\
            "userProperty": "onPremisesUserPrincipalName",\
            "priority": 1\
        }\
    ],\
    "authenticationModeConfiguration": {\
        "x509CertificateAuthenticationDefaultMode": "x509CertificateMultiFactor",\
        "rules": [\
            {\
                "x509CertificateRuleType": "issuerSubject",\
                "identifier": "CN=ContosoCA,DC=Contoso,DC=org ",\
                "x509CertificateAuthenticationMode": "x509CertificateMultiFactor"\
            },\
            {\
                "x509CertificateRuleType": "policyOID",\
                "identifier": "1.2.3.4",\
                "x509CertificateAuthenticationMode": "x509CertificateMultiFactor"\
            }\
        ]\
    },\
    "includeTargets": [\
        {\
            "targetType": "group",\
            "id": "all_users",\
            "isRegistrationRequired": false\
        }\
    ]\
}\
'

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



// Code snippets are only available for the latest major version. Current major version is $v1.*

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

requestBody := graphmodels.NewAuthenticationMethodConfiguration()
id := "X509Certificate"
requestBody.SetId(&id) 
state := graphmodels.ENABLED_AUTHENTICATIONMETHODSTATE 
requestBody.SetState(&state) 


x509CertificateUserBinding := graphmodels.NewX509CertificateUserBinding()
x509CertificateField := "PrincipalName"
x509CertificateUserBinding.SetX509CertificateField(&x509CertificateField) 
userProperty := "onPremisesUserPrincipalName"
x509CertificateUserBinding.SetUserProperty(&userProperty) 
priority := int32(1)
x509CertificateUserBinding.SetPriority(&priority) 

certificateUserBindings := []graphmodels.X509CertificateUserBindingable {
	x509CertificateUserBinding,
}
requestBody.SetCertificateUserBindings(certificateUserBindings)
authenticationModeConfiguration := graphmodels.NewX509CertificateAuthenticationModeConfiguration()
x509CertificateAuthenticationDefaultMode := graphmodels.X509CERTIFICATEMULTIFACTOR_X509CERTIFICATEAUTHENTICATIONMODE 
authenticationModeConfiguration.SetX509CertificateAuthenticationDefaultMode(&x509CertificateAuthenticationDefaultMode) 


x509CertificateRule := graphmodels.NewX509CertificateRule()
x509CertificateRuleType := graphmodels.ISSUERSUBJECT_X509CERTIFICATERULETYPE 
x509CertificateRule.SetX509CertificateRuleType(&x509CertificateRuleType) 
identifier := "CN=ContosoCA,DC=Contoso,DC=org "
x509CertificateRule.SetIdentifier(&identifier) 
x509CertificateAuthenticationMode := graphmodels.X509CERTIFICATEMULTIFACTOR_X509CERTIFICATEAUTHENTICATIONMODE 
x509CertificateRule.SetX509CertificateAuthenticationMode(&x509CertificateAuthenticationMode) 
x509CertificateRule1 := graphmodels.NewX509CertificateRule()
x509CertificateRuleType := graphmodels.POLICYOID_X509CERTIFICATERULETYPE 
x509CertificateRule1.SetX509CertificateRuleType(&x509CertificateRuleType) 
identifier := "1.2.3.4"
x509CertificateRule1.SetIdentifier(&identifier) 
x509CertificateAuthenticationMode := graphmodels.X509CERTIFICATEMULTIFACTOR_X509CERTIFICATEAUTHENTICATIONMODE 
x509CertificateRule1.SetX509CertificateAuthenticationMode(&x509CertificateAuthenticationMode) 

rules := []graphmodels.X509CertificateRuleable {
	x509CertificateRule,
	x509CertificateRule1,
}
authenticationModeConfiguration.SetRules(rules)
requestBody.SetAuthenticationModeConfiguration(authenticationModeConfiguration)


authenticationMethodTarget := graphmodels.NewAuthenticationMethodTarget()
targetType := graphmodels.GROUP_AUTHENTICATIONMETHODTARGETTYPE 
authenticationMethodTarget.SetTargetType(&targetType) 
id := "all_users"
authenticationMethodTarget.SetId(&id) 
isRegistrationRequired := false
authenticationMethodTarget.SetIsRegistrationRequired(&isRegistrationRequired) 

includeTargets := []graphmodels.AuthenticationMethodTargetable {
	authenticationMethodTarget,
}
requestBody.SetIncludeTargets(includeTargets)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
authenticationMethodConfigurations, err := graphClient.Policies().AuthenticationMethodsPolicy().AuthenticationMethodConfigurations().ByAuthenticationMethodConfigurationId("authenticationMethodConfiguration-id").Patch(context.Background(), requestBody, nil)

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


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

X509CertificateAuthenticationMethodConfiguration authenticationMethodConfiguration = new X509CertificateAuthenticationMethodConfiguration();
authenticationMethodConfiguration.setOdataType("#microsoft.graph.x509CertificateAuthenticationMethodConfiguration");
authenticationMethodConfiguration.setId("X509Certificate");
authenticationMethodConfiguration.setState(AuthenticationMethodState.Enabled);
LinkedList<X509CertificateUserBinding> certificateUserBindings = new LinkedList<X509CertificateUserBinding>();
X509CertificateUserBinding x509CertificateUserBinding = new X509CertificateUserBinding();
x509CertificateUserBinding.setX509CertificateField("PrincipalName");
x509CertificateUserBinding.setUserProperty("onPremisesUserPrincipalName");
x509CertificateUserBinding.setPriority(1);
certificateUserBindings.add(x509CertificateUserBinding);
authenticationMethodConfiguration.setCertificateUserBindings(certificateUserBindings);
X509CertificateAuthenticationModeConfiguration authenticationModeConfiguration = new X509CertificateAuthenticationModeConfiguration();
authenticationModeConfiguration.setX509CertificateAuthenticationDefaultMode(X509CertificateAuthenticationMode.X509CertificateMultiFactor);
LinkedList<X509CertificateRule> rules = new LinkedList<X509CertificateRule>();
X509CertificateRule x509CertificateRule = new X509CertificateRule();
x509CertificateRule.setX509CertificateRuleType(X509CertificateRuleType.IssuerSubject);
x509CertificateRule.setIdentifier("CN=ContosoCA,DC=Contoso,DC=org ");
x509CertificateRule.setX509CertificateAuthenticationMode(X509CertificateAuthenticationMode.X509CertificateMultiFactor);
rules.add(x509CertificateRule);
X509CertificateRule x509CertificateRule1 = new X509CertificateRule();
x509CertificateRule1.setX509CertificateRuleType(X509CertificateRuleType.PolicyOID);
x509CertificateRule1.setIdentifier("1.2.3.4");
x509CertificateRule1.setX509CertificateAuthenticationMode(X509CertificateAuthenticationMode.X509CertificateMultiFactor);
rules.add(x509CertificateRule1);
authenticationModeConfiguration.setRules(rules);
authenticationMethodConfiguration.setAuthenticationModeConfiguration(authenticationModeConfiguration);
LinkedList<AuthenticationMethodTarget> includeTargets = new LinkedList<AuthenticationMethodTarget>();
AuthenticationMethodTarget authenticationMethodTarget = new AuthenticationMethodTarget();
authenticationMethodTarget.setTargetType(AuthenticationMethodTargetType.Group);
authenticationMethodTarget.setId("all_users");
authenticationMethodTarget.setIsRegistrationRequired(false);
includeTargets.add(authenticationMethodTarget);
authenticationMethodConfiguration.setIncludeTargets(includeTargets);
AuthenticationMethodConfiguration result = graphClient.policies().authenticationMethodsPolicy().authenticationMethodConfigurations().byAuthenticationMethodConfigurationId("{authenticationMethodConfiguration-id}").patch(authenticationMethodConfiguration);

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


const options = {
	authProvider,
};

const client = Client.init(options);

const authenticationMethodConfiguration = {
    '@odata.type': '#microsoft.graph.x509CertificateAuthenticationMethodConfiguration',
    id: 'X509Certificate',
    state: 'enabled',
    certificateUserBindings: [
        {
            x509CertificateField: 'PrincipalName',
            userProperty: 'onPremisesUserPrincipalName',
            priority: 1
        }
    ],
    authenticationModeConfiguration: {
        x509CertificateAuthenticationDefaultMode: 'x509CertificateMultiFactor',
        rules: [
            {
                x509CertificateRuleType: 'issuerSubject',
                identifier: 'CN=ContosoCA,DC=Contoso,DC=org ',
                x509CertificateAuthenticationMode: 'x509CertificateMultiFactor'
            },
            {
                x509CertificateRuleType: 'policyOID',
                identifier: '1.2.3.4',
                x509CertificateAuthenticationMode: 'x509CertificateMultiFactor'
            }
        ]
    },
    includeTargets: [
        {
            targetType: 'group',
            id: 'all_users',
            isRegistrationRequired: false
        }
    ]
};

await client.api('/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/x509Certificate')
	.update(authenticationMethodConfiguration);

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


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\X509CertificateAuthenticationMethodConfiguration;
use Microsoft\Graph\Generated\Models\AuthenticationMethodState;
use Microsoft\Graph\Generated\Models\X509CertificateUserBinding;
use Microsoft\Graph\Generated\Models\X509CertificateAuthenticationModeConfiguration;
use Microsoft\Graph\Generated\Models\X509CertificateAuthenticationMode;
use Microsoft\Graph\Generated\Models\X509CertificateRule;
use Microsoft\Graph\Generated\Models\X509CertificateRuleType;
use Microsoft\Graph\Generated\Models\AuthenticationMethodTarget;
use Microsoft\Graph\Generated\Models\AuthenticationMethodTargetType;


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

$requestBody = new X509CertificateAuthenticationMethodConfiguration();
$requestBody->setOdataType('#microsoft.graph.x509CertificateAuthenticationMethodConfiguration');
$requestBody->setId('X509Certificate');
$requestBody->setState(new AuthenticationMethodState('enabled'));
$certificateUserBindingsX509CertificateUserBinding1 = new X509CertificateUserBinding();
$certificateUserBindingsX509CertificateUserBinding1->setX509CertificateField('PrincipalName');
$certificateUserBindingsX509CertificateUserBinding1->setUserProperty('onPremisesUserPrincipalName');
$certificateUserBindingsX509CertificateUserBinding1->setPriority(1);
$certificateUserBindingsArray []= $certificateUserBindingsX509CertificateUserBinding1;
$requestBody->setCertificateUserBindings($certificateUserBindingsArray);

$authenticationModeConfiguration = new X509CertificateAuthenticationModeConfiguration();
$authenticationModeConfiguration->setX509CertificateAuthenticationDefaultMode(new X509CertificateAuthenticationMode('x509CertificateMultiFactor'));
$rulesX509CertificateRule1 = new X509CertificateRule();
$rulesX509CertificateRule1->setX509CertificateRuleType(new X509CertificateRuleType('issuerSubject'));
$rulesX509CertificateRule1->setIdentifier('CN=ContosoCA,DC=Contoso,DC=org ');
$rulesX509CertificateRule1->setX509CertificateAuthenticationMode(new X509CertificateAuthenticationMode('x509CertificateMultiFactor'));
$rulesArray []= $rulesX509CertificateRule1;
$rulesX509CertificateRule2 = new X509CertificateRule();
$rulesX509CertificateRule2->setX509CertificateRuleType(new X509CertificateRuleType('policyOID'));
$rulesX509CertificateRule2->setIdentifier('1.2.3.4');
$rulesX509CertificateRule2->setX509CertificateAuthenticationMode(new X509CertificateAuthenticationMode('x509CertificateMultiFactor'));
$rulesArray []= $rulesX509CertificateRule2;
$authenticationModeConfiguration->setRules($rulesArray);

$requestBody->setAuthenticationModeConfiguration($authenticationModeConfiguration);
$includeTargetsAuthenticationMethodTarget1 = new AuthenticationMethodTarget();
$includeTargetsAuthenticationMethodTarget1->setTargetType(new AuthenticationMethodTargetType('group'));
$includeTargetsAuthenticationMethodTarget1->setId('all_users');
$includeTargetsAuthenticationMethodTarget1->setIsRegistrationRequired(false);
$includeTargetsArray []= $includeTargetsAuthenticationMethodTarget1;
$requestBody->setIncludeTargets($includeTargetsArray);


$result = $graphServiceClient->policies()->authenticationMethodsPolicy()->authenticationMethodConfigurations()->byAuthenticationMethodConfigurationId('authenticationMethodConfiguration-id')->patch($requestBody)->wait();

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


Import-Module Microsoft.Graph.Identity.SignIns

$params = @{
	"@odata.type" = "#microsoft.graph.x509CertificateAuthenticationMethodConfiguration"
	id = "X509Certificate"
	state = "enabled"
	certificateUserBindings = @(
		@{
			x509CertificateField = "PrincipalName"
			userProperty = "onPremisesUserPrincipalName"
			priority = 
		}
	)
	authenticationModeConfiguration = @{
		x509CertificateAuthenticationDefaultMode = "x509CertificateMultiFactor"
		rules = @(
			@{
				x509CertificateRuleType = "issuerSubject"
				identifier = "CN=ContosoCA,DC=Contoso,DC=org "
				x509CertificateAuthenticationMode = "x509CertificateMultiFactor"
			}
			@{
				x509CertificateRuleType = "policyOID"
				identifier = "1.2.3.4"
				x509CertificateAuthenticationMode = "x509CertificateMultiFactor"
			}
		)
	}
	includeTargets = @(
		@{
			targetType = "group"
			id = "all_users"
			isRegistrationRequired = $false
		}
	)
}

Update-MgPolicyAuthenticationMethodPolicyAuthenticationMethodConfiguration -AuthenticationMethodConfigurationId $authenticationMethodConfigurationId -BodyParameter $params

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.x509_certificate_authentication_method_configuration import X509CertificateAuthenticationMethodConfiguration
from msgraph.generated.models.authentication_method_state import AuthenticationMethodState
from msgraph.generated.models.x509_certificate_user_binding import X509CertificateUserBinding
from msgraph.generated.models.x509_certificate_authentication_mode_configuration import X509CertificateAuthenticationModeConfiguration
from msgraph.generated.models.x509_certificate_authentication_mode import X509CertificateAuthenticationMode
from msgraph.generated.models.x509_certificate_rule import X509CertificateRule
from msgraph.generated.models.x509_certificate_rule_type import X509CertificateRuleType
from msgraph.generated.models.authentication_method_target import AuthenticationMethodTarget
from msgraph.generated.models.authentication_method_target_type import AuthenticationMethodTargetType
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = X509CertificateAuthenticationMethodConfiguration(
	odata_type = "#microsoft.graph.x509CertificateAuthenticationMethodConfiguration",
	id = "X509Certificate",
	state = AuthenticationMethodState.Enabled,
	certificate_user_bindings = [
		X509CertificateUserBinding(
			x509_certificate_field = "PrincipalName",
			user_property = "onPremisesUserPrincipalName",
			priority = 1,
		),
	],
	authentication_mode_configuration = X509CertificateAuthenticationModeConfiguration(
		x509_certificate_authentication_default_mode = X509CertificateAuthenticationMode.X509CertificateMultiFactor,
		rules = [
			X509CertificateRule(
				x509_certificate_rule_type = X509CertificateRuleType.IssuerSubject,
				identifier = "CN=ContosoCA,DC=Contoso,DC=org ",
				x509_certificate_authentication_mode = X509CertificateAuthenticationMode.X509CertificateMultiFactor,
			),
			X509CertificateRule(
				x509_certificate_rule_type = X509CertificateRuleType.PolicyOID,
				identifier = "1.2.3.4",
				x509_certificate_authentication_mode = X509CertificateAuthenticationMode.X509CertificateMultiFactor,
			),
		],
	),
	include_targets = [
		AuthenticationMethodTarget(
			target_type = AuthenticationMethodTargetType.Group,
			id = "all_users",
			is_registration_required = False,
		),
	],
)

result = await graph_client.policies.authentication_methods_policy.authentication_method_configurations.by_authentication_method_configuration_id('authenticationMethodConfiguration-id').patch(request_body)

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

Response

HTTP/1.1 204 No Content

다음을 통해 공유

Update x509CertificateAuthenticationMethodConfiguration

Permissions

HTTP request

Request headers

Request body

Response

Examples

Request

Response

피드백

추가 리소스