Skip to content

Latest commit

 

History

History
190 lines (142 loc) · 7.92 KB

README.md

File metadata and controls

190 lines (142 loc) · 7.92 KB
Raw

CloudWatch Postman Codeship Status for KissKissBankBank/cloudwatch-postman

CloudWatch Postman is a Node server that sends data to Amazon CloudWatch. It enables you to serve an API with endpoints that add or update your metrics/your logs on CloudWatch with your AWS credentials.

  • For the moment, configuration of this API is set with environment variables.
  • Its first purpose is to serve some endpoints so an cliend-side application can call it to send data to CloudWatch.

Postman on a bicycle

Prerequisites

  • Node.js,
  • Redis,
  • Amazon CloudWatch,
  • an AWS IAM account that can call CloudWatch with read and write access.

Quick start

Install the dependencies:

npm install

Choose an CLIENT_SECRET_KEY and an ACCESS_TOKEN_SECRET_KEY. These secret values will be used by CloudWatch Postman to generate tokens to access the API.

Create a .env file with these secrets and your AWS credentials.

Start the app:

npm run serve

Test the API on http://localhost:8080/test.

How to request the API

You can request the API using a unique access token:

+--------------------+                               +--------------------+
|                    | 2. Ask for an access token.   |                    |
|                    | +------- POST /token -------> |                    |
|                    |                               |                    |
|       Client       | <---------------------------+ |                    |
| (your application) | 3. The API returns a valid    |      The API       |
|                    |    access token.              |                    |
|                    |                               | cloudwatch-postman |
|  1. Create your    |                               |                    |
|     client token.  |                               |                    |
|                    |                               |                    |
|                    |                               |                    |
|                    |                               |                    |
|                    |                               |                    |
|                    | 4. Make API calls with the    |                    |
|                    |    valid access token.        |                    |
|                    |                               |                    |
|                    | +---- eg. POST /metric -----> |                    |
|                    |                               |                    |
|                    | (by default, the access token |                    |
|                    |  is valid for one hour)       |                    |
+--------------------+                               +--------------------+

What is a unique access token?

As CloudWatch Postman is firstly meant to be called by a client-side application, unique access tokens can secure a little bit more the API endpoints.

You need to exchange your client token to obtain a unique access token. The latter have a default expiration of one hour.

When is a unique access token used?

Every endpoint, except the POST /token one, needs an accessToken to be requested. We advise you to fetch it on your client-side application as soon as possible if you know that you will need to query the API.

How to get a unique access token?

You can fetch an accessToken on the POST /token endpoint with your client token.

How to generate your client token

This section explains how to generate an client token to request an access token for the API.

You will needs these values:

  • the current timestamp,
  • a random salt value,
  • your CLIENT_SECRET_KEY,

Concatenate these 3 values and hash them with a sha256 algorithm digested in base64. Here is an example in JavaScript:

import crypto from 'crypto'

const data = `${timestamp}${salt}${appSecretKey}`
const hash = crypto.createHash('sha256').update(data).digest('base64')

Then, generate your token:

  • concatenate the date, the salt value and the hash with a :: delimiter,
  • encode this string in base64.

Here is an example in JavaScript:

Buffer.from([timestamp, salt, hash].join('::')).toString('base64')

Tokens usage

Name Usage How to get it Expiration
Access token An access token is used for each call to the API endpoints, except POST /token and GET /test. It has to be included in the JSON body of your calls along with your other parameters { accessToken: "aValidAccessToken" }. You can fetch a valid access token on POST /token with your client token. By default, an access token has a one hour validity from the moment it is sent to the client.
Client token The client token is used to fetch a valid access token on POST /token. It has to be included in the JSON body of your call { clientToken: 'yourClientToken'}. You have to generate your client token on your side. By default, a client token has a one day validity from the moment it is generated on your side.

API

You can check the existing endpoints of this API in the documentation.

Configuration with Dotenv

You can set some variables with a .env file and start the app with:

npm run serve

Example

# .env
AWS_ACCESS_KEY_ID=***
AWS_SECRET_ACCESS_KEY=***
AWS_REGION=***
CLIENT_SECRET_KEY=***
ACCESS_TOKEN_SECRET_KEY=***

Variables

The following variables can be setup in the .env file:

Variable Requirement Description Default value
AWS_ACCESS_KEY_ID Required The AWS IAM user access key id.
AWS_SECRET_ACCESS_KEY Required The AWS IAM user secret access key.
AWS_REGION Required The CloudWatch region
CLIENT_SECRET_KEY Required Your client secret key. You will share it on your consumer app to generate your client token.
ACCESS_TOKEN_SECRET_KEY Required Your access token secret key. It is used to generate all the access tokens.
PORT Optional The port on which the server is lauched 8080
CORS_ALLOWED_ORIGIN Optional A list of domain origins to which you grant the access to your API. Separate each origin with a comma: alice-in-wonderland.io, the-mad-hatter.com, tweedledee-tweedled.um *

Contributing

Please refer to the contributing documentation.

Resources