IDENTITY-BASED MICROSEGMENTATION DOCUMENTATION

Overview

Object types

The Microsegmentation Console API accepts and returns JSON or MessagePack encoded objects. This is controlled by the Accept and Content-Type HTTP headers.

Authentication and authorization

Most of the resources require authentication and authorization.

  • For a request to be authenticated, it must provide the Authorization HTTP header.
  • For a request to be authorized, a policy must be in place to grant you access.

Errors

When an error occurs, either due to the user input or platform error, it is returned as list of errors. Errors always have the same structure:

  • title: The title of the error
  • description: A more detailed description of the error
  • code: The status code of the error
  • trace: Trace ID that can help Palo Alto Networks engineers trace the cause of the error.
  • data: Additional opaque data related to the error.

For example:

[
  {
    "code": 422,
    "data": {
      "attribute": "name"
    },
    "description": "Attribute 'name' is required",
    "subject": "elemental",
    "title": "Validation Error",
    "trace": "4da0331d645697d6"
  }
]

The error codes follow the HTTP status codes:

  • 200 OK: The request is a success and the body contains the response.
  • 204 No content: The request is a success and there is no additional body.
  • 400 Bad Request: The data of your request is invalid or incomplete.
  • 401 Unauthorized: You are not correctly authenticated.
  • 403 Forbidden: You are authenticated, but you are not authorized.
  • 404 Not Found: The resource you try to access does not exist.
  • 415 Unsupported Media Type: Invalid Content-Type or Accept HTTP header.
  • 417 Expectation Failed: Your token quota has been exhausted.
  • 422 Unprocessable Entity: Validation error (missing required attributes, number not in range etc.)
  • 423 Locked: The API is locked for write operations during maintenance.
  • 429 Too Many Requests: You have been rate limited.
  • 500 Internal Server Error: Something wrong happened in the server
  • 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout: Temporary communication failure.

There may be additional error codes in certain circumstances. Please refer to the HTTP error code documentation for more information.

Authentication

All API calls must explicitly pass the Authorization HTTP header in the following form:

Authorization: Bearer <token>

The token is a JSON Web Token (JWT) that can be exchanged from one of the supported authentication sources:

  • Microsegmentation account: username and password.
  • App credentials: X.509 certificate.
  • User-configured OIDC provider.
  • User-configured LDAP server.

These various sources are called realms.

Regardless of the realm, the Microsegmentation Console validates the user-provided information and converts identification bits into claims that are inserted in the JWT.

Administrators can then write API authorizations based on these claims to authorize actions on various parts of the system.

Generally speaking, you need to call the /issue API in order to get a token.

curl https://api.console.aporeto.com/issue \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "realm": "<realm>",
    "validity: "24h",
    "quota": 0,
    "metadata": {<realm-specific-identification>}
  }'

The realm property can be one of:

  • Vince: Microsegmentation account
  • Certificate: Client X.509 certificate (app credentials)
  • OIDC: User-configured OIDC provider
  • LDAP: User-configured LDAP provider
  • AWSSecurityToken: ID token issued from Amazon Security Token Service
  • AzureIdentityToken: ID token issued from Azure Identity Platform.
  • GCPIdentityToken: ID token issued from Google Cloud Platform.
  • Google: ID token issued from Google Sign-in.
  • AWSIdentityDocument: This realm is deprecated.

The validity property controls how long the token will be valid. It is expressed in the Golang duration format, like 10s, 6h or 24h. By default, if you omit this value or set it to 0, the validity will be 24h.

The quota controls how many times a token can be used. Not setting this value or setting it to 0 disables quota so the token can be used as much as you like during its validity period.

The metadata attribute contains various realm-dependent information (see below).

Upon correct authentication, the Microsegmentation Console returns a JWT wrapped in a JSON or MessagePack object.

{
    "quota": 0,
    "realm": "Vince",
    "token": "<jwt>",
    "validity": "24h"
}

The token attribute contains the actual JWT you need to pass into the Authorization HTTP header for every subsequent request.

Authenticating with a Microsegmentation account

To authenticate from your Microsegmentation account, you can issue the following command.

curl https://api.console.aporeto.com/issue \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "realm": "Vince",
    "metadata": {
      "vinceAccount": "<account-name>",
      "vincePassword": "<account-password>"
    }
  }'

Authenticating with an X.509 certificate

NOTE: How to retrieve an X.509 certificate from the Microsegmentation Console is not in the scope of this document.

To use an X.509 user certificate, you must configure your client to pass it on the TLS layer.

Assuming your certificate (containing the key) is at ~/aporeto.pem, you can retrieve a token by issuing the following command:

curl https://api.console.aporeto.com/issue \
  -X POST \
  -E "~/aporeto.pem" \
  -H 'Content-Type: application/json' \
  -d '{"realm": "Certificate"}'

Namespace

Most of the resources in Microsegmentation Console live in a namespace. When you issue a command, in addition to your JWT, you must pass the X-Namespace HTTP header. This tells Microsegmentation Console which namespace the request is targeting and what API authorizations to apply.

Note that the API authorization associated with your JWT claims will depend on the namespace you target.

For instance, you may get the permission to list the namespace in /company/ns1:

curl https://api.console.aporeto.com/namespaces \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'X-Fields: name' \
  -H 'Authorization: Bearer <token>'
[
  {
    "name": "/company/ns1/myns"
  },
  {
    "name": "/company/ns1/myotherns"
  }
]

But not in the namespace /company/ns2:

curl https://api.console.aporeto.com/namespaces \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns2' \
  -H 'X-Fields: name' \
  -H 'Authorization: Bearer <token>'
[
  {
    "code": 403,
    "title":"Forbidden",
    "description": "You are not allowed to access this resource."
  }
]

Idempotency

The Microsegmentation Console API supports idempotency for POST operations. This allows you to safely retry requests that returned a communication error, but actually were honored by the system.

If you issue two subsequent POST requests with the same idempotency key, the second will return the exact same response as the first one, while it will not have done anything in the system.

The idempotency key is passed through the HTTP header Idempotency-Key. The value needs to be a unique identifier. UUID are generally widely used.

For instance, if you issue the following command twice:

curl https://api.console.aporeto.com/namespaces \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Fields: ID' \
  -d '{"name": "test-namespace-2"}'

The first will return:

{"ID":"5d2398157ddf1f3519ce6d96"}

But the second will fail:

[
  {
    "code":422,
    "title":"Duplicate Key",
    "description":"Another object exists with the same key"
  }
]

However, if you set the Idempotency-Key header and issue the following request twice:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company' \
  -H 'Idempotency-Key: abcdef1234' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Fields: ID' \
  -d '{"name": "test-namespace-2"}' \
  https://api.console.aporeto.com/issue

The first one returns:

{"ID":"5d2398157ddf1f3519ce6d96"}

The second one returns:

{"ID":"5d2398157ddf1f3519ce6d96"}

CRUD operations

Hierarchy layout

The Microsegmentation Console API follows a three-level structure to traverse the hierarchy. For instance, for a hypothetical object parent that can have children who can in turn have grandchildren, the Microsegmentation Console lays out the API URLs as follows:

  • /parents: Affects all parents.
  • /parents/:id: Affects a particular parent with the given ID.
  • /parents/:id/children: Affects all children in parent with the given ID.
  • /children: Affects all children
  • /children/:id: Affects a particular child with the given ID.
  • /children/:id/grandchildren: Affects all grandchildren in child with the given ID.

Methods

The Microsegmentation Console API uses standard HTTP methods to perform actions on resources. Not all methods apply to all URLs.

  • GET: Retrieves many or retrieve one.
  • POST: Creates a new resource.
  • PUT: Fully updates an existing resource.
  • DELETE: Deletes an existing resource.
  • HEAD: Works like a GET but it does not return any body.

Creating resources

The POST method can be used with the following resource URLs.

  • POST /parents: Creates a new parent object.
  • POST /parents/:id/children: Creates a new child under the parent with the given ID.

Example:

curl https://api.console.aporeto.com/namespaces \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'X-Fields: name' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "name": "mynamespace"
  }'

Retrieving resources

The GET (or HEAD) method can be used with the following resource URLs.

  • GET /parents: Returns all parents.
  • GET /parents/:id: Returns the parent with the given ID.
  • GET /parents/:id/children: Returns all children in the parent with given ID.

You can paginate the results using the query parameters page and pageSize. A pageSize or 0 returns the full list of objects.

Example:

curl https://api.console.aporeto.com/namespaces?page=2&pageSize=10 \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'Authorization: Bearer <token>'

Updating resources

The PUT method can only be used with the PUT /parents/:id resource URL. It updates the parent with the given ID.

Updating a resource requires you to resend the entire object, not just the parts you want to change. This ensures (especially through the updateTime property) no conflicts should two clients update the same resource at the same time.

Example:

curl https://api.console.aporeto.com/namespaces/5d07f89c7ddf1f5e0210582d \
  -X PUT \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "ID": "5d07f89c7ddf1f5e0210582d",
    "SSHCA": "",
    "SSHCAEnabled": false,
    "annotations": {},
    "associatedSSHCAID": "",
    "associatedTags": [],
    "createTime": "2019-06-17T20:31:24.681Z",
    "customZoning": false,
    "description": "Hello world",
    "localCA": "",
    "localCAEnabled": false,
    "metadata": [],
    "name": "/company/apps",
    "namespace": "/company",
    "networkAccessPolicyTags" :[],
    "normalizedTags": [
      "$identity=namespace",
      "$name=/company/apps",
      "$namespace=/company",
      "$id=5d07f89c7ddf1f5e0210582d"
    ],
    "protected": false,
    "serviceCertificateValidity": "1h",
    "updateTime": "2019-06-17T20:31:24.681Z",
    "zone": 0,
    "zoning": 0
  }'

Deleting resources

The DELETE method can only be used with the DELETE /parents/:id resource URL. It deletes the parent with the given ID.

Example:

curl https://api.console.aporeto.com/namespaces/5d07f89c7ddf1f5e0210582d \
  -X DELETE \
  -H 'Content-Type: application/json' \
  -H 'X-Namespace: /company/ns1' \
  -H 'Authorization: Bearer <token>'