Truepic BlogStatus Page
Get Started
Contact Us

Integrate Key Providers

Learn how to use the different key providers supported by the command-line interface

AWS

The aws key provider stores keys in Key Management Service and their certificates in Secrets Manager.

Authentication

Permissions

The CLI requires the following permissions to be assigned through IAM:

  • kms:CreateKey
  • kms:DescribeKey
  • kms:GetPublicKey
  • kms:Sign
  • kms:TagResource
  • secretsmanager:CreateSecret
  • secretsmanager:DescribeSecret
  • secretsmanager:GetSecretValue
  • secretsmanager:TagResource

Continue reading to determine which resource to assign these permissions to.

Authenticate via Instance Profile

If the CLI will be running in an AWS environment that utilizes instance profiles – such as EC2 – the instance profile can be used for authentication. Assign the permissions listed above to the instance profile.

When enrolling with the CLI, only the region is required:

./truepic enroll aws --api-key <API_KEY> --region <REGION>

Authenticate via AWS CLI

If the CLI will be running on a machine with the AWS CLI installed, the configured user credentials can be used for authentication. Assign the permissions listed above to the user.

When enrolling with the CLI, only the region is required:

./truepic enroll aws --api-key <API_KEY> --region <REGION>

To use an AWS CLI profile other than default (which is the default):

./truepic enroll aws \
  --api-key <API_KEY> \
  --region <REGION> \
  --cli-profile <CLI_PROFILE>

Authenticate via Access Key & Secret

If neither of the above authentication methods is appropriate, you can authenticate with an access key and secret directly. Create a new user within IAM, or use an existing user, and assign the permissions listed above. Then create a new access key, selecting Application running outside AWS as the use case. Be sure to copy the secret after creation, as it's not viewable after that.

Both the access key and secret can then be specified when enrolling with the CLI:

./truepic enroll aws \
  --api-key <API_KEY> \
  --region <REGION> \
  --access-key-id <ACCESS_KEY_ID> \
  --access-key-secret <ACCESS_KEY_SECRET>

Alternatively, environment variables can be used:

export AWS_ACCESS_KEY_ID=<ACCESS_KEY_ID>
export AWS_ACCESS_KEY_SECRET=<ACCESS_KEY_SECRET>
./truepic enroll aws --api-key <API_KEY> --region <REGION>

Azure

The azure key provider stores keys and their certificates in Azure Key Vault.

Create a Key Vault

Before the CLI can use Azure, a key vault must first be created for the CLI to house keys and certificates within. An existing key vault may be used if you prefer, but we recommend creating a new one specifically for the CLI.

To create a new key vault through the Azure Portal:

  1. Head to the Key vaults service.
  2. Follow the link to create a new key vault.
  3. Follow the steps to configure the key vault according to your needs. No specific settings are required, however, the authentication instructions below do assume the recommended Azure role-based access control.

Authentication

Role

The CLI requires the built-in Key Vault Administrator role. This can be assigned through the Access control (IAM) section of the subscription you're using. Continue reading to determine which resource to assign this role to.

Authenticate via Managed Identity

If the CLI will be running within Azure – whether Azure VMs, App Services, or Function Apps – the managed identity assigned to the deployment environment can be used for authentication. Assign the role listed above to the managed identity.

When enrolling with the CLI, only the vault URI is required:

./truepic enroll azure --api-key <API_KEY> --vault-uri <VAULT_URI>

Authenticate via Azure CLI

If the CLI will be running on a machine with the Azure CLI installed, the logged in user can be used for authentication. Assign the role listed above to the user.

When enrolling with the CLI, only the vault URI is required:

./truepic enroll azure --api-key <API_KEY> --vault-uri <VAULT_URI>

Authenticate via Client ID & Secret

If neither of the above authentication methods is appropriate, you can authenticate with a client ID and secret associated with a registered app. To register an app, head to Azure Active Directory > App registration within the Azure Portal and then follow this quickstart guide at Microsoft Learn. Here are a few pointers to help you along the way:

  • The app name can be anything, but we recommend Truepic Lens CLI.
  • There's no need to specify a Redirect URI.
  • After creating the app, head to Certificates & secrets > Client secrets and create a new secret. Be sure to copy the secret after creation, as it's not viewable after that.
  • After creating the secret, head to Overview and copy the Application (client) ID and Directory (tenant) ID.

The values collected above are all required to enroll with the CLI:

./truepic enroll azure /
  --api-key <API_KEY> /
  --vault-uri <VAULT_URI> /
  --tenant-id <TENANT_ID> /
  --client-id <CLIENT_ID> /
  --client-secret <CLIENT_SECRET>

Alternatively, environment variables can be used:

export AZURE_TENANT_ID=<TENANT_ID>
export AZURE_CLIENT_ID=<CLIENT_ID>
export AZURE_CLIENT_SECRET=<CLIENT_SECRET>
./truepic enroll azure --api-key <API_KEY> --vault-uri <VAULT_URI>

File System

The file-system key provider stores keys and their certificates in the host machine's file system.

Because there are no outside dependencies, the file system is a very simple key provider to get started with that doesn't incur any additional cost. Enrolling with the CLI only requires your API key:

./truepic enroll file-system --api-key <API_KEY>

Security Considerations

The security tradeoff is that the private keys are stored in plain text on the host machine, and therefore only as secure as the host machine itself. The CLI can also read/write the private keys (but they never leave the host machine, ever), which may not comply with your organization's security policies. These security concerns can be mitigated in some ways – like ensuring only the user running the CLI can access the files – but care and consideration must be taken.

Inline

The inline key provider stores keys and their certificates inline with the profile.

Because there are no outside dependencies, like the file system, it's a very simple key provider to get started with that doesn't incur any additional cost. Enrolling with the CLI only requires your API key:

./truepic enroll inline --api-key <API_KEY>

Security Considerations

The security tradeoff is that the private keys are stored in plain text on the host machine, and therefore only as secure as the host machine itself. The CLI can also read/write the private keys (but they never leave the host machine, ever), which may not comply with your organization's security policies. These security concerns can be mitigated in some ways – like ensuring only the user running the CLI can access the files – but care and consideration must be taken.

Updated 3 months ago