From ea1e29fa33f1789f45b78f2cf47f6207d3382b9f Mon Sep 17 00:00:00 2001
From: Dmitriy Gromov <dmitriy@knewton.com>
Date: Thu, 21 Jan 2016 14:28:34 -0500
Subject: [PATCH] Renamed sts duration to ttl and added STS permissions note.

---
 builtin/logical/aws/path_sts.go               |  8 ++++----
 website/source/docs/secrets/aws/index.html.md | 15 +++++++++++++++
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/builtin/logical/aws/path_sts.go b/builtin/logical/aws/path_sts.go
index 2a9b9a4812..c8fb95accf 100644
--- a/builtin/logical/aws/path_sts.go
+++ b/builtin/logical/aws/path_sts.go
@@ -15,8 +15,8 @@ func pathSTS(b *backend) *framework.Path {
 				Type:        framework.TypeString,
 				Description: "Name of the role",
 			},
-			"duration": &framework.FieldSchema{
-				Type:        framework.TypeInt,
+			"ttl": &framework.FieldSchema{
+				Type:        framework.TypeDurationSecond,
 				Description: "Lifetime of the token in seconds",
 				Default: 3600,
 			},
@@ -34,7 +34,7 @@ func pathSTS(b *backend) *framework.Path {
 func (b *backend) pathSTSRead(
 	req *logical.Request, d *framework.FieldData) (*logical.Response, error) {
 	policyName := d.Get("name").(string)
-	duration := int64(d.Get("duration").(int))
+	ttl := int64(d.Get("ttl").(int))
 
 	// Read the policy
 	policy, err := req.Storage.Get("policy/" + policyName)
@@ -50,7 +50,7 @@ func (b *backend) pathSTSRead(
 	return b.secretAccessKeysAndTokenCreate(
 		req.Storage,
 		req.DisplayName, policyName, string(policy.Value),
-		&duration,
+		&ttl,
 	)
 }
 
diff --git a/website/source/docs/secrets/aws/index.html.md b/website/source/docs/secrets/aws/index.html.md
index 55625e2b3c..291f546c75 100644
--- a/website/source/docs/secrets/aws/index.html.md
+++ b/website/source/docs/secrets/aws/index.html.md
@@ -100,6 +100,7 @@ security_token  <nil>
 ```
 
 If you want keys with an STS token use the 'sts' endpoint instead of 'creds.'
+The aws/sts endpoint will always fetch STS credentials with a 1hr ttl.
 
 ```text
 $vault read aws/sts/deploy
@@ -161,6 +162,20 @@ Note that this policy example is unrelated to the policy you wrote to `aws/roles
 If you get stuck at any time, simply run `vault path-help aws` or with a subpath for
 interactive help output.
 
+## A Note on STS Permissions
+
+Vault generates STS tokens using the IAM credentials passed to aws/config.
+
+Those credentials must have two properties:
+
+- They must have permissions to call sts:GetFederatedToken.
+- The capabilities of those credentials have to be at least as permissive as those requested
+by policies attached to the STS creds.
+
+If either of those conditions are not met, a "403 not-authorized" error will be returned.
+
+See http://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html for more details.
+
 ## A Note on Consistency
 
 Unfortunately, IAM credentials are eventually consistent with respect to other