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. You do not need to set this property if you are using machine authentication with managed workloads (with VENs installed).
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 creating 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]

Request Parameter

Parameter	Description
`distinguished_name`	The X.509 Subject distinguished name is 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]

Request Parameters

Parameter	Description
`machine_auth`	An optional boolean flag is used to enable machine authentication for the rule. When set to true, machine authentication is enabled for the rule.
`sec_connect`	An optional boolean flag is used to enable SecureConnect (host-to-host traffic encryption) for the rule.

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,
    "consumers": [{
        "actors": "ams"
    }],
    "consuming_security_principals": [],
    "unscoped_consumers": false,
    "description": "",      
    "ingress_services": [{"proto": 6}],       
    "resolve_labels_as": {
      "providers": ["workloads"],
      "consumers": ["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, "consumers":[{"actors":"ams"}],"consuming_security_principals":[], "ingress_services": [{"proto": 6}], unscoped_consumers":false, "description":","resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]},"enabled":true,"machine_auth":true"}'"consumers":[{"actors":"ams"}],"consuming_security_principals":[], "ingress_services": [{"proto": 6}], unscoped_consumers":false, "description":","resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]},"enabled":true,"machine_auth":true"}'

REST APIs for 23.5