npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

buenro-amazon-cognito-passwordless-auth

v1.0.0

Published

Passwordless authentication with Amazon Cognito: FIDO2 (WebAuthn, support for Passkeys), Magic Link, SMS OTP Step Up

Downloads

1

Readme

Amazon Cognito Passwordless Auth

AWS Solution to implement Passwordless authenticaton with Amazon Cognito

Passwordless authentication improves security, reduces friction and provides better user experience for end-users of customer facing applications. Amazon Cognito provides features to implement custom authentication flows, which can be used to expand authentication factors for your application. This solution demonstrates several patterns to support passwordless authentication and provides reference implementations for these methods:

  • FIDO2: aka WebAuthn, i.e. sign with Face, Touch, YubiKey, etc. This includes support for Passkeys.
  • Magic Link Sign In: sign in with a one-time-use secret link that's emailed to you (and works across browsers).
  • SMS based Step-Up auth: let an already signed-in user verify their identity again with a SMS One-Time-Password (OTP) without requiring them to type in their password.

The reference implementation of each of these auth methods uses several AWS resources. This solution contains both CDK code (TypeScript) for the back-end, as well as front-end code (TypeScript) to use in Web, React and React Native to help developers understand the building blocks needed and expand/adjust the solution as necessary.

IMPORTANT: This AWS Solution is for demonstration purposes and uses several AWS resources, it is intended for developers with moderate to advanced AWS knowledge. If you plan to use these methods in production, you need to review, adjust and extend the sample code as necessary for your requirements.

Video Introduction

Here's a short (11m41s) video that explains and demonstrates the solution:

Solution Intro on YouTube

FIDO2 / WebAuthn

This solution includes components that implement FIDO2 authentication, i.e. sign with Face, Touch, YubiKey, etc. This includes support for Passkeys:

FIDO2 AWS Architecture

Included sample React component, for adding/changing/deleting authenticators:

For more details, see FIDO2

Magic Link Sign In

This solution includes components to support signing-in with a Magic Link:

Magic Link Architecture

Example e-mail:

For more details, see Magic Links

SMS based Step-Up auth

This solution includes components to support step-up auth, using SMS One-Time-Password (OTP):

SMS OTP Step Up AWS Architecture

Example SMS:

For more details, see SMS OTP Step up

Table of Contents

Installation

We've wrapped the sample code in a NPM package for convenient installation and use:

npm install amazon-cognito-passwordless-auth

Also, make sure to install the peer dependencies you need (e.g. React, AWS CDK).

Getting Started

To play around with the library we recommend you deploy the end-to-end example into your own AWS account. You can run the accompanying front end locally, and sign-in with magic links and FIDO2.

Basic Usage

First, deploy a CDK stack and instantiate the Passwordless construct:

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import { Passwordless } from "amazon-cognito-passwordless-auth/cdk";

class SampleTestStack extends cdk.Stack {
  constructor(scope?: Construct, id?: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const passwordless = new Passwordless(this, "Passwordless", {
      allowedOrigins: [
        "http://localhost:5173", // Mention all URLs you're exposing the web app on
      ],
      magicLink: {
        sesFromAddress: "[email protected]", // must be a verified domain or identity in Amazon SES
      },
      fido2: {
        allowedRelyingPartyIds: [
          "localhost", // Domain names that you wish to use as RP ID
        ],
      },
      smsOtpStepUp: {}, // leave this out to disable SMS OTP Step Up Auth. Likewise for magicLink and fido2
    });

    new cdk.CfnOutput(this, "ClientId", {
      value: passwordless.userPoolClients!.at(0)!.userPoolClientId,
    });
    new cdk.CfnOutput(this, "Fido2Url", {
      value: passwordless.fido2Api!.url!,
    });
  }
}

Then, in your web app's entrypoint (e.g. main.tsx):

import { Passwordless } from "amazon-cognito-passwordless-auth";

Passwordless.configure({
  cognitoIdpEndpoint:
    "<AWS region where the CDK stack was deployed to, e.g. eu-west-1>",
  clientId:
    "<Cognito User Pool Client ID, one of the outputs of the CDK stack>",
  fido2: {
    baseUrl:
      "<The base URL to the FIDO2 API, one of the outputs of the CDK stack>",
  },
  debug: console.debug, // Optional: adds logging
});

Now you're ready to use the library! E.g. in your web app you can do:

import {
  authenticateWithFido2,
  fido2CreateCredential,
} from "amazon-cognito-passwordless-auth/fido2";

// Register a new credential (e.g. Face ID / Touch) for use with this Relying Party
const { credentialId } = await fido2CreateCredential({
  friendlyName: "My iPhone",
});

// Initiate FIDO2 authentication
const { signedIn, abort } = authenticateWithFido2({ username: "alice" });

const { idToken, accessToken, refreshToken } = await signedIn;

React

For React we recommend you use the Passwordless hook for all your interactions with the library. E.g. the hook tracks the sign-in status (signInStatus) and gives easy access to the user's JWTs (tokens, tokensParsed).

To use the React hook, first wrap your app with the Passwordless context provider in your app's entrypoint (e.g. main.tsx):

import { PasswordlessContextProvider } from "amazon-cognito-passwordless-auth/react";

ReactDOM.createRoot(document.getElementById("root")).render(
  <PasswordlessContextProvider>
    <React.StrictMode>
      <App />
    </React.StrictMode>
  </PasswordlessContextProvider>
);

Then, inside your components, use the Passwordless hook:

import { usePasswordless } from "amazon-cognito-passwordless-auth/react";

function MyComponent() {
  const { tokensParsed, authenticateWithFido2, signInStatus, lastError, busy } =
    usePasswordless();

  if (signInStatus === "NOT_SIGNED_IN" || signInStatus === "SIGNING_IN") {
    return (
      <>
        <form
          onSubmit={(event) => {
            authenticateWithFido2({
              username: event.currentTarget.username.value,
            });
            event.preventDefault();
          }}
        >
          <input
            type="text"
            placeholder="username"
            name="username"
            disabled={busy}
          />
          <input type="submit" disabled={busy} />
        </form>
        {lastError && <p>{lastError.message}</p>}
      </>
    );
  }

  if (signInStatus !== "SIGNED_IN") {
    return <p>One moment please ...</p>;
  }

  return <p>Welcome, {tokensParsed?.idToken["cognito:username"]}!</p>;
}

This solution also includes sample React components, e.g. a prefab sample sign-in page. See examples and documentation here: README-REACT.md

Features

This library includes:

  • A CDK construct that deploys an Amazon Cognito User Pool with Custom Authorization configured to support the passwordless authentication flows (includes other AWS Services needed, notably DynamoDB and HTTP API).
  • Web functions to use in your Web Apps, to help implement the corresponding front-end.
  • React and React Native hooks, to make it even easier to use passwordless authentication in React and React Native.
  • React prebuilt components that you can drop into your webapp to get started with something that works quickly, as a basis for further development.

Other noteworthy features:

  • This library is built from the ground up in plain TypeScript and has very few dependencies besides aws-sdk and aws-cdk-lib. Most batteries are included:
    • The Magic Link back-end implementation has no dependencies
    • The FIDO2 back-end implementation only depends on cbor
    • The SMS Step-Up Auth back-end implementation only depends on aws-jwt-verify
    • The (plain) Web client implementation has no dependencies
    • The React Web client implementation only has a peer dependency on react itself
    • The React Native client implementation only depends on react-native-passkey
  • This library is fully compatible with AWS Amplify (JS library, aws-amplify), however it does not require AWS Amplify. If you just need Auth, this library should be all you need, but you can use AWS Amplify at the same time for any other features (and even for Auth too, as they can co-operate). See Usage with AWS Amplify.
  • The custom authentication implementations are also exported as separate functions, so you can reuse the code, configure them and tailor them in your own Custom Auth Functions. For example, you can use a custom JavaScript function to generate the HTML and Text contents of the e-mail with the Magic Links.

Security

See CONTRIBUTING for more information.

Keep Dependencies Up-to-date

This sample solution defines several peer dependencies that you must install yourself (e.g. AWS CDK, React). You must make sure to keep these dependencies updated, to account for any security issues that may be found (and solved) for these dependencies.

Token (JWT) Storage

By default, localStorage is used to store tokens (JWTs). This is similar to how e.g. AmplifyJS does it, and is subject to the same concerns. You may want to store tokens elsewhere, perhaps in memory only. You can do so by configuring a custom storage class, e.g.:

import { Passwordless } from "amazon-cognito-passwordless-auth";

class MemoryStorage {
  constructor() {
    this.memory = new Map();
  }
  getItem(key) {
    return this.memory.get(key);
  }
  setItem(key, value) {
    this.memory.set(key, value);
  }
  removeItem(key) {
    this.memory.delete(key);
  }
}

Passwordless.configure({
  ..., // other config
  storage: new MemoryStorage(),
});

Other Security Best Practices

This sample solution is secure by default. However, you should consider matching the security posture to your requirements, that might be stricter than the defaults:

Usage with AWS Amplify

This library by default uses the same token storage as Amplify uses by default, and thus is able to co-exist and co-operate with Amplify. That means that you can use this library to manage authentication, and use Amplify for other operations (e.g. Storage, PubSub).

After the user signed-in with this library, Amplify will recognize that sign-in as if it had managed the sign-in itself.

If you're using Amplify and this library together, you can use the following convenience methods to configure this library from Amplify configuration:

import { Passwordless } from "amazon-cognito-passwordless-auth";
import { Amplify } from "aws-amplify";

// Configure Amplify:
Amplify.configure({
  ...
})

// Next, configure Passwordless from Amplify:
Passwordless.configureFromAmplify(Amplify.configure());

// Or, to be able able to provide additional Passwordless configuration, do:
Passwordless.configureFromAmplify(Amplify.configure()).with({
  fido2: {
    baseUrl: "...",
  },
});

Usage in (plain) Web

See README.md

Usage in React

See README-REACT.md

Usage in React Native

See README-REACT-NATIVE.md

FAQ - Frequently Asked Questions

Who created this library?

The AWS Industries Prototyping team. We created this library initially to use in our own prototypes, that we build for customers. We thought it would benefit many customers, so we decided to spend the effort to open-source it.

Since we use this library ourselves, we'll probably keep it up-to-date and evolve it further. That being said, we consider this sample code: if you use it, be prepared to own your own fork of it.

Why is this on aws-samples, and not awslabs?

Having this repository be on aws-samples communicates most clearly that it is sample code. Users may run it as-is, but should be prepared to "own" it themselves.

We are considering to move it to awslabs in the future (which is why we released this under Apache-2.0 license, instead of MIT-0 which is common on aws-samples).

How have you tested the security posture of this solution?

If you use this solution, YOU must review it and be your own judge of its security posture.

Having said that, you should know that this solution was written by Amazon Cognito experts from AWS. We have run it through multiple internal reviews. We've used it for several of our projects. Amazon's application security team has reviewed and pentested it.

Can you also support other Infrastructure as Code tools than CDK?

This is currently out of scope, to keep maintenance effort manageable. However we'd like to track such requests: leave us a GitHub issue.

Can you also support other Client technologies such as VueJS, Angular, Ionic, etc?

This is currently out of scope, to keep maintenance effort manageable. However we'd like to track such requests: leave us a GitHub issue.

Can you also support other languages than JavaScript / TypeScript?

This is currently out of scope, to keep maintenance effort manageable. However we'd like to track such requests: leave us a GitHub issue.

License

This project is licensed under the Apache-2.0 License.