Amazon Web Services Integration
The AWS integration allows users to seamlessly use SecretHub with any application running on AWS. By using the integration, service accounts can be created that do not have a key that has to be copied anywhere. Instead, the integration leverages AWS native services (KMS, IAM and STS) to handle encryption and authentication.
The integration supports the following AWS services:
- AWS Elastic Cloud Computing (EC2)
- AWS Elastic Container Service (ECS), including Fargate
- AWS Elastic Kubernetes Service (EKS)
- AWS Lambda Serverless
Service Accounts
Any application running on AWS needs its own AWS service account on SecretHub. AWS service accounts have two prerequisites:
- A KMS key that is used for encryption of the account. KMS keys can be reused for multiple service accounts.
- An IAM role that is assumed by the service that is running the application. For example, an “IAM Role” for an EC2 instance, “Task Execution Role” for a Lambda Function or a “Task Role” for an ECS Task. The role must have decryption rights on the KMS key. Because the role is used for identifying the service account, each role can be used for at most 1 SecretHub service account.
Creating Service Accounts
To create a service account, you’ll need to take the following steps:
-
Create KMS key: use the AWS CLI, AWS Console or any other method to create a Customer Managed Key in AWS.
Make sure you have permission to perform the
kms:Encrypt
action on this key. This can be achieved by making yourself a Key User or Key Administrator. -
Create IAM role: use the AWS CLI, AWS Console or any other method to create an IAM Role for an AWS Service.
This role must be granted the permission to perform the
kms:Decrypt
action on the previously created KMS key. - Create service account: use SecretHub CLI, Go SDK or Terraform Provider to create a AWS service account on SecretHub.
The diagram below illustrates the process of creating a service account:
CLI
To create an AWS service account through the CLI, the following command can be used:
secrethub service aws init <namespace>/<repo> \
--kms-key <kms-key> \
--role <role-name> \
--region <aws-region>
For further details, see the command reference docs of secrethub service aws
, which also contains all other commands related to AWS service accounts.
Golang SDK
AWS service accounts can also be created using the Golang SDK. You can find further details as well as an example on how to do this in the GoDoc.
Using Identity Provider
Using SecretHub with the AWS Identity Provider is really simple. As long as your EC2 instance, ECS task, or Lambda function uses the IAM role attached to the SecretHub service account, it can automatically fetch and decrypt the secrets it needs.
When you invoke SecretHub with the AWS Identity Provider enabled, the integration automatically communicates with the necessary AWS services to provide authentication and decryption. How this works is demonstrated in the following diagram:
The Identity Provider can be invoked in multiple ways, depending on how you use SecretHub.
CLI
For the CLI there are two different options for invoking the AWS Identity Provider:
- Use the
--identity-provider=aws
flag for the CLI: - Set the
SECRETHUB_IDENTITY_PROVIDER
environment variable toaws
.
Golang SDK
By setting the SECRETHUB_IDENTITY_PROVIDER
environment variable to aws
, you can initialize the client for the Golang SDK using secrethub.NewClient()
.
The client then automatically sets up the Identity Provider for AWS.
It is also possible to explicitly initialize the client with the AWS Identity Provider:
import (
"github.com/secrethub/secrethub-go/pkg/secrethub"
"github.com/secrethub/secrethub-go/pkg/secrethub/credentials"
)
func main() {
creds := credentials.UseAWS()
client, err := secrethub.NewClient(secrethub.WithCredentials(creds))
}
The client will automatically use the native AWS services for authentication and decryption instead of the default credential key file.
Depending on your exact setup, it might be necessary to provide extra configuration details for the AWS config.
Reference to one or more aws.Config
struct can be provided to the credentials.UseAWS()
function.
For example, explicitly setting CredentialsChainVerboseErrors
(to get more verbose errors regarding AWS credentials) can be done in the following way:
creds := credentials.UseAWS(&aws.Config{
CredentialsChainVerboseErrors: aws.Bool(true),
})