brianfoody-aws-utils v1.0.0

AWS Utils Library

Utility library for AWS Services with clean interfaces and to abstract complexity away.

Generated by projen.

Built through github actions.

Running

git clone  git@github.com:brianfoody/aws-utils.git
npx projen
npm run integration # you'll need to modify the testUtils to use your AWS account details etc..

Authenticator

Th first step is to create an authenticator. This allows a user to sign in and authenticate themselves. A providerId along with an access token should be returned.

A Cognito user pool is your usual authenticator in AWS land but this could also be a non AWS-related service like Apple Sign In. Ultimately we just want a JWT token that identifies you.

const authenticator = makeCognitoAuthenticator({
  config: {
    region,
    userPoolId: "eu-central-1_qJsskDss",
    clientId: "23s9w99ww",
  },
});

await authenticator.authenticate({
  username,
  password,
});

Authoriser

Once authenticated the next thing to do is authorise yourself with AWS and get your access credentials along with an identityId if supported.

If you have authenticated against a user pool, it will need to configured for this identity pool to get credential. If you have authenticated against Apple, the App ID will need to configured for this identity pool to get credentials. If you have authenticated against ... you get the idea

const authoriser = makeCognitoAuthoriser({
  config: {
    identityPoolId: "eu-central-1:39736276-2ef6-48b7-bc9b-5599792nd82",
    accountId: "927438389348",
    region,
  },
  authenticationProvider: authenticator,
});

Get credentials

We can now get our credentials from the authoriser.

const authorisation = await authoriser.authorise();

You will notice we pass trhe authenticator into the authoriser. This is because the authenticated token can expire and if so, the authoriser refreshes it before requesting credentials when you authorise.

If refresh fails then authorisation will fail -> SessionTimedOutException

If the user is not authorised to use the service it will fail -> AuthorisationRejectedException

If successful access key, secret and optionally identity id will be returned.

Authorise AWS Services

The best way to use AWS services is to create a library for them which uses the authorisation provider

const s3 = makeS3Storage({
  authoriser: authoriser,
  config: {
    bucketName:
      "core-infrastructure",
    region,
  },
});

Then when you call any operation on this it will ask the authorisation provider to authorise the request.

The authoriser will ensure the user is still authenticated and refresh if not.

And then the request will be sent to the AWS service with valid credentials.

Reloading in an app / website without logging in again

Each authenticator is passed a storage provider which can be used to store the authorisation information needed to refresh a session, generally a user and token.

I prefer this to AWS Amplify which hides the storage away from you. I've always found it nice to know what a library is doing and be able to easily customise it.

For example when porting auth if you control the storage it's really easy. If amplify does, it's a pain in the ass.