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 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:

1. 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.
2. 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.
3. 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. To achieve this, use the credentials.CreateAWS() function in the following fashion:

import (
    "github.com/secrethub/secrethub-go/pkg/secrethub"
    "github.com/secrethub/secrethub-go/pkg/secrethub/credentials"
)

func main() {
    client := secrethub.Must(secrethub.NewClient())

    service, err := client.Services().Create("my/repo", "Service Description", credentials.CreateAWS(
    		"1234abcd-12ab-34cd-56ef-1234567890ab", // KMS key ID
    		"MyRole", // Role name
    	))
    if err != nil{
        panic(err)
    }    
    fmt.Printf("Service ID: %s\n", service.ServiceID)
}

You can find further details 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 to aws.

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),
})

See also

• Managing AWS Service Accounts
• Secret Management for AWS EC2
• Secret Management for AWS ECS
• Using secrets in AWS Lambda Serverless (Golang)