commit ed13179dc40d38ae258fefd19199ceca3252195f Author: Colby Gutierrez-Kraybill Date: Wed Aug 15 23:51:03 2018 -0400 First commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fdc7b83 --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +# Mac OS +.DS_Store + +# NPM +/node_modules +npm-* + +# Build +dist/* + +# Editors +/#* +*~ diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..205a295 --- /dev/null +++ b/.npmignore @@ -0,0 +1,5 @@ +node_modules/ +.DS_Store +*.log +.nyc_output/ +coverage/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..be62566 --- /dev/null +++ b/README.md @@ -0,0 +1,63 @@ +# aws-sts-helper ![Build Status](https://travis-ci.org/LLK/scratch-asset-types.svg?branch=master) + +A library for facilitating the acquisition of temporary security tokens through the AWS Security Token Service (STS) + +## What does it do? + +Using a particular AWS access key pair, query for and store a new access key pair, plus session token that is suitable to use for another role, that may have more specific or narrower permissions than the original access key pair. + +For example, a role could be constructed with a policy that only allows for the creation of a named S3 bucket `dev-projects-*`, and provide all read-write permissions to the bucket created. Then this role can be access using the generated temporary access key and token by a locally developed project, limited to accessing just the `dev-projects-*` buckets in S3. + +By default, any credentials created in this way are stored in a file, `./.aws-sts.json`. This way the credentials are cached locally and available to reuse for the duration that the temporary credentials last. This library will look for the existence of the stored credentials and if they are still valid (not-expired) it will return them instead of generating a new set. + +### Usage: + +You can set environment variables and/or set values in the configuration map passed into the `getTemporaryCredentials` call. + +Available variables and their usage: + +| Env Variable | Maps to | Purpose/Default | +|-----------------------|-------------------------------------|-----------------------------------------------------------------| +| AWS_STS_ACCESS_KEY | Equivalent to AWS_ACCESS_KEY_ID | Used to assume a role and generate temporary credentials for it | +| AWS_STS_ACCESS_SECRET | Equivalent to AWS_SECRET_ACCESS_KEY | Used to assume a role and generate temporary credentials for it | +| AWS_ROLE_ARN | The Role to assume in ARN format | | +| AWS_ROLE_SESSION_NAME | A name that will be assigned to the temporary credentials | Defaults to `temporary` | +| AWS_STS_FILE_NAME | Fully qualified path to credential file, JSON | Used to store credentials in JSON format, defaults to `./.aws-sts.json` | +| AWS_ROLE_DURATION_SECONDS | Number of seconds the temporary access key lasts| defaults to 12 hours or 43200 seconds | | +| AWS_STS_FILE_MODE | permissions setting on JSON file that caches credentials | Defaults to 0o600 or user read-write only | + +These values can be passed either in the environment or in a configuration object: + +```javascript +const sts = require('aws-sts-helper'); + +sts.getTemporaryCredentials({ + { + credentials: { + fileName: './.aws-sts.json', + mode: 0o600 + }, + role: { + arn: 'arn:aws:iam:::role/ProjectsS3Development', + sessionName: 'colbyProjectsDev', + durationSeconds: 43200 + }, + key: { + access: 'access key that allows calls to STS assume role', + secret: 'secret key paired to access key' + } + } +}, (err, awsRaw) => { + if (err) { + console.log('err:',err); + process.exit(-1); + } + var aws = JSON.parse(awsRaw); + + console.log('aws:',aws); + var sh = `AWS_ACCESS_KEY_ID=${aws.Credentials.AccessKeyId}\n` + + `AWS_SECRET_ACCESS_KEY=${aws.Credentials.SecretAccessKey}\n` + + `AWS_SESSION_TOKEN=${aws.Credentials.SessionToken}\n`; + fs.writeFileSync("aws-temp-credentials.sh", sh, {encoding:'utf-8'}); +}); +``` diff --git a/index.js b/index.js new file mode 100644 index 0000000..c3d1464 --- /dev/null +++ b/index.js @@ -0,0 +1,67 @@ +const aws = require('aws-sdk'); +const fs = require('fs'); +const defaults = require('lodash').defaults; + +const credentialsExpired = c => { + if (c && c.Credentials) { + const expiration = new Date(c.Credentials.expiration); + if (expiration.getTime() < new Date().getTime()) { + return true; + } + } + return false; +}; + +const getTemporaryCredentials = (config, callback) => { + defaults(config, { + credentials: { + fileName: process.env.AWS_STS_FILE_NAME || './.aws-sts.json', + mode: parseInt(process.env.AWS_STS_FILE_MODE, 8) || 0o600, + }, + role: { + arn: process.env.AWS_ROLE_ARN || '', + sessionName: process.env.AWS_ROLE_SESSION_NAME || 'temporary' + durationSeconds: process.env.AWS_ROLE_DURATION_SECONDS || 43200 + }, + key: { + access: process.env.AWS_STS_ACCESS_KEY || '', + secret: process.env.AWS_STS_ACCESS_SECRET || '' + } + }); + + const sts = new aws.STS({ + accessKeyId: config.key.access, + secretAccessKey: config.key.secret + }); + + fs.readFile(config.credentials.fileName, 'utf-8', (err, old) => { + if (err || credentialsExpired(old)) { + sts.assumeRole({ + RoleArn: config.role.arn, + RoleSessionName: config.role.sessionName, + DurationSeconds: config.role.durationSeconds + }, (err, newCredentials) => { + if (err) return callback(err, null); + fs.writeFile( + config.credentials.fileName, + JSON.stringify(newCredentials), + { + mode: config.credentials.mode, + encoding: 'utf-8' + }, + err => { + if (err) return callback(err, null); + return callback(null, newCredentials); + } + ); + }); + } else { + return callback(null, old); + } + }); +}; + + +module.exports = { + getTemporaryCredentials: getTemporaryCredentials +}; diff --git a/package.json b/package.json new file mode 100644 index 0000000..69cb0d6 --- /dev/null +++ b/package.json @@ -0,0 +1,23 @@ +{ + "name": "aws-sts-helper", + "version": "1.0.0", + "description": "Facilitates gathering temporary security tokens from the AWS STS (Security Token Service) and then using that token information for interacting with AWS APIs", + "repository": { + "type": "git", + "url": "git+ssh://git@github.com/LLK/aws-sts-helper.git" + }, + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "Massachusetts Institute of Technology", + "license": "BSD-3-Clause", + "devDependencies": { + "babel-eslint": "^8.0.3", + "eslint": "^4.13.1", + "eslint-config-scratch": "^5.0.0", + "tap": "^11.0.0" + }, + "dependencies": { + "aws-sdk": "~2.166.0" + } +}