Skip to content
This repository has been archived by the owner on Jan 12, 2024. It is now read-only.

Commit

Permalink
updated README for Sts Auth update
Browse files Browse the repository at this point in the history
  • Loading branch information
melanahammel committed Dec 18, 2018
1 parent a1044fa commit 7f964a4
Showing 1 changed file with 13 additions and 97 deletions.
110 changes: 13 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,24 @@
[![Coverage Status](https://coveralls.io/repos/github/Nike-Inc/cerberus-java-client/badge.svg?branch=master)](https://coveralls.io/github/Nike-Inc/cerberus-java-client)
[![][license img]][license]

A java based client library for Cerberus that's built on top of Nike's Cerberus client.
This is a Java based client library for Cerberus that is built on top of Nike's Cerberus client.

This library acts as a wrapper around the Nike developed Cerberus client by configuring the client to be Cerberus compatible.

To learn more about Cerberus, please see the [Cerberus website](http://engineering.nike.com/cerberus/).

## Quickstart for EC2
## Quickstart for Cerberus Java Client

1. Start with the [quick start guide](http://engineering.nike.com/cerberus/docs/user-guide/quick-start).
2. Add the [Cerberus client dependency](https://bintray.com/nike/maven/cerberus-client) to your build (e.g. Maven, Gradle)
3. Provide an authentication mechanism.
- For local development it is easiest to export a `CERBERUS_TOKEN` that you copied from the Cerberus dashboard.
When running in AWS, your application will not need this environment variable, instead it will automatically
authenticate using its IAM role. Alternatively, set a `cerberus.token` System property.
- If you would like to test IAM authentication locally, you can do that by [assuming a role](http://docs.aws.amazon.com/cli/latest/userguide/cli-roles.html).
4. Access secrets from Cerberus using Java
2. Add the [Cerberus client dependency](https://bintray.com/nike/maven/cerberus-client) to your build (e.g. Maven, Gradle).
3. Access secrets from Cerberus using Java.
``` java
String cerberusUrl = "https://cerberus.example.com";
CerberusClient cerberusClient = DefaultCerberusClientFactory.getClient(cerberusUrl);
String region = "us-west-2";
CerberusClient cerberusClient = DefaultCerberusClientFactory.getClient(cerberusUrl, region);
Map<String,String> secrets = cerberusClient.read("/app/my-sdb-name").getData();
```
Check out ["Working with AWS Credentials"](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) for more information on how the AWS SDK for Java loads credentials.

## Lambdas

Expand All @@ -40,91 +37,6 @@ feature provided by AWS.
Another option is to store Lambda secrets in Cerberus but only read them at Lambda deploy time, then storing them as encrypted
environmental variables, to avoid the extra Cerberus runtime latency.

### Additional permissions

The IAM role assigned to the Lambda function must contain the following policy statement in addition to the above KMS decrypt policy, this is so the Lambda can look up its metadata to automatically authenticate with the Cerberus IAM auth endpoint:

``` json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowGetFunctionConfig",
"Effect": "Allow",
"Action": [
"lambda:GetFunctionConfiguration"
],
"Resource": [
"*"
]
}
]
}
```

### Configure the Client

Setup the CERBERUS_ADDR environmental variable and access Cerberus using Java:

``` java
String invokedFunctionArn = context.getInvokedFunctionArn();
CerberusClient cerberusClient = DefaultCerberusClientFactory.getClientForLambda(invokedFunctionArn);
Map<String,String> secrets = cerberusClient.read("/app/my-sdb-name").getData();
```

## More Configuration Options

There are other ways of using this library than the quick start above.

### Configuring the Cerberus URL

Provide the URL directly using the factory method `DefaultCerberusClientFactory.getClient(cerberusUrl)` or use the
`DefaultCerberusUrlResolver` by setting the environment variable `CERBERUS_ADDR` or the JVM system property `cerberus.addr`
and then use the factory method that does not require a URL:

``` java
final CerberusClient cerberusClient = DefaultCerberusClientFactory.getClient();
Map<String,String> secrets = cerberusClient.read("/app/my-sdb-name").getData();
```

### Configuring Credentials

#### Default Credentials Provider Chain

This client uses a provider chain to resolve the token needed to interact with Cerberus.

See `DefaultCerberusCredentialsProviderChain.java` for full usage.

If the client library is running on an EC2 instance, it will attempt to use the instance's assigned IAM role to authenticate
with Cerberus and obtain a token.

If the client library is running in an ECS task, it will attempt to use the task's execution IAM role to authenticate
with Cerberus and obtain a token.

The IAM role must be configured for access to Cerberus before this will work.

The following policy statement must also be assigned to the IAM role, so that the client can automatically decrypt the auth token from the Cerberus IAM auth endpoint:

``` json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowKmsDecrypt",
"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. See your company's internal
documentation for the account ID that you should use.

## Development

Expand All @@ -134,11 +46,15 @@ First, make sure the following environment variables are set before running the

``` bash
export CERBERUS_ADDR=https://example.cerberus.com
export TEST_ACCOUNT_ID=12345678910
export TEST_ROLE_NAME=integration-test-role
export TEST_REGION=us-west-2
```

Then, make sure AWS credentials have been obtained. One method is by running [gimme-aws-creds](https://github.com/Nike-Inc/gimme-aws-creds):

```bash
gimme-aws-creds
```

Next, in the project directory run:
```gradle
./gradlew integration
Expand Down

0 comments on commit 7f964a4

Please sign in to comment.