In Anchore 5.1, we have added the functionality of using token-based authentication through our API keys. Now with Anchore Enterprise 5.1, an administrator can create a token for a user so that they can use API keys rather than a username or credential. Let's dive into the details of what this means.

Token-based authentication is a protocol that provides an extra layer of security when users want to access an API. It allows users to verify their identity, and in return receive a unique access token for the specific service. Tokens have a lifespan and as long as it is used within that duration, users can access the application with that same token without having to continuously log in.

We list the step-by-step mechanism for a token-based authentication protocol:

  1. A user will send its credentials to the client. 
  2. The client sends the credentials to an authorization server where it will generate a unique token for that specific user’s credentials. 
  3. The authorization server sends the token to the client. 
  4. The client sends the token to the resource server
  5. The resource server sends data/resource to the client for the duration of the token’s lifespan.

Token-Based Authentication in Anchore 5.1

Now that we've laid the groundwork, in the following sections we'll walk through how to create API keys and use them in AnchoreCTL.

Creating API Keys

In order to generate an API key, navigate to the Enterprise UI and click on the top right button and select ‘API Keys’:

alt text

Clicking ‘API Keys’ will present a dialog that lists your active, expired and revoked keys:

alt text

To create a new API key, click on the ‘Create New API Key’ on the top right. This will open another dialog where it asks you for relevant details for the API key:

alt text

You can specify the following fields:

  • Name: The name of your API key. This is mandatory and the name should be unique (you cannot have two API keys with the same name).
  • Description: An optional text descriptor for your API key.
  • Expiry Date: An expiry date for your API key, you cannot specify a date in the past and it cannot exceed 365 days by default. This is the lifespan you are configuring for your token.

Click save and the UI will generate a Key Value and display the following output of the operation:

alt text

NOTE: Make sure you copy the Key Value as there is no way to get this back once you close out of this window.

Revoking API Keys

If there is a situation where you feel your API key has been compromised, you can revoke an active key. This prevents the key from being used for authentication. To revoke a key, click on the ‘Revoke’ button next to a key:

alt text

NOTE: Be careful revoking a key as this is an irreversible operation i.e. you cannot mark it active later.

The UI by default only displays active API keys. If you want to see your revoked and expired keys, check the toggle to ‘Show only active API keys’ on the top right:

alt text

Managing API Keys as an Admin

As an account admin you can manage API keys for all users in the account you are administered in. A global admin can manage API keys across all accounts and all users.

To access the API keys as an admin, click on the ‘System’ icon and navigate to ‘Accounts’:

alt text

Click ‘Edit’ for the account you want to manage keys for and click on the ‘Tools’ button against the user you wish to manage keys for:

alt text

Using API Keys in AnchoreCTL

Generating API Keys as an SAML (SSO) User

API keys for SAML (SSO) users are disabled by default. To enable API keys for SAML users, please update your helm chart values file with the following:


        allow_api_keys_for_saml_users: true

NOTE: API keys are an additional authentication mechanism for SAML users that bypasses the authentication control of the IDP. When access has been revoked at the IDP, it does not automatically disable the user or revoke all API keys for the user. Therefore, when access has been revoked for a user, the system admin is responsible to manually delete the Anchore User or revoke any API key which was created for that user.

Using API Keys

API keys are authenticated using basic auth. In order to use API keys, you need to use a special username _api_key and the password is the Key Value that was the output when you created the API key.

curl -u '_api_key:<API key value>' http://localhost:8228/v2/images

  url: "http://localhost:8228"

  username: "_api_key"

  password: <API Key Value>

Caveats for API Keys

API Keys generally inherit the permissions and roles of the user they were generated for, but there are certain operations you cannot perform using API keys regardless of which user they were generated for:

  • You cannot Add/Edit/Remove Accounts, Users and Credentials.
  • You cannot Add/Edit/Remove Roles and Role Members.
  • You cannot Add/Edit/Revoke API Keys.

We invite you to learn more about Anchore Enterprise 5.0 with a free 15 day trial. Or, if you’ve got other questions, set up a call with one of our specialists.

Learn more from Anchore:

  1. User Management in Anchore Enterprise 
  2. User Authentication with API Keys
  3. AnchoreCTL Configurations