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:
- A user will send its credentials to the client.
- The client sends the credentials to an authorization server where it will generate a unique token for that specific user’s credentials.
- The authorization server sends the token to the client.
- The client sends the token to the resource server
- 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’:
Clicking ‘API Keys’ will present a dialog that lists your active, expired and revoked keys:
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:
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:
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:
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:
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’:
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:
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:
user_authentication:
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.
