niallmccullagh / exegesis-cognito

AWS Cognito authentication for exegesis

exegesis-cognito

This package provides authentication of AWS cognito tokens in Exegesis requests.

Configure server

import * as exegesisExpress from 'exegesis-express';
import exegesisCognito from 'exegesis-cognito';


async function createServer() {
    const app = express();

    const jwks = fs.readFileSync('config/jwks.json', 'utf8')

    app.use(await exegesisExpress.middleware(
        path.resolve(__dirname, './openapi.yaml'),
        {
            // Other options go here...
            authenticators: {
                bearerAuth: exegesisCognito( { jwks })
            }
        }
    ));

    const server = http.createServer(app);
    server.listen(3000);
}

Open API spec

...
paths:
  '/things':
    get:
      operationId: getThings
      x-exegesis-controller: thingController
      security:
        - bearerAuth: []
...
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

API

exegesisCognito(options)

Returns an Exegesis authenticator that will authenticate a request with an AWS bearer token.

Configuration

The authenticator can be configured by passing in an options object.

Mandatory

jwks is a JSON object that represents a set of JWKs. The JSON object MUST have a keys member, which is an array of JWKs. The JWKS for a AWS cognito pool can be found at this well known

https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json

See AWS cognito site for more details.

Optional

• algorithms: List of strings with the names of the allowed algorithms. For instance, ["HS256", "HS384"].
• audience: if you want to check audience (aud), provide a value here. The audience can be checked against a string, a regular expression or a list of strings and/or regular expressions. Eg: "urn:foo", /urn:f[o]{2}/, [/urn:f[o]{2}/, "urn:bar"]
• issuer (optional): string or array of strings of valid values for the iss field.
• ignoreExpiration: if true do not validate the expiration of the token.
• ignoreNotBefore...
• subject: if you want to check subject (sub), provide a value here
• clockTolerance: number of seconds to tolerate when checking the nbf and exp claims, to deal with small clock differences among different servers
• maxAge: the maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span zeit/ms. Eg: 1000, "2 days", "10h", "7d". A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default ("120" is equal to "120ms").
• clockTimestamp: the time in seconds that should be used as the current time for all necessary comparisons.

Exegesis context

The authenticator will store the verified decoded token in the context.security object.

It will also poupulate the context.user object. The details extracted will deped on whether the bearer token is an id or access token.

Id token

{
    "user": {
        "id": "ba5bcf72-4b20-4c06-bc6b-ffc710adb244",
        "username": "jane",
        "email_verified": false,
        "email": "[email protected]",
        "roles": [
            "mygroup"
        ]
    }
}

Access token

{
  "user": {
    "id": "ba5bcf72-4b20-4c06-bc6b-ffc710adb244",
    "username": "niall"
  }
}

Sending a request

The client must send the access/id token in the Authorization header when making requests to protected resources. For example,

curl -X GET \
  'http://localhost:3000/things' \
  -H 'Authorization: Bearer eyJraWQiOiJpaGZYSVQ4Uk4yeFwvQW15UVo0Z2FUdEw5T3ZqQVpQa3RUcHY4SUpTbWttaz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiYTViY2Y3Mi00YjIwLTRjMDYtYmM2Yi1mZmM3MTBhZGIyNDQiLCJhdWQiOiIyNzh2b2EwY3UzM2Mxa3VlODJyYTYycTY1cSIsImNvZ25pdG86Z3JvdXBzIjpbIm15Z3JvdXAiXSwiZW1haWxfdmVyaWZpZWQiOnRydWUsImV2ZW50X2lkIjoiMzI4NDRkNDgtYjFkZC0xMWU4LWE0NzQtMDVhN2YwNzQzYmE3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1MzYyNDI0MjIsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xX1RFU1QiLCJjb2duaXRvOnVzZXJuYW1lIjoiamFuZSIsImV4cCI6MTUzNjI0NjAyMiwiaWF0IjoxNTM2MjQyNDIyLCJlbWFpbCI6ImphbmVAZC5vZSJ9.IdZV1F0MxEU0eC_6Qe_98EjgMSgYEGhP-mwqZtzQb4L8U1jOw-hnK4J1REChsaOatffE-aOJ4uoLV4oPYedRqnX4ABJ9XueN3lWfcZHc_DE2RTvDuEAV7hHoNTZwwn_mgaaYwLNMMOJeciXu3iM7PeT7xJAjdCxcdczZi1hPpqBc9Yx9wM7EMHyEo5klov3zRPJyvFPEpQPgpG1TjNkuvFwcl848YaXQDdlS9rXtTOySBVQu913e3i25VBnxZGxeHpFO3mmUomefOprDEvZpBSPg3-Di4F2-vKDzIl1OT98J8GayrJnD39O1TMUdiW-ApZKBFydtJtqvydQoVmEo_g'

License

exegesis-cognito's Issues

An in-range update of @types/jsonwebtoken is breaking the build 🚨

The dependency @types/jsonwebtoken was updated from 8.3.2 to 8.3.3.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

@types/jsonwebtoken is a direct dependency of this project, and it is very likely causing it to break. If other packages depend on yours, this update is probably also breaking those in turn.

Status Details

• ❌ continuous-integration/travis-ci/push: The Travis CI build could not complete due to an error (Details).
• ✅ coverage/coveralls: First build on greenkeeper/@types/jsonwebtoken-8.3.3 at 100.0% (Details).

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴