diff --git a/README.md b/README.md index 0c22a9e..2b233d4 100644 --- a/README.md +++ b/README.md @@ -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 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 @@ -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 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 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 @@ -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