Machine Authentication

This Public Experimental API allows you to configure unmanaged workloads and rules for machine authentication in case you configured the PCE to use machine authentication.

Before you start writing rules, you need to complete the following tasks:

Configure an unmanaged (no VEN) workload that you want to use machine authentication on with the client certificate X.509 Subject distinguished name (distinguished_name) issued from the CA. If you are using machine authentication with managed workloads (with VENs installed), you do not need to set this property.
Configure rules for machine authentication by setting the machine_auth flag to true on each rule. You can also optionally set SecureConnect (sec_connect) if you want the traffic data to be encrypted using IPsec.

Once you have done these two tasks, you can use these unmanaged workloads in machine authentication-based rules.

Configure Machine Authentication

The machine authentication workload property for the certificate distinguished name is required for those hosts or systems where you have not installed a VEN, such a laptop or other server whose IP address is unknown or changes often.

You can set the distinguished_name when you first create (POST) the unmanaged workload, which is passed in the JSON request payload.

Note

For information on how to create an unmanaged workload, see Create an Unmanaged Workload.

URI to Configure Machine Authentication on an Unmanaged Workload

Use this URI to configure machine authentication when you create a new unmanaged workload:

POST [api_version][org_href]/workloads

If you want to enable machine authentication on an existing unmanaged workload, you need to know the workload HREF, which can be obtained from the command GET on a collection of Workloads.

The workload HREF is highlighted in blue:

/orgs/7/workloads/XXXXXXX-9611-44aa-ae06-fXXX8903db65

Use this URI to configure machine authentication for an existing unmanaged workload:

PUT [api_version][workload_href]

Parameters

distinguished_name

The X.509 Subject distinguished name, used if you want this unmanaged workload to use machine authentication when communicating with other hosts.

Request Body

{ 
   "distinguished_name": "CN=ACCVRAIZ1, OU=PKIACCV, O=ACCV, C=ES" 
}

Curl Command Enable Machine Authentication

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/7/workloads/XXXXXXX-9611-44aa-ae06-fXXX8903db65 -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"distinguished_name": "CN=ACCVRAIZ1, OU=PKIACCV, O=ACCV, C=ES"}'

Configure Machine Authentication on Rule

For a rule to use machine authentication, you need to configure it on the rule when you create or update it.

URI to Configure Machine Authentication for a Rule

Use this URI to configure machine authentication for a new rule:

POST [api_version][rule_set_href]/sec_rules

If you want to enable machine authentication on an existing rule, you need to know the HREF of the rule. For example:

/orgs/3/sec_policy/draft/rule_sets/152/sec_rules/124

Use this URI to configure machine authentication for an existing rule:

PUT [api_version][sec_rule_href]

Parameters for sec_policy_rule_sets_sec_rules_post

Parameter	Description	Type	Required
`href`	URI of the object	String	No
`enabled`	Indicates if the rule is enabled or disabled.	Boolean	Yes
`providers`	Entities that can be used as a source in a rule	Object	Yes
`destinations`	Entities that can be used as a destination in a rule Reference to se`c_policy_rule_sets_sec_rules_destinations_put.schema.json`		Yes
`service`	URI of the associated service	Object	No
`sec_connect`	Optional boolean flag to enable SecureConnect (host-to-host traffic encryption) for the rule. A boolean flag to enable SecureConnect (host-to-host traffic encryption) for the rule.	Boolean	No
`ub_service`	URI of UB side service	Object, NULL	Yes

Properties for sec_policy_rule_sets_sec_rules_post

Property	Description	Typ	Requied
`enabled`	Indicates if the rule is enabled or disabled.	Boolean	Yes
`providers`	Entities that can be used as a source in a rule		Yes
`destinations`	Entities that can be used as a destination in a rule Reference to se`c_policy_rule_sets_sec_rules_destinations_put.schema.json`		Yes
`ingress_services`	Reference to `sec_rule_ingress_services.schema.json`		Yes
`resolve_labels_as`	Reference to `sec_rule_resolve_labels_as.schema.json`		Yes
`machine_auth`	Optional boolean flag to enable machine authentication for the rule. When set to true, machine authentication is enabled for the rule.	Boolan	No
`sec_connect`	Whether a secure connection is established		No

Request Body

This example shows the JSON payload for updating a rule to enable machine authentication, but with SecureConnect disabled.

{
    "providers": [{"label": {"href": "/orgs/1/labels/1"}}],
    "sec_connect": false,
    "destinations": [{
        "actors": "ams"
    }],
    "consuming_security_principals": [],
    "unscoped_destinations": false,
    "description": "",      
    "ingress_services": [{"proto": 6}],       
    "resolve_labels_as": {
      "providers": ["workloads"],
      "destinations": ["workloads"]
    },
    "enabled": true,
    "machine_auth": true
}

Configure Machine Authentication for Rule

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/1/sec_policy/draft/rule_sets/152/sec_rules/124 -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"providers":["{"label": {"href":"/orgs/1/labels/1"}}], "sec_connect":false, "destinations":[{"actors":"ams"}],"consuming_security_principals
":[], "ingress_services": [{"proto": 6}], unscoped_destinations":false, "description":","resolve_labels_as":{"providers":["workloads"],"destinations":["workloads"]},"enabled":true,"machine_auth":true"}'

REST APIs for 22.5