Cerberus |
Secure property store for cloud applications
Home Components Docs

AWS IAM KMS Authentication

Introduction

User Guide

Administration Guide

Authentication

Architecture

Contributing

AWS IAM KMS Authentication

Deprecation Notice

AWS IAM KMS Authentication is deprecrated. KMS Auth is Cerberus’s original AWS IAM authentication mechanism. Please see AWS STS Authentication for more information on how to use AWS STS Authentication, the current authentication mechanism. To use STS Auth, make sure you are on the latest version of the Cerberus clients.

IAM Authentication

One of the key components of the Cerberus offering is a simple yet secure solution for accessing privileged data from an EC2 instance. Within Cerberus, the logical grouping of related data is referred to as a safe deposit box (SDB). This SDB in a collection of metadata describing the data and a set of permissions for what LDAP groups and AWS IAM roles have access.

Assumptions

If more than one IAM role is associated with the EC2 instance, the first one to authenticate successfully with Cerberus will be used.

Prerequisites

The EC2 instance must be assigned an IAM role that has been given permissions to at least one SDB in Cerberus. The IAM role to be assigned must contain, at a minimum, a IAM policy statement giving access to call the KMS’ decrypt action:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Allow KMS Decrypt",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": [
                "arn:aws:kms:*:[Cerberus AWS Account ID]:key/*"
            ]
        }
    ]
}

The account ID in the ARN should be the account ID where Cerberus is deployed.

Sequence

The Cerberus Java client provides a credentials provider that is able to authenticate with Cerberus based on the assigned IAM roles to that instance.

  1. Lookup the AWS account ID from EC2 metadata service
  2. Lookup all the IAM roles assigned to the instance from EC2 metadata service
  3. For each assigned IAM role:
    1. Request encrypted auth response from Cerberus
    2. Attempt to decrypt response with KMS
  4. Store the auth token and expire time

IAM authentication sequence diagram

A note about regions

The various Cerberus clients take in as an argument a region, when using KMS auth, the supplied region is the AWS region that Cerberus will create a KMS key for you in, and the region that you will have to use KMS decrypt in to get your payload. You will want to make this the region you are running in and not hard code this region. So that if there is an KMS outage in 1 region your services in another region will continue to work.

References