IDENTITY-BASED MICROSEGMENTATION DOCUMENTATION

App credentials

About app credentials

App credentials provide access to your Aporeto namespace. They can be very useful when deploying applications that need to connect to Aporeto.

When creating an app credential, the control plane will:

  1. Create the app credentials.
  2. Create the API authorization to grant a specific role to the app credential.
  3. Return the app credential.

List app credentials

You can view the list of existing app credentials by using the list command:

apoctl appcred list

Example Output:

name:      alice
id:        5bf46d187ddf1f62b3b79eac
date:      2019-11-20T20:22:48Z
roles:     [@auth:role=namespace.administrator]

name:      bob
id:        5c364e0d7ddf1f3cf70b3157
date:      2019-01-09T19:39:57.209Z
roles:     [@auth:role=namespace.viewer]

You can also use the flag --recursive to list the appcreds in the current namespace and all its children.

Create an app credential

App credentials can be formatted for different uses, such as:

  • Aporeto (default)
  • Kubernetes secret
  • X.509 certificate

You can use the flag --type to select the type.

Aporeto type

This type is the default app credential format. It can be used by

  • apoctl
  • Aporeto enforcer
  • Aporeto operator
  • Custom applications created using the Aporeto SDK

To create an app credential with the role namespace.administrator and write it into ./mycreds.json, run:

apoctl appcred create mycreds -n /my/ns \
  --role @auth:role=namespace.administrator \
  > ./mycreds.json

You can list the available roles by running:

apoctl api list roles -c key -c description

You can check the content of the file by running:

cat ./mycreds.json

Example output:

{
    "ID": "5bc65d707ddf1f94d1bb96b6",
    "name": "myapp",
    "namespace": "/my/ns"
    "certificate": "<base64>",
    "certificateAuthority": "<base64>",
    "certificateKey": "<base64>",
}

You can then use it to retrieve an Aporeto token by running:

apoctl auth appcred --path ./mycreds.json

Kubernetes secret type

This format wraps the app credential in the Aporeto format into a Kubernetes secret definition. This secret can then be mounted by pods to access the Aporeto API.

To create an app credential with the role enforcer and apply it in your current Kubernetes cluster, run:

apoctl appcred create mycreds \
  --role @auth:role=enforcer \
  --type k8s \
  | kubectl apply -f -

X.509 certificate type

This format extracts the certificates contained in the Aporeto format and writes them into a separate certificate and key in the PEM format.

To create an app credential with the role namespace.administrator on /my/ns and get an X.509 certificate, run:

apoctl appcred create mycreds \
  -n /my/ns \
  --role @auth:role=namespace.administrator \
  --type cert

The certificate can be used to get an Aporeto token:

apoctl auth cert --cert myapp-cert.pem --key myapp-key.pem

Renew an app credential

Renewing an app credential will keep the old one valid for an additional period of 12 hours. After that grace period, entities using it will see their API calls denied.

To renew your app credential, simply execute:

apoctl appcred renew mycreds -n /my/ns > ./mycreds.json

TIP

You can always set the type using the flag --type.

Disable an app credential

IMPORTANT

Entities using the disabled app credential will see their API calls denied immediately.

To disable an existing app credential, run:

apoctl appcred disable mycreds -n /my/ns

To re-enable a disabled app credential, run:

apoctl enable disable mycreds -n /my/ns

Change the roles of an app credential

IMPORTANT

Entities using the app credential will see their roles updated immediately.

To change the roles of an existing app credential, run:

apoctl appcred roles mycreds -n /my/ns \
  --role compute.editor \
  --role automation.viewer

Delete an app credential

IMPORTANT

Deleting an appcred will revoke the certificate immediately. Entities using the previous version will see their API calls denied.

To delete an existing app credential, run:

apoctl appcred delete mycreds -n /my/ns