exegesis-cognito

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

Configure server

1import * as exegesisExpress from 'exegesis-express';
2import exegesisCognito from 'exegesis-cognito';
3
4
5async function createServer() {
6    const app = express();
7
8    const jwks = fs.readFileSync('config/jwks.json', 'utf8')
9
10    app.use(await exegesisExpress.middleware(
11        path.resolve(__dirname, './openapi.yaml'),
12        {
13            // Other options go here...
14            authenticators: {
15                bearerAuth: exegesisCognito( { jwks })
16            }
17        }
18    ));
19
20    const server = http.createServer(app);
21    server.listen(3000);
22}

Open API spec

1...
2paths:
3  '/things':
4    get:
5      operationId: getThings
6      x-exegesis-controller: thingController
7      security:
8        - bearerAuth: []
9...
10components:
11  securitySchemes:
12    bearerAuth:
13      type: http
14      scheme: bearer
15      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

1{
2    "user": {
3        "id": "ba5bcf72-4b20-4c06-bc6b-ffc710adb244",
4        "username": "jane",
5        "email_verified": false,
6        "email": "janeh@d.oe",
7        "roles": [
8            "mygroup"
9        ]
10    }
11}

Access token

1{
2  "user": {
3    "id": "ba5bcf72-4b20-4c06-bc6b-ffc710adb244",
4    "username": "niall"
5  }
6}

Sending a request

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

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

License