DEV Community: Cotter

Cotter + Cloudflare Workers + Google Calendar API: Build a Serverless Calendar Booking App

Putri Karunia — Tue, 03 Nov 2020 10:56:41 +0000

During this pandemic, scheduling a meeting has become more important than ever, be it for a conference call, a consultation, or just a friendly chat.

In this guide, we'll explore how to use Google Calendar's API to make your own calendar booking app (yes, it's a platform, so other people can log in and share their own calendar link!).

Build a Calendar Booking App with Cotter, Cloudflare Workers, and Google API

👉 Try out the live demo!

Calendar Booking App by Cotter

We'll use:

Cotter for logging in users and connecting to their Google Account.
Cloudflare Workers as a backend that will call Google Calendar API.
Google Calendar API for booking time slots in your users' calendar.
We'll also use React in this tutorial.

Why Cloudflare Workers?

Cloudflare workers allows you to deploy JavaScript code on Cloudflare's Edge network. This means you can write serverless code in Cloudflare workers and have it deployed across the globe. Your users will connect to the nearest Cloudflare network.

What about a database?

Cloudflare workers offers a Key-Value store that can keep consistent data across their locations. Note that currently, it's "eventually consistent" which means it might take some time (max 60s) for an update to be available globally.

Why do we need a backend?

The biggest reason why we need a backend in this tutorial is that we need a secure environment to store our API Secret Key which is used to get Google's Access Tokens from Cotter.

We don't need a database or a key-value store for our use case, so Cloudflare Workers is perfect for deploying a simple backend code that authenticates your users and calls Google's API

TLDR

To try it out right now, you can use our CodeSandbox and follow the steps below to set up the Cloudflare Backend:

1. Create a project at Cotter, then add Sign in with Google to your Login Form

Follow these instructions to set up Google OAuth 2.0 Credentials and connect it to Cotter.
Make sure you added https://www.googleapis.com/auth/calendar for the scope.
Enable Google for your form: Go to Branding > Magic Link Form > click the checkmark to enable Google Sign In
Add Cotter's Login Form to your website

2. Use this CodeSandbox to get the calendar-booking React App. Update src/constants.js with your Cotter API KEY ID. You can also clone the project from the Github Repo.

3. Setup Cloudflare Worker, make 3 workers with subdomains:

checkconnection.YOURSUBDOMAIN.workers.dev
createevent.YOURSUBDOMAIN.workers.dev
disconnect.YOURSUBDOMAIN.workers.dev

Copy the code from our Github for your Cloudflare Worker.

4. Enable Google Calendar API in your Google project

Enable Google Calendar API to the project that you used to create Google OAuth 2.0 Credentials.

How it works

Here's the outline of the things that we needed to do to build this platform:

Users will be using "Sign in with Google" to get an access token from Google. This access token is accessible via Cotter's API.
Make API endpoints at your Cloudflare Worker which would 1) call Cotter's API to get the user's Google Access Token, and 2) call Google's API using that Google access token.

Logging In

Getting Google's Access Token via Google Sign In

To access Google's Calendar API, you'll need a Google Access Token for the user to modify their calendar. This means the user needs to connect their Google Account. Using Cotter as your authentication service, this can be done in 2 ways:

If the user logged-in using Google Sign In , you can automatically access their Google Access Token by calling Cotter's API.
If the user logged-in with their email , you can provide a button on the dashboard and ask them to connect their Google Account. After that, you can access their Google Access Token by calling Cotter's API.

When your user logged-in using Cotter, you'll get a Cotter Access Token. We'll use this access token to protect our API Endpoints that we're going to make in Cloudflare Workers.

1) Adding Sign in with Google to your Login Form

Follow these instructions to set up Google OAuth 2.0 Credentials and connect it to Cotter. Make sure you added https://www.googleapis.com/auth/calendar for the scope.
Enable Google for your form: Go to Branding > Magic Link Form > click the checkmark to enable Google Sign In
Add Cotter's Login Form to your website

Using Cotter's React SDK, you can easily use React context provider to keep track of the authentication state (i.e. is the user logged-in, etc).

yarn add cotter-react

import React from "react";
import { Router } from "@reach/router";
import LoginPage from "../login";
import { CotterProvider, LoginForm } from "cotter-react"; // 👈 Import Cotter Provider

function App() {
  return (
    // 👇 1) Wrap CotterProvider around your ROOT COMPONENT
    // Copy paste your Cotter API Key ID below.
    <CotterProvider apiKeyID="<YOUR API KEY ID>">
      <Router>
        <LoginPage path="/" />
      </Router>
    </CotterProvider>
  );
}

function LoginPage() {
  return (
      <div className="LoginPage__form-container">
      {/* 👇 2) Show the login form */}
      <LoginForm
          onSuccess={(response) => console.log(response)}
          onError={(err) => console.log(err)}
      />
      </div>
  );
}

export default App;

2) Checking if the user is logged-in in your dashboard

Using CotterContext you can check if the user is logged-in and get their Cotter Access Token.

import { CotterContext, withAuthenticationRequired } from "cotter-react"; // 👈 Import the user context
import React, { useContext, useEffect, useState } from "react";
import "./styles.css";

function DashboardPage() {
  const { user, getAccessToken, isLoggedIn } = useContext(CotterContext); // Get the logged-in user information
  const [accessToken, setaccessToken] = useState(null);

  useEffect(() => {
    if (isLoggedIn) readAccessToken();
  }, [isLoggedIn]);

  // Get the Cotter access token to be used for our API call
  // (for now, we'll just display it in the dashboard)
  const readAccessToken = async () => {
    const token = await getAccessToken();
    setaccessToken(token?.token);
  };
  return (
      <div className="container">
        User ID: {user?.ID} <br />
        User email: {user?.identifier} <br />
        Cotter Access Token: {accessToken}
      </div>
  );
}

// Protect this page using the `withAuthenticationRequired` HOC
// If user is not logged-in, they'll be redirected to the `loginPagePath`
export default withAuthenticationRequired(DashboardPage, {
  loginPagePath: "/",
});

Wrap your component around withAuthenticationRequired to automatically redirect your user to login if the user is not logged-in
Use isLoggedIn to check if the user is logged-in, and user to get the logged-in user information.
Use getAccessToken to get the Cotter Access Token that we'll use to call our API endpoints.

3) Checking if the user has connected their Google Account

We'll make an endpoint for this on our Cloudflare Worker which will call Cotter's API to see if the user has connected their Google Account.

4) Show a button to connect Google Account from the Dashboard

If the user has not connected their Google Account (they didn't log in using Google), show a button to connect Google Account. Call this function with your button to connect their Google Account:

import { CotterContext } from "cotter-react"; // 👈 Import the user context

function DashboardPage() {
  ...
  const { getCotter } = useContext(CotterContext);

  // If the user hasn't connected their Google Account,
  // show a button to call this function to connect
  const connectToGoogle = async () => {
    var cotter = getCotter();
    cotter.connectSocialLogin("GOOGLE", accessToken);
  };

  return (
    <div className="DashboardPage__container">
     ...
      <button onClick={connectToGoogle}>Connect Google Account</button>
    </div>
  );
}

Cloudflare Worker Endpoints

Making API endpoints at Cloudflare Workers to call Google's API

Once you got the login flow working, you can start making the endpoints at Cloudflare Workers that would call Google's API. Specifically, you'll need these endpoints:

An API to check if the user has connected their Google Account
An API to modify their Google Calendar

Create a Cloudflare Account and Setup Workers

Go to Cloudflare and sign up with your email and password. You don't need to add a domain. When asked to add a domain, if you don't have a domain, you can skip this by clicking on the Cloudflare logo.
Click Workers on the right side of your dashboard, and add a subdomain that you want for your backend API endpoint. Choose the Free Plan and verify your email.

Create a Test Worker to see how this works

Press Create a Worker. You can see that you have a handler script on the left side, and a playground to test your API endpoint. Click Send and you should see hello world as the response.
That's it, you've just created an endpoint! To save this endpoint, press Save and Deploy.

Creating Endpoints

Notice that you can only change the sub-subdomain, not the path.

To be able to handle different paths, you'll need to use their CLI and use a router. That's too advanced for this tutorial, so we'll just have our endpoints on different subdomains.

Endpoints

Endpoint #1: `checkconnection`

Check if the user has Google Connected.

Create a worker, and change the name to checkconnection . We'll define our endpoint as the following:

$ curl --request GET \
    --header 'Authorization: Bearer <COTTER_ACCESS_TOKEN>' \
    --url 'https://checkconnection.YOUR_SUBDOMAIN.workers.dev?userid=<COTTER_USER_ID>'

// If Google account is connected:
{"connected": true}

// If not:
{"connected": false}

Here are the things that we'll need to do:

Check if the Cotter access token is valid
Call Cotter's API to check if this user has a Google Access Token

Code & Env Variables

Copy the code from our Github repo.

Add the Cotter Api Keys as environment variables

Go to the Settings tab, and press Add Variable. Add both the API_KEY_ID and API_SECRET_KEY from Cotter, then press Save.

Endpoint #2: `createevent`

Create a Google Calendar Event

Before we start, you'll need to Enable Google Calendar API to the project that you used to create Google OAuth 2.0 Credentials.

Create another worker, and change the name to createevent . We'll define our endpoint as the following:

$ curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"start_time":"2020-11-02T10:00:00-08:00","end_time":"2020-11-02T10:15:00-08:00","attendee_email":"attendee@gmail.com","meeting_title":"John Doe <> Jane Doe"}' \
  --url 'https://createevent.YOUR_SUBDOMAIN.workers.dev?userid=<COTTER_USER_ID>'

start_time & end_time should be in formatted according to RFC3339
attendee_email is the email of the attendee (just 1 email)
meeting_title is the title of the meeting

{
    "success": true,
    "event": { ... Google's Event Obj }
}

Success Response

{
    "success": false,
    "error": "Error message"
}

Error Response

This URL doesn't require an authorization header because we want anyone to be able to book an appointment without having to log in to your platform first.

Here are the things that we'll need to do:

Call Cotter's API to get the user's Google Access Token
Use Google API Event insert endpoint using the Google Access Token

Code & Env Variables

Copy the code from our Github repo.

Add the Cotter Api Keys and Google Credentials as environment variables

Again, we need to add the API_KEY_ID and API_SECRET_KEY environment variables from Cotter API Keys.
We also need to add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variable from Google OAuth Credentials.

Endpoint #3: `disconnect`

Disconnect the user's Google Account

Create another worker, and change the name to disconnect . We'll define our endpoint as the following:

$ curl --request DELETE \
    --header 'Authorization: Bearer <COTTER_ACCESS_TOKEN>' \
    --url 'https://disconnect.YOUR_SUBDOMAIN.workers.dev?userid=<COTTER_USER_ID>'

// If disconnected successfully
{"success": true}

Here are the things that we'll need to do:

Check if the Cotter access token is valid
Call Cotter's API to delete a user's Google Access Token

Code & Env Variables

Copy the code from our Github repo.

Add the Cotter Api Keys as environment variables

Again, we need to add the API_KEY_ID and API_SECRET_KEY environment variables from Cotter API Keys.

That's it!

Build a Calendar Booking App with Cotter, Cloudflare Workers, and Google API

You should now have your backend API set up and Google Sign In set up, all you need to do is connect them in your frontend. If you need some references on how to do that, check out our Github repo:

👉 Try the live demo, it's fully functional

Calendar Booking App by Cotter

Questions & Feedback

Come and talk to the founders of Cotter and other developers who are using Cotter on Cotter's Slack Channel.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

If you need help, ping us on our Slack channel or email us at team@cotter.app.

The Simplest Way to Authorize Github OAuth Apps with Next.js and Cotter

Putri Karunia — Tue, 08 Sep 2020 06:55:07 +0000

Add "Sign in with Github" in one click to authorize your Github OAuth App and access Github REST API using Cotter and Next.js.

Cotter just launched a Github Login integration 🎉. This means you can easily log your users in and get an access token to enable Github integrations in your app.

What we're building

We're going to build a website with Next.js that allows your users to login with email or with Github and get a list of their public and private repositories.

Overview

Let's Start - Make our Home Page
Let's see how this works before moving on to Github API
Designing our API endpoints to get data from Github
Showing the Repo List in our Dashboard Page
But, what if the user didn't Sign in with Github?

Let's Start – Make our Home Page

Create your Next.js project

Start with creating a new Next.js project by running the code below, and follow the instructions.

yarn create next-app

Add a Login Form in the Home Page

We're using Cotter for the Login form to quickly enable an Email Magic Link login and Sign in with Github.

Add Cotter as a dependency

yarn add cotter

Add a Login Form and a Title

Modify our home page at pages/index.js. We'll start with the simple Email Magic Link login. Remove everything in pages/index.js and add a title and Cotter's login form:

import { useEffect } from "react";
import styles from "../styles/Home.module.css";
import Cotter from "cotter"; // 1️⃣ Import Cotter
import { useRouter } from "next/router";

export default function Home() {
  const router = useRouter();
  // 2️⃣ Initialize and show the form
  useEffect(() => {
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    cotter
      .signInWithLink() // use .signInWithOTP() to send an OTP
      .showEmailForm() // use .showPhoneForm() to send magic link to a phone number
      .then((response) => {
        console.log(response); // show the response
        router.push("/dashboard");
      })
      .catch((err) => console.log(err));
  }, []);

  return (
      <div className={styles.container}>
        <h1 className={styles.subtitle}>Welcome to my Github App</h1>

        {/* 3️⃣ Put a <div> that will contain the form */}
        <div id="cotter-form-container" style={{ width: 300, height: 300 }} />
      </div>
  );
}

pages/index.js

You'll need an API_KEY_ID, create a new project, and copy the API_KEY_ID from the dashboard. The code above should give you a simple Login page that looks like this:

Enable Github Login

The documentation laid out the steps you need to take to enable Social Login to your login form. We'll follow it step by step below:

First, create a Github OAuth App. Summarizing Github's documentation, you should do the following:

Click on your profile picture on the top right > Settings > Developer Settings > OAuth Apps > New OAuth App
Fill in your Application Name, Homepage URL, and description based on your app.
Fill in https://www.cotter.app/api/v0/oauth/token/callback/GITHUB for the Authorization callback URL.
Then click Register Application.

Go to your Cotter Dashboard and add a Social Login connection.

Go to Dashboard > Social Login > New Login Connection > Github. Then copy your Client ID and Client Secret from Github. We'll add the repo scope because we want to get the users' repository data.

Add the Client ID, Client Secret, and repo scope

Press Create to create the login connection.

Show Github Login on your Form

Now that your Social Login connection is set up, we can show it in our Login Form. Go to Dashboard > Branding > Magic Link. Check the box for Github under Social Login Providers.

Add Github Login to your Form

Press Save to update your customization.

You should now see the Sign in with Github button in our Next.js app.

Let's see how this works before moving on to Github API

We'll go over how the login works, how you can authenticate users to your backend, and how you can get Github's access token to access private repo data.

1. Let's try logging in with your email address first.

Enter your email address and press "Sign in Without Password". Tap the magic link in your email and you should be logged-in.

Now check your console log, you should see something like this:

{
  "token": {...},
  "email": "team@cotter.app", // 👈 the user's email
  "oauth_token": {
    "access_token": "eyJhbGciOiJFUzI...", // 👈 access token
    "id_token": "eyJhbGciOiJFUzI1...",
    "refresh_token": "236:QDVxW6...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "auth_method": "OTP"
  },
  "user": {
    "ID": "abcdefgh-abcd-abcd-9959-67ebae3cdfcf", // 👈 user ID
    "issuer": "abcdefgh-abcd-abcd-81ad-5cc8b69051e8",
    "identifier": "team@cotter.app",
    ...
  }
}

Note: If your console log can't be expanded because you redirected to /dashboard, comment out the redirection part router.push("/dashboard")

Three things that you should take note of are the user's email , the Cotter User ID, and the access_token that we will use to protect our API endpoints. These information will be available to you at anytime the user is logged-in by calling cotter.tokenHandler.getAccessToken() and cotter.getLoggedInUser()

2. Let's try logging-in again but with your Github account that has the same email address

When you used a Github account that has the same address as an existing account, you should see a prompt asking if you'd like to link the accounts:

If you're using a Github account that has an email address that is not recognized, then it will automatically create a new user. You'll see the same JSON response like the above when the user has successfully log in with Github.

Designing our API endpoints to get data from Github

We will have a dashboard page that will call our API endpoint at /api/repo to get a list of repositories owned by the user.
We'll make an API endpoint /api/repo that will:

Check if the user is logged-in
If logged-in, get the user's Github Access Token from Cotter's API
Call Github API to get the authenticated user's repository list

Make our API endpoint at `/api/repo`

Our endpoint will look like this:

GET http://localhost:3000/api/repo
Authorization: Bearer <Cotter Access Token>

1. Make a function to handle API calls to `/api/repo`

Next.js gives you a neat way to add server code that can handle API requests. To handle an API call to /api/repo, make a file pages/api/repo.js. Then, we'll add a skeleton handler function with a list of things that we need to do:

const handler = async (req, res) => {
  // TODO: Check if Authorization Header has a valid access_token
  // TODO: Parse the access_token to get cotter_user_id to
  // TODO: Call Cotter's API to get Github Access Token for the user
  // TODO: Call Github API to get the repository data
};

export default handler;

pages/api/repo.js

2. Check if the Authorization Header have a valid access token

We'll make a separate function above our handler function to do this check. We'll be using Cotter's client library to help us validate the access token.

yarn add cotter-node

// 1) Import Cotter
import { CotterValidateJWT } from "cotter-node";

const checkJWT = (handler) => async (req, res) => {
  // 2) Check that the access_token exists
  if (!("authorization" in req.headers)) {
    res.statusCode = 401;
    res.end("Authorization header missing");
    return;
  }
  const auth = await req.headers.authorization;
  const bearer = auth?.split(" ");
  const token = bearer?.length > 0 && bearer[1];

  // 3) Validate the access_token
  var valid = false;
  try {
    valid = await CotterValidateJWT(token);
  } catch (e) {
    console.log(e);
    valid = false;
  }
  if (!valid) {
    res.statusCode = 403;
    res.end("Authorization header is invalid");
    return;
  }

  // 4) Pass the access token to the next handler
  req.access_token = token;
  handler(req, res);
};

const handler = async (req, res) => {...};

// 5) We are passing our handler function into
// `checkJWT` so that `checkJWT` will be run first
// before our `handler` is run.
export default checkJWT(handler);

pages/api/repo.js

What we did was pretty simple:

First, we check if the Authorization header exists
If it exists, then we check if the access_token is valid using Cotter's helper function.
Then we call checkJWT(handler) to run the check and then run the handler if the check passed.

3. Get the Cotter User ID from the `access_token`.

We will need this for our API call to Cotter. The access_token is a JWT token that contains the user's Cotter User ID. Check here for the full spec. We'll use another Cotter helper function to parse the access token and get the Cotter User ID.

yarn add cotter-token-js

import { CotterValidateJWT } from "cotter-node";
// 1) Import Cotter Token
import { CotterAccessToken } from "cotter-token-js";

const checkJWT = (handler) => async (req, res) => {...};

const handler = async (req, res) => {
  // Parse the access_token to get cotter_user_id
  const decodedToken = new CotterAccessToken(req.access_token);
  const cotterUserID = decodedToken.getID();
  // TODO: Call Cotter's API to get Github Access Token for the user
  // TODO: Call Github API to get the repository data
};

export default checkJWT(handler);

pages/api/repo.js

4. Get Github Access Token from Cotter API

The API to get a Social Provider access token from Cotter looks like this

curl -XGET \
-H 'API_KEY_ID: <COTTER API KEY ID>' \
-H 'API_SECRET_KEY: <COTTER API SECRET KEY>' \
'https://www.cotter.app/api/v0/oauth/token/GITHUB/<COTTER USER ID>'

Let's install axios and create our request

yarn add axios

import axios from "axios"; // Import axios

const checkJWT = (handler) => async (req, res) => {...};

const handler = async (req, res) => {
  // Parse the access_token to get cotter_user_id
  ...

  // Call Cotter's API to get Github Access Token for the user
  let githubAccessToken = "";
  const config = {
    headers: {
      API_KEY_ID: process.env.COTTER_API_KEY_ID,
      API_SECRET_KEY: process.env.COTTER_API_SECRET_KEY,
    },
  };
  try {
    let resp = await axios.get(
     `https://www.cotter.app/api/v0/oauth/token/GITHUB/${cotterUserID}`,
      config
    );
    githubAccessToken = resp.data.tokens?.access_token;
  } catch (err) {
    res.statusCode = 500;
    res.end("Fail getting Github access token from Cotter API");
    return;
  }
  // TODO: Call Github API to get the repository data
};

export default checkJWT(handler);

pages/api/repo.js

As you can see we're storing our secrets in an environment variable. Get your API_KEY_ID and API_SECRET_KEY from the dashboard and export it in your terminal, then run yarn dev.

$ export COTTER_API_KEY_ID=<API KEY ID>
$ export COTTER_API_SECRET_KEY=<API SECRET KEY>
$ yarn dev

5. Call Github API to get the repositories list

Github's API to get the list of repositories of the authenticated user looks like this:

curl \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Authorization: token <GITHUB ACCESS TOKEN>" \
  "https://api.github.com/user/repos"

Let's make the request using axios and the Github Access Token that we get in the earlier step.

const handler = async (req, res) => {
  // Parse the access_token to get cotter_user_id to
  ...
  // Call Cotter's API to get Github Access Token for the user
  ...

  // Call Github API to get the repository data
  const githubConfig = {
    headers: {
      Accept: "application/vnd.github.v3+json",
      Authorization: `token ${githubAccessToken}`,
    },
  };
  try {
    let resp = await axios.get(
      `https://api.github.com/user/repos`,
      githubConfig
    );
    // We only want to show the repo name and url
    const repoData = resp.data?.map((repo) => ({
      full_name: repo.full_name,
      url: repo.html_url,
    }));
    res.statusCode = 200;
    res.json(repoData);
    return;
  } catch (err) {
    res.statusCode = 500;
    res.end("Fail getting repostories from Github API");
    return;
  }
};

export default checkJWT(handler);

pages/api/repo.js

That's it, let's try our API endpoint

Copy your access token from the console log when logging in and run:

curl \
  -H "Authorization: Bearer <COTTER ACCESS TOKEN>" \
  "http://localhost:3000/api/repo"

You should see the following response:

[
  {
    "full_name": "putrikarunia/project1",
    "url": "https://github.com/putrikarunia/project1"
  },
  {
    "full_name": "putrikarunia/project2",
    "url": "https://github.com/putrikarunia/project2"
  },
  {
    "full_name": "putrikarunia/project3",
    "url": "https://github.com/putrikarunia/project3"
  }
]

Response from our backend at /api/repo

Showing the Repo List in our Dashboard Page

Make the Dashboard Page

Add a dashboard page by making a file at pages/dashboard.js. Using useEffect we will call our API endpoint to get the repositories, and put the results in our React state:

import { useEffect, useState } from "react";
import styles from "../styles/Home.module.css";
import Cotter from "cotter";
import axios from "axios";

export default function Dashboard() {
  const [err, seterr] = useState(null);
  const [repos, setrepos] = useState([]);

  // Get a list of repositories
  useEffect(() => {
    getRepositories();
  }, []);

  const getRepositories = async () => {
    // 1️⃣ Get Access Token for Logged-in User
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    const accessToken = await cotter.tokenHander.getAccessToken();

    // 2️⃣ Make the request to our `/api/repo` endpoint
    const config = {
      headers: {
        Authorization: `Bearer ${accessToken?.token}`,
      },
    };
    try {
      let resp = await axios.get("/api/repo", config);
      setrepos(resp.data);
    } catch (err) {
      seterr(JSON.stringify(err.response?.data));
    }
  };

  return (
    <div className={styles.container}>
      <h1 className={styles.subtitle}>
        Welcome! Here's a list of your Github Repos
      </h1>
      {/* Show any error here */}
      <div style={{ color: "#FF0000" }}>{err}</div>

      {/* 3️⃣ Show the list of repositories */}
      <div className={styles.main}>
        {repos.map((repo) => (
          <div className={styles.card}>
            <h3>{repo.full_name}</h3>
            <a href={repo.url}>{repo.url}</a>
          </div>
        ))}
      </div>
    </div>
  );
}

pages/dashboard.js

Let's go over what we did:

We added 2 React states, err and repos, to show errors and the repo data.
When the component mounts, we call getRepositories which first gets the user's access token using Cotter's function cotter.tokenHandler.getAccessToken(), then calls an API request to our backend endpoint at /api/repo.
When the API call is successful, the function will update our repos state with the list of repositories, or show an error.

If you sign-in with Github, then go to `localhost:3000/dashboard` , you'll see the following:

Don't forget to uncomment the redirection part in /pages/index.js : router.push("/dashboard")

A list of your Github Repositories

Add a NavBar to Log Out or Log In and navigate between pages

Let's add a Navbar component to help our users navigate our website. Make a file /components/Navbar/index.js in your project directory.

import { useState, useEffect } from "react";
import Link from "next/link";
import Cotter from "cotter";

export default function Navbar() {
  const [loggedIn, setloggedIn] = useState(false);
  const [email, setemail] = useState(null);
  useEffect(() => {
    checkLoggedIn();
  }, []);

  // TODO: Check if the user is logged-in
  const checkLoggedIn = async () => {};

  // TODO: Log out the user
  const logOut = () => {};

  return (
    <div style={{ display: "flex", justifyContent: "flex-end" }}>
      {loggedIn ? (
        <div style={{ padding: 20 }} onClick={logOut}>
          Log Out
        </div>
      ) : (
        <Link href="/">
          <a style={{ padding: 20 }}>Log In</a>
        </Link>
      )}

      {loggedIn && <div style={{ padding: 20 }}>{email}</div>}
      <Link href="/dashboard">
        <a style={{ padding: 20 }}>Go to Dashboard</a>
      </Link>
    </div>
  );
}

components/Navbar/index.js

We added a loggedIn and email state. If the user is logged-in, we'll display the Log Out button and the user's email, otherwise we'll display the Login button.
The function checkLoggedIn will check if the user is logged in and update the loggedIn state and set the user's email state
We also added a function called logOut to log out the user.

Make the `checkLoggedIn` function

We can do this using Cotter's function by checking if an access token exists. Update your checkLoggedIn function:

  const checkLoggedIn = async () => {
    const cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    const accessToken = await cotter.tokenHander.getAccessToken();
    if (accessToken?.token.length > 0) {
      setloggedIn(true);
      const user = cotter.getLoggedInUser();
      setemail(user?.identifier);
    } else {
      setloggedIn(false);
    }
  };

components/Navbar/index.js

Make the `logOut` function

We can also do this by calling Cotter's cotter.logOut() function. Update your logOut function:

  const logOut = async () => {
    const cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    await cotter.logOut();
    setloggedIn(false);
    window.location.href = "/";
  };

components/Navbar/index.js

Import the Navbar in your Home Page and Dashboard Page

In /pages/index.js:

import Navbar from "../components/Navbar";

export default function Home() {
  ...
  return (
    <>
      <Navbar /> // Add the navbar
      <div className={styles.container}>...</div>
    </>
  );
}

pages/index.js

In /pages/dashboard.js:

import Navbar from "../components/Navbar";

export default function Dashboard() {
  ...
  return (
    <>
      <Navbar /> // Add the navbar
      <div className={styles.container}>...</div>
    </>
  );
}

pages/dashboard.js

Great! Now our website works well and users can log in/log out and get their Repositories list.

But, what if the user didn't Sign in with Github?

If the user didn't Sign in with Github, then we wouldn't get Github's Access Token, and it will return an error like this:

How do we fix this?

Fortunately, Cotter has a function to allow logged-in users to Connect a Github Account of their choosing to their current account. This means we can add a button in the dashboard that tells the user to Connect Github if we get this error.

Add a button to Connect Github if not connected yet.

Following the guide to Connect a Github account to an Existing User, we'll add a function and a button at pages/dashboard.js

import Cotter from "cotter";
export default function Dashboard() {
  ...

  // Get a list of repositories
  useEffect(() => {...}, []);

  const getRepositories = async () => {...};

  const connectToGithub = async () => {
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    const accessToken = await cotter.tokenHandler.getAccessToken();
    cotter.connectSocialLogin("GITHUB", accessToken?.token); // pass in the provider's name
  };

  return (
    <>
      <Navbar />
      <div className={styles.container}>
        {/* Show any error here */}
        ...

        {/* If there's no Github access token, show a button to connect a Github account */}
        {err?.includes("Fail getting Github access token from Cotter API") && (
          <div className={styles.card} onClick={connectToGithub}>
            Connect Github
          </div>
        )}

        {/* Show the list of repositories */}
        ...
      </div>
    </>
  );
}

pages/dashboard.js

Now let's try logging in with an email that is not associated with your Github account using the Email Address field. You should see something like this:

Show a Connect Github button if the user doesn't have any Github Account connected

Press Connect Github , and it will connect your currently logged-in Github Account with this email address.

If you log out and log in again with Github, you will now be logged-in to this new email address.

How do I disconnect a Github Account

We won't cover this in the tutorial, but you can use our API endpoint to delete a connection.

That's it!

We now have a working Github API integration with a simple way to get your user's Github Access Token.

What's Next?

There's a lot of things that you can do using Github's API.

Check out the complete list of Github's REST API here.
See the code for this tutorial in our Github repo.

Questions & Feedback

Come and talk to the founders of Cotter and other developers who are using Cotter on Cotter's Slack Channel.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

If you need help, ping us on our Slack channel or email us at team@cotter.app.

How to Make an Interactive Todo List CLI using Python with an Easy Login Mechanism

Putri Karunia — Thu, 27 Aug 2020 18:48:01 +0000

Build your own Todo List CLI with Python using packages like Click, PyInquirer, and Cotter in minutes!

There a ton of awesome packages that helps you build a beautiful CLI, some are covered in this article Building Beautiful Command Line Interfaces with Python.

We're going to use some of them to make a nice and interactive todo list CLI.

The API

We're going to use a ready-made REST API that helps us store and update the todo list. The API is accessible on https://cottertodolist.herokuapp.com/ and you can find the source code and documentation at the Github Repo.

The CLI

To make the CLI, we'll use several packages:

CLI functionalities and prompts: Click, and PyInquirer
Authentication: Cotter

Get the full code for this tutorial in Cotter's Github.

Let's start with a super simple CLI

In your project directory, let's start by making a virtualenv:

python -m venv venv/

Then activate the virtual environment with the source command:

source venv/bin/activate

Now let's install click to make our simple cli:

pip install click

Then make a file for our CLI – let's call it cli.py and we'll make a simple greet command.

# cli.py
import click

@click.group()
def main():
    """ Simple CLI that will greet you"""
    pass

@main.command()
@click.argument('name')
def greet(name):
    """This will greet you back with your name"""
    click.echo("Hello, " + name)


if __name__ == "__main__":
    main()

This is how it looks like when run:

❯ python cli.py greet Putri
Hello, Putri

Now let's build our Todo List CLI.

Let's check our Todo List API documentation. An example request to show all lists looks like this:

### Show all lists
GET http://localhost:1234/list
Authorization: Bearer <access_token>

As you can see our API requires an access_token to only allow owners to view and update the todo list.

Start with Registering/Logging-in our users to the API

The first thing we need to do is to authenticate our users and register it to the Todo list API. The API looks like this:

### Login or Register a user using Cotter's response
### From the Python SDK
POST http://localhost:1234/login_register
Content-Type: application/json

{
    "oauth_token": {
        "access_token": "eyJhbGciOiJF...",
        "id_token": "eyJhbGciOiJFUzI...",
        "refresh_token": "40011:ra78TcwB...",
        "expires_in": 3600,
        "token_type": "Bearer",
        "auth_method": "OTP"
    }
}

To do this, we'll use Cotter's Python SDK to generate the oauth_tokens then send it to the todo list API.

Logging-in with Cotter

First, install Cotter using:

pip install cotter

Then, let's update our cli.py to add a login function:

# cli.py
import click
import os
import cotter

# 1️⃣ Add your Cotter API KEY ID here
api_key = "<COTTER_API_KEY_ID>"

@click.group()
def main():
    """ A Todo List CLI """
    pass

@main.command()
def login():
    """Login to use the API"""
    # 2️⃣ Add a file called `cotter_login_success.html`
    # 3️⃣ Call Cotter's api to login
    port = 8080 # Select a port
    response = cotter.login_with_email_link(api_key, port)

    click.echo(response) 


if __name__ == "__main__":
    main()

You'll need an API_KEY_ID from Cotter, which you can get from the Dashboard.

Following the SDK instructions, you'll also need an HTML file called cotter_login_success.html in your project directory. Copy cotter_login_success.html from the SDK's example folder in Github. Your project folder should now contain 2 files:

project-folder
|- cli.py
|- cotter_login_success.html

Now let's run the CLI and try to log in. You should see something like this:

❯ python cli.py login
Open this link to login at your browser: https://js.cotter.app/app?api_key=abcdefgh-c318-4fc1-81ad-5cc8b69051e8&redirect_url=http%3A%2F%2Flocalhost%3A8080&state=eabgzskfrs&code_challenge=zBa9xK4sI7zpqvDZL8iAX9ytSo0JZ0O4gWWuVIKTXU0&type=EMAIL&auth_method=MAGIC_LINK

This should also open your browser where you can enter your email and login.

Once you're done logging-in, you should see the following response in your terminal:

{
  "oauth_token": {
    "access_token": "eyJhbGciOiJFU...",
    "id_token": "eyJhbGciOiJF...",
    "refresh_token": "40291:czHCOxamERp1yA...Y",
    "expires_in": 3600,
    "token_type": "Bearer",
    "auth_method": "OTP"
  },
  "identifier": {...},
  "token": {...},
  "user": {...}
}

This is perfect for our /login_register API endpoint, so let's send the response from login to that endpoint inside our login function.

Register or Login the user to the todo list API

First, we need to install requests to call HTTP requests:

pip install requests

Update our login function inside cli.py to the following:

# cli.py
import requests

@main.command()
def login():
    """Login to use the API"""
    # Add a file called `cotter_login_success.html`
    # Call Cotter's api to login
    port = 8080 # Select a port
    response = cotter.login_with_email_link(api_key, port)

    # 1️⃣ Add your Cotter API KEY ID here
    url = 'https://cottertodolist.herokuapp.com/login_register'
    headers = {'Content-Type': 'application/json'}
    data = response
    resp = requests.post(url, json=data, headers=headers)

    if resp.status_code != 200:
        resp.raise_for_status()

    click.echo(resp.json())

You should now see a response {'user_id': '274825255751516680'} which means we have successfully registered or logged-in our user.

Storing the oauth_tokens for later use
We don't want to ask the user to login every time we need the access_token. Fortunately, Cotter already provides a function to easily store and get (and automatically refresh) the access_token from a file.

Update your login function by storing the token just before echoing the response:

# cli.py
from cotter import tokenhandler
token_file_name = "cotter_token.json"

@main.command()
def login():
    ...

    tokenhandler.store_token_to_file(response["oauth_token"], token_file_name)

    click.echo(resp.json())

Create a Todo List

Our create todo list API looks like this:

### Create a new Todo list
POST http://localhost:1234/list/create
Authorization: Bearer <access_token>
Content-Type: application/json

{
    "name": "Web Repo"
}

Let's add a function called create in our cli.py below our login function

# cli.py
@main.command()
@click.option('--name', prompt='List name', help='Name for your new todo list')
def create(name):
    """Create a todo list"""
    # Get access token
    access_token = tokenhandler.get_token_from_file(token_file_name, api_key)["access_token"]

    # Construct request
    url = "https://cottertodolist.herokuapp.com/list/create"
    headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer ' + access_token}
    data = { "name": name }
    response = requests.post(url, json=data, headers=headers)

    if response.status_code != 200:
        response.raise_for_status()

    click.echo("List " + name + " created!")

The function above takes an argument called --name (it'll ask you for the name of the list), then call the API with our access token. If you run it, it'll look like this:

❯ python cli.py create
List name: Web Repo
List Web Repo created!

Add a Task to the list

To add a task to a list, the API looks like this:

### Create a Task within a list
### name = List name, task = Task name/description
POST http://localhost:1234/todo/create
Authorization: Bearer <access_token>
Content-Type: application/json

{
    "name": "Web Repo",   
    "task": "Update favicon.ico"
}

Since the user might have more than one list, we want to ask them to choose which list they want to use. We can use PyInquirer to make a nice prompt with multiple options. First, install PyInquirer:

pip install PyInquirer

Then add a function called add in our cli.py.

# cli.py
# Import PyInquirer prompt
from PyInquirer import prompt

@main.command()
def add():
    """Create a todo task for a list"""
    # Get access token from file
    access_token = tokenhandler.get_token_from_file(token_file_name, api_key)["access_token"]

    # Get all todo lists for the user
    url = "https://cottertodolist.herokuapp.com/list"
    headers = {'Authorization': 'Bearer ' + access_token}
    response = requests.get(url, headers=headers)
    lists = response.json()

    # Prompt to pick list
    options = map(lambda x: x["name"], lists)
    questions = [
      {
        'type': 'list',
        'name': 'list_name',
        'message': 'Add task to which list?',
        'choices': options,
      },
      {
        'type': 'input',
        'name': 'task_name',
        'message': 'Task description',
      }
    ]
    answers = prompt(questions)
    if not answers:
        return

    # Call API to create task fot the selected list
    url = "https://cottertodolist.herokuapp.com/todo/create"
    headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer ' + access_token}
    data = {
      "name": answers['list_name'],
      "task": answers['task_name']
    }
    response = requests.post(url, json=data, headers=headers)
    if response.status_code != 200:
        response.raise_for_status()

    click.echo("Task " + answers['task_name'] + " is added in list " + answers['list_name'])

First, we needed to call the API to list all todo lists for the user.
The first question has type: list which asks the user to choose which list they want to add a new task to.
The second question has type: input which asks the user to type in the new task's description.
Using the answers, we call our API to add the task to the chosen list.

Show our Todo Lists

Now that we've created a list and added some tasks, let's see the list! The API to see a list looks like this:

### Show all lists
GET http://localhost:1234/list
Authorization: Bearer <access_token>

Let's add a function called ls to list the todo lists for this user in cli.py. We'll apply this rule:

python cli.py ls will ask you which list you want to see, then show that list.
python cli.py ls -a will immediately show all your lists.

# cli.py

@main.command()
@click.option('-a', '--all', is_flag=True) # Make a boolean flag
def ls(all):
    """Show lists"""
    # Get access token from file
    access_token = tokenhandler.get_token_from_file(token_file_name, api_key)["access_token"]

    # Get all lists
    url = "https://cottertodolist.herokuapp.com/list"
    headers = {'Authorization': 'Bearer ' + access_token}
    response = requests.get(url, headers=headers)
    if response.status_code != 200:
        response.raise_for_status()
    listsFormatted = response.json()

    if all == True:
        # Show all tasks in all lists
        for chosenList in listsFormatted:
            click.echo('\n' + chosenList['name'])
            for task in chosenList['tasks']:
                if task['done'] == True:
                    click.echo("[✔] " + task['task'])
                else:
                    click.echo("[ ] " + task['task'])
    else:
        # Show a prompt to choose a list
        questions = [
            {
                'type': 'list',
                'name': 'list',
                'message': 'Which list do you want to see?',
                'choices': list(map(lambda lst: lst['name'], listsFormatted))
            },
        ]
        answers = prompt(questions)
        if not answers:
            return

        # Get the chosen list
        chosenList = list(filter(lambda lst: lst['name'] == answers['list'], listsFormatted))
        if len(chosenList) <= 0:
            click.echo("Invalid choice of list")
            return
        chosenList = chosenList[0]

        # Show tasks in the chosen list
        click.echo(chosenList['name'])
        for task in chosenList['tasks']:
            if task['done'] == True:
                click.echo("[✔] " + task['task'])
            else:
                click.echo("[ ] " + task['task'])

First, we get all the todo lists for this user
If the flag -a is specified, then we iterate over each list and print the list name and tasks along with the checkmark
If the flag -a is not specified, then we prompt the user to select a list, then we iterate over the tasks for that selected list and print the tasks with the checkmark.

Now try it out! It should look like this:

❯ python cli.py ls -a

Web Repo
[ ] Update favicon.ico
[ ] Add our logo to the footer
[ ] Add a GIF that shows how our product works

Morning Routine
[ ] Drink coffee
[ ] Grab yogurt
[ ] Drink fish-oil

Obviously, none of our tasks are done since we haven't made the function to mark a task as done. Let' do that next.

Check and Un-check a Task

We'll use PyInquirer's powerful checklist type to allow the user to check and un-check the tasks. Our API to update a task looks like this:

### Update task set done = true or false by id
PUT http://localhost:1234/todo/update/done/274822869038400008
Authorization: Bearer <access_token>
Content-Type: application/json

{
    "done": true
}

Let's add a function called toggle to our cli.py.

# cli.py
@main.command()
def toggle():
    """Update tasks in a list"""
    # Get access token from file
    access_token = tokenhandler.get_token_from_file(token_file_name, api_key)["access_token"]

    # Call API to list all tasks
    url = "https://cottertodolist.herokuapp.com/list"
    headers = {'Authorization': 'Bearer ' + access_token}
    response = requests.get(url, headers=headers)
    if response.status_code != 200:
        response.raise_for_status()
    listsFormatted = response.json()

    # Show a prompt to choose a list
    questions = [
        {
            'type': 'list',
            'name': 'list',
            'message': 'Which list do you want to update?',
            'choices': list(map(lambda lst: lst['name'], listsFormatted))
        },
    ]
    answers = prompt(questions)
    if not answers:
        return

    # Get the chosen list
    chosenList = list(filter(lambda lst: lst['name'] == answers['list'], listsFormatted))
    if len(chosenList) <= 0:
        click.echo("Invalid choice of list")
        return
    chosenList = chosenList[0]

    # Show an interactive checklist for the tasks
    questions = [
        {
            'type': 'checkbox',
            'message': chosenList['name'],
            'name': chosenList['name'],
            'choices': list(map(lambda task: {'name': task['task'], 'checked': task["done"]}, chosenList['tasks'])),
        }
    ]
    answers = prompt(questions)
    if not answers:
        return

    # Call our Update API for each task in the list
    # set `done` as True or False based on answers
    for task in chosenList['tasks']:
        url = "https://cottertodolist.herokuapp.com/todo/update/done/" + task['id']
        headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer ' + access_token}
        data = {
            "done": task['task'] in answers[chosenList['name']]
        }
        response = requests.put(url, json=data, headers=headers)
        if response.status_code != 200:
            response.raise_for_status()

    click.echo(answers)

First, we call the list API to get all the lists for the user and prompt them to select a list.
Then using PyInquirer with type: checklist we can show them a checklist for the tasks in the list, and set {'checked': True} for tasks that are already done.
The user can use <space> to select or deselect a task, and press enter to update the task.

It looks like this:

Let's see our complete todo list again:

❯ python cli.py ls -a

Web Repo
[ ] Update favicon.ico
[ ] Add our logo to the footer
[ ] Add a GIF that shows how our product works

Morning Routine
[✔] Drink coffee
[✔] Grab yogurt
[ ] Drink fish-oil

Awesome! Our Todo-List CLI is done!

The final result should look like this:

This post is written by the team at Cotter – we are building lightweight, fast, and passwordless login solutions for websites, mobile apps, and now CLIs too! If you're building a website, app, or CLI, we have all the tools you need to get a login flow set up in minutes.

What's Next?

It's pretty lame if your user has to always call python cli.py create, we want to change it to todo create instead. Follow this article to find out how to do that.

If you want to make your own REST API in Flask, check out the source code of the Todo List API that we just used to see how to protect your API routes with an access_token. Want to make a front-end for our Todo list so it's accessible from both the terminal and the web? Check out our tutorials on implementing the same Cotter Login to your React front end. This ensures that your users can log in and see the same list throughout both platforms.

Questions & Feedback

Come and talk to the founders of Cotter and other developers who are using Cotter on Cotter's Slack Channel.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

If you need help, ping us on our Slack channel or email us at team@cotter.app.

Angular: Send Email, SMS, and WhatsApp Verification Code to New Users Worldwide

Putri Karunia — Thu, 06 Aug 2020 17:00:00 +0000

In this tutorial, we'll add a simple email and phone number verification to an Angular app with an option to send the verification code via SMS or WhatsApp.

Get Started

We'll be using this CodeSandbox so you can try it out without any setup. Open it in a new tab to make it easier to edit the code.

If you want to make a new Angular app locally, first install the cli

npm install -g @angular/cli

then create a new Angular app:

ng new my-app
cd my-app
ng serve --open

Verifying user's Email

Let's start by verifying the user's email before we jump to sending SMS or WhatsApp messages.

Installing Dependencies

Cotter is already added to the CodeSandbox above. To add Cotter to your local project, you can use yarn or npm.

yarn add cotter

Step 1: Setup a div to contain Cotter's verification form in `src/app/app.component.html`

Add a div with id="cotter-form-container" below our title:

<!-- 1️⃣ Setup a div to contain the form -->
<div
  id="cotter-form-container"
  style="width: 300px; height: 300px;"
></div>

Step 2: Import Cotter in `src/app/app.component.ts` and show the form

import { Component, OnInit } from '@angular/core';
import Cotter from 'cotter'; // 2️⃣ Import Cotter

export class AppComponent implements OnInit {
  title = 'My Cotter App';

  // 2️⃣ Initialize and show the form on init
  success = false;
  payload = null;
  payloadString = null;

  constructor() {}

  ngOnInit() {
     // ⭐ Show Email Form
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    cotter
      .signInWithLink()
      .showEmailForm()
      .then((payload: object) => {
        this.success = true;
        this.payload = payload;
        this.payloadString = JSON.stringify(payload, null, 4);
      })
      .catch((err: any) => console.log(err));
  }
}

You need to add your API_KEY_ID here. Create a free account at Cotter, then create a Project and take notes of the API Keys.

Give it a try

Enter your email address and sign in.
Check the response for an access token.

Check out the complete project here.

Not Prompted to Click a Link?

That's the magic! Cotter's email verification works across apps. If the user's email/phone number is already verified, apps that are integrated with Cotter don't need to re-verify the user's email and phone number again as long as it's accessed from the same browser.

Verify the Phone Number via SMS or WhatsApp

It's very easy to update the code above to ask for the user's phone number instead. Update the config above:

Change to showPhoneForm().
Customize the form in the Dashboard > Branding to show buttons for SMS and WhatsApp.

// ⭐ Show Phone Form
var cotter = new Cotter(API_KEY_ID);
cotter
  .signInWithLink()
  .showPhoneForm() // 👈 Update type to PHONE
  .then((payload: object) => {
    this.success = true;
    this.payload = payload;
    this.payloadString = JSON.stringify(payload, null, 4);
  })
  .catch((err: any) => console.log(err));

To send an SMS or a WhatsApp message, you need to add some balance to your account. Go to Billing and add a payment method to start sending phone verification codes.

A Note on Validating User Response

We showed you how to validate Cotter's user response in the frontend part of your project. It's recommended to validate the response in your backend, right before you register the user to your database.

What's Next?

Now that you can verify your users' emails and phone numbers, you can start registering and logging in users.

Follow this guide on how to Setup Passwordless Login.

Questions & Feedback

If you have any questions or feedback, feel free to join Cotter's Slack Channel and chat us there.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

OAuth 2.0 - Before You Start: Pick the Right Flow for Your Website, SPA, Mobile App, TV App, and CLI

Michelle Marcelline — Tue, 04 Aug 2020 10:55:23 +0000

OAuth 2.0 has at least 4 different flows for different use cases. Find out which flow you should use to secure your app.

We learned how OAuth 2.0 works in general in What on Earth is OAuth? and learned how to securely store access tokens in the front end. In this post, we'll learn which OAuth 2.0 flow you should use based on what you're building.

OAuth 2.0 Recap:

In general, the OAuth 2.0 flow looks like this diagram below (if you're not familiar with the OAuth 2.0 Flow below, check our explanation here).

OAuth 2.0 Flow with Google Sign In

Step 1: The website requests authorization for Albert. Albert is being redirected to Google's site to log in.
Step 2: Google's site returned with an Authorization Grant. This is the part that has several different cases based on which flow you're using.
Step 3-4: Depending on the flow, the client will have a way to exchange this Authorization Grant with an access token, and sometimes a refresh token
Step 5-6: The website uses the access token to access resources.

Common OAuth 2.0 Flows

As mentioned above, there are 4 common OAuth 2.0 Flows:

Authorization Code Flow
Authorization Code Flow with Proof Key for Code Exchange (PKCE)
Client Credentials Flow
Device Code Flow

Which Flow Should I Use?

Different apps should use different flows based on whether or not the app can hold secrets securely.

Web Server Apps and Command Line Scripts: Use Authorization Code Flow
Single Page Apps and Mobile Apps: Use Authorization Code Flow with PKCE
Server-to-Server API Calls : Use Client Credentials Flow
TV Apps and other apps on input-constrained devices: Use Device Code Flow

Web Server Apps and Command Line Scripts

→ Use Authorization Code Flow

Web Server Apps are apps that are running on a server where the source code is not publicly exposed.

Requirements: Your app needs to be able to hold a Client Secret securely in the back end server.

For example:

✅ Your app runs on a server (Node.js, PHP, Java, .NET): Your server code is not publicly exposed and you can put secret keys in environment variables without it being visible to users of the application.
❌ React-only website: React is a SPA framework, your code is publicly exposed, and therefore cannot hold secrets securely, even if you put secrets in .env files.

Authorization Code Flow

OAuth 2.0 Authorization Code Flow

Step 1-4: User clicks Sign in with Google, and get redirected to Google's Site to authenticate.
Step 5: When the user successfully authenticated, Google will redirect the user back to your website, and include an authorization_code in the redirect URL. For example:

https://mysite.com/redirect
    ?code=ABCDEFGHIJ12345
    &state=abcde123abc

Step 6-9: With the code above and a Client ID + Client Secret that you get from Google when registering an application, you can request for an access_token for the user that you can then use to fetch data.

See the full spec at RFC 6749 Section 4.1

How do I do this from the command line?

On step 3 , show the URL that the user should go to in their browser.
Get your script to listen to a local port, for example, http://127.0.0.1:8000 and set the redirect URL to be http://127.0.0.1:8000/redirect
On step 5 , the user's browser will redirect to

https://127.0.0.1:8000/redirect
    ?code=ABCDEFGHIJ12345
    &state=abcde123abc

Your script should then handle this GET request, parse the code and state and proceed to step 6-9.

Single Page Apps & Mobile Apps

→ Use Authorization Code Flow with PKCE

Single Page Apps (SPA) and Mobile Apps are not able to hold secrets securely because their source code is publicly exposed or can be decompiled.

How does the PKCE flow work without a Client Secret?

The PKCE flow requires the app to generate a secret on the fly. This secret is generated at the beginning of the flow when the user started the login flow and then checked when exchanging authorization code with an access token.

This makes sure that the entity that is requesting to exchange the authorization code with an access token is still the same entity where the user requested to authenticate.

Authorization Code Flow with PKCE

OAuth 2.0 Authorization Code Flow with PKCE

Step 1: User clicks the login button in your app
Step 2: Generate a code_verifier and code_challenge, then make an authorization request by sending the code_challenge.

code_verifier = "a cryptographic random string"
code_challenge = base64url_encode(sha256(ascii(code_verifier)))

Step 3-5: The Authorization Server will save the code_challenge for later and redirect the user to log in, then redirect to your app with an authorization_code
Step 6 : Your app then sends the code_verifier , client_id , and authorization_code to get an access token.
Step 7: The Authorization Server will check if the original code_challenge == base64url_encode(sha256(ascii(code_verifier))). This is where it determines whether the entity that started this flow is the same one as the one that is currently requesting an access token. If yes, it returns the access token.
Step 8-9 : Your app can now fetch data using the access token.

See the full spec at RFC 7636.

Here are some resources to help you generate a code challenge and verifier:

Server-to-Server API calls

→ Use Client Credentials Flow

For example, your back end server wants to call an API endpoint at Stripe to retrieve a list of payments. This is a machine-to-machine authorization, and there's no end-user authorization. In this case, Stripe is only trying to authorize your server to access the API endpoint. Since your server can also hold secrets securely, all you need for accessing the data is a Client ID and Client Secret.

Client Credentials Flow

OAuth 2.0 Client Credentials Flow

Step 1: Your server authenticates itself using its Client ID and Client Secret. Notice that this doesn't involve any user. This is because your server is acting as itself. (For example, your server is acting as Hello Merchant that you registered to Stripe).
Step 2: If the Client ID and Client Secret checks out, you'll receive an access token.
Step 3: Use the access token to fetch data.

See the full spec at RFC 6749 Section 4.4

TV Apps and other apps on input-constrained devices

→ Use Device Code Flow

It'll be horrible if you have to input your super-secure Google password to watch YouTube on your brand new smart TV, right? OAuth 2.0 Device Code Flow is designed so that you can authorize apps on an input constraint device by opening a URL and entering a code on your browser (on your phone/laptop).

Requirements: Your app needs to be able to display a URL and a User Code to the user. This can also be done by showing a QR Code.

Device Code Flow

Step 1: User requests to log in on your TV App.
Step 2-3: Your TV App makes an authorization request to the Authorization Server (Google Accounts in this case) with your app's Client ID, and receive 3 things: a device_code, a user_code , and a verification_uri.
Step 4 : Your TV App now asks the user to go to the verification_uri and enter the user_code . You can optionally do this by asking the user to scan a QR Code that encodes both the verification_uri and the user_code .
Step 5: Your TV App now requests an access token to the Authorization Server using the device_code and client_id . If the user hasn't authenticated and allowed access to your app yet (they haven't gone to the verification_uri), the Authorization Server will respond with an error authorization_pending. Your TV App should keep on requesting until you get an access token.
Step 6: The user typed in the verification_uri on their phone or laptop, and entered the user_code.
Step 7-8: The user is now redirected to Google's Login page where they can authenticate and allow your TV App to access certain data.
Step 9 : Google accounts now mark that your user has authenticated and allowed your app to access their data. The next time your app requested for an access token with the device_code, Google Accounts will return an access token.
Step 10-11 : Use the access token to fetch data.

See the full spec at RFC 8628 Section 3.4

That's It!

This should help you pick which OAuth 2.0 flow you need for different use cases. We didn't go into the specific HTTP Request parameters that you should use, we will cover that next time.

This post is written by the team at Cotter – we are building lightweight, fast, and passwordless login solution for websites and mobile apps. If you're building a website, we have a ready-made solution that implements the flows above for you.

Sign in with Magic Link via Email, SMS, or WhatsApp on:

References

We referred to these articles and specs to write this post:

Questions & Feedback

If you need help or have any feedback, ping us on Cotter's Slack Channel! We're here to help.

Ready to use Cotter?

If you enjoyed this post and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

What is WebAuthn: Logging in with Face ID and Touch ID on the web

Michelle Marcelline — Tue, 28 Jul 2020 07:13:42 +0000

Enable TouchID and Windows Hello authentication to your website. Introducing WebAuthn: how it works and how to implement it.

What is WebAuthn?

The Web Authentication API is an authentication specification that allows Websites to authenticate users with built-in authenticators like Apple's TouchID and Windows Hello, or using security keys like Yubikey.

WebAuthn Login with Cotter

It utilizes public-key cryptography instead of passwords. When the user registers, a private-public key pair is generated for the account, and the private key is stored securely in the user's device, while the public key is sent to the server. The server can then ask the user's device to sign a challenge using the private key to authenticate the user.

Registration with WebAuthn

Usually, a website will ask the user to enter a username and password. With WebAuthn, the website will generate this public-private key pair and send the public key to the server and store the private key securely in the user's device.

WebAuthn Registration Flow

Logging-in with WebAuthn

This is where websites usually check whether the user has provided the right username and password. With WebAuthn, the website will send a challenge and check if the browser can sign the challenge using the private key that's stored in the user's device.

WebAuthn Login Flow

Implementation

We've built a simple way to implement WebAuthn using Cotter that you can do in just a few minutes.

Try WebAuthn in Action.

We've made a simple site for you to try it out: https://cotter.herokuapp.com/

Make sure you're using Google Chrome on a laptop that supports TouchID/Windows Hello.
Registration: If this is your first time logging in, you'll be prompted to enable TouchID or Windows Hello after your email is verified.
Login: Go to an incognito tab and open this URL again. You need to allow third-party cookies (eye icon on URL bar). Try logging in with the same email, and you'll be prompted to log in using WebAuthn.

Short Guide for Implementing WebAuthn with React

yarn add cotter

Implement Login with WebAuthn

Import Cotter
Call signInWithWebAuthnOrLink to use WebAuthn with Magic Link as the fallback method, followed by showEmailForm or showPhoneForm, and get the response as a promise.
Setup a <div> with id="cotter-form-container" that will contain the form.

import React, { useEffect, useState } from "react";
import Cotter from "cotter"; // 1️⃣ Import Cotter

function App() {
  const [payload, setpayload] = useState(null);

  // 2️⃣ Initialize and show the form
  useEffect(() => {
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    cotter
      .signInWithWebAuthnOrLink() // 👈 sign in using WebAuthn
      .showEmailForm()
      .then(response => {
        setpayload(response); // show the response in our state
      })
      .catch(err => console.log(err));
  }, []);

  return (
    <div>
      {/* 3️⃣ Put a <div> that will contain the form */}
      <div id="cotter-form-container" style={{ width: 300, height: 300 }} />

      <pre>{JSON.stringify(payload, null, 4)}</pre>
    </div>
  );
}

export default App;

App.js

You'll need an API_KEY_ID , create a project, and copy the API KEY from the dashboard.

What does `signInWithWebAuthnOrLink` do?

If the email is not recognized as a user , then Cotter will ask the user to verify their email by sending a MagicLink. After the user verified their email, Cotter's SDK will ask the user to enable WebAuthn login by registering the current device.
If the email is a user that has WebAuthn set up , then Cotter will try to authenticate the user with WebAuthn. Alternatively, the user can choose to send a magic link to their email to login.

Implementation with vanilla JS

To learn more about WebAuthn, here's a more in-depth explanation about how to implement WebAuthn with purely JavaScript. Check out Apple's guide from WWDC20.

Registration

Step 1: Your site requests the server for registering WebAuthn.

Ask the user to enter some identifier (username, email, etc), then send the request to your server asking to register a new WebAuthn credential.

Step 2: The server specifies some options for creating the new keypair.

The server specify a PublicKeyCredentialCreationOptions object that contains some required and optional fields for creating the new PublicKeyCredential (our keypair).

const optionsFromServer = {
    "challenge": "random_string", // need to convert to ArrayBuffer
    "rp": { // my website info
      "name": "My Website",
      "id": "mywebsite.com"
    },
    "user": { // user info
      "name": "anthony@email.com",                  
      "displayName": "Anthony",
      "id": "USER_ID_12345678910" // need to convert to ArrayBuffer
    },
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -7 // Accepted Algorithm
      }
    ],
    "authenticatorSelection": {
        authenticatorAttachment: "platform",
    },
    "timeout": 60000 // in milliseconds
};

rp : This is for specifying information about the relying party. The relying party is the website where the user is registering/logging-in into. If the user is registering to your website , then your website is the relying party.

id: The host's domain name, without the scheme or port. For example, if the RP's origin is https://login.example.com:1337, then the id is login.example.com or example.com, but not m.login.example.com.

pubKeyCredParams : What public key types are acceptable to the server.

alg : A number that describes what algorithm the server accepts, and is described in the COSE registry under COSE Algorithms. For example, -7 is for ES256 algorithm.

authenticatorSelection : (Optional) Restrict authenticator to be either platform or cross-platform. Use platform to allow authenticators like Windows Hello or TouchID. Use cross-platform to allow authenticators like Yubikey.

Step 3: In the front-end, use the options to create a new keypair.

Using our creationOptions , we can now tell the browser to generate a new keypair.

// make sure you've converted the strings to ArrayBuffer
// as mentioned above
const credential = await navigator.credentials.create({
    publicKey: optionsFromServer 
});

The credential that is returned will look like below:

PublicKeyCredential {
    id: 'ABCDESKa23taowh09w0eJG...',
    rawId: ArrayBuffer(59),
    response: AuthenticatorAttestationResponse {
        clientDataJSON: ArrayBuffer(121),
        attestationObject: ArrayBuffer(306),
    },
    type: 'public-key'
}

Step 4: Send the `credential` to your server

First, you might need to convert the ArrayBuffers to either base64 encoded strings or just to string. You'll need to decode this in your server.

Follow the specifications to validate the credential in your server. You should then store the Credential information to allow the user to login with this WebAuthn Credential.

Login

Step 1: Send a request to your server to login

This allows the server to send a challenge that your front-end needs to sign.

Step 2: The server sends a challenge and a list of WebAuthn credentials that the user can log in from.

The server specify a PublicKeyCredentialRequestOptions object that contains the challenge to sign and a list of WebAuthn credentials that the user has registered previously.

const optionsFromServer = {
    "challenge": "somerandomstring", // Need to convert to ArrayBuffer
    "timeout": 60000,
    "rpId": "mywebsite.com",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "AdPc7AjUmsefw37..." // Need to convert to ArrayBuffer
      }
    ]
}

Step 3: The front-end signs the challenge

// make sure you've converted the strings to ArrayBuffer
// as mentioned above
const assertion = await navigator.credentials.get({
    publicKey: optionsFromServer
});

The assertion that is returned looks like this:

PublicKeyCredential {
    id: 'ABCDESKa23taowh09w0eJG...',    // The WebAuthn Credential ID
    rawId: ArrayBuffer(59),
    response: AuthenticatorAssertionResponse {
        authenticatorData: ArrayBuffer(191),
        clientDataJSON: ArrayBuffer(118),
        signature: ArrayBuffer(70), // The signature that we need to verify
        userHandle: ArrayBuffer(10),
    },
    type: 'public-key'
}

Step 4: Send the `assertion` to your server and verify it

You might need to convert the ArrayBuffers to a string before sending it to the server. Follow the specifications on verifying the assertion.

When the assertion is verified, this means that the user has successfully logged in. This would be the place to generate your session tokens or set your cookies and return to the front-end.

A few things to think about:

If the user logs in with their laptop's TouchID, how do you allow them to log in from someone else's laptop?

It might be a bad user experience if they can only log in from their own laptop. A possible way is to use WebAuthn as an alternative , and always have a fallback login method (for example, using magic links or OTP).

Adding more than one WebAuthn credential for one account.

You might want to have a "Settings" page that allows your user to allow WebAuthn login from other devices. For example, they want to login with WebAuthn both from their laptop and their iPad.

The browser doesn't know which credentials you have saved in your server for a user. If your user already registered their laptop's WebAuthn credential, you need to tell the browser so that it doesn't create a new credential. Use the excludeCredentials in the PublicKeyCredentialCreationOptions.

Support for WebAuthn

Not all browsers support WebAuthn yet, but it's growing. Check out FIDO's website for a list of Browsers and Platforms that supports WebAuthn.

That's It!

This should cover the basics about registering and logging-in with WebAuthn, and help you implement it on your site. This post is written by the team at Cotter – we are building lightweight, fast, and passwordless login solution for websites and mobile apps.

If you want to implement WebAuthn, our documentation might help:

References

We referred to these incredibly helpful articles to write this post:

Questions & Feedback

If you need help or have any feedback, ping us on Cotter's Slack Channel! We're here to help.

Ready to use Cotter?

If you enjoyed this post and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

Passwordless Login with Email and JSON Web Token (JWT) Authentication using Next.js

Putri Karunia — Thu, 23 Jul 2020 03:00:00 +0000

How do you log your users in and how do you give them access? We'll go over how to authenticate and authorize users without passwords in Next.js.

When you start adding users to your website, the main question that you need to answer is: how do you log your users in and how do you give them access to the appropriate resources?

In this tutorial we'll go over how to address both questions and build a Next.js app that only allows logged-in users to access private resources within the app.

So you want to have users.

Let's go over some concepts: authentication vs authorization.

Authentication: How do I log my users in?

Authentication is a way for your server to verify the user's identity. The most common way to authenticate users is by using the email/password combo. Unfortunately, passwords have serious disadvantages on both security and user interface. In this tutorial, we'll use a verification code sent to the user's email to authenticate the user.

Authorization: How do I keep my users logged in?

Authorization is a way for your server to authorize a request. In simpler terms, this is where you pass in a token or session to your backend server when calling an API to view or update some data. The 2 common strategies are cookie-based sessions and JWT tokens.

The main advantage for JWT tokens is that it's not stored in your database so you don't need to do a DB check to validate every request. That's why we're going to use JWT Tokens in this tutorial.

Learn more about how OAuth 2.0 and Access Token works.

How would the overall registration/login look like?

Authentication: We'll ask for the user's email and send them an email containing a code. If the user enters the code correctly, we'll get a JWT Token in the frontend and store it in localStorage.

Authorization: Every time we want to access a private API endpoint we need to include a header Authorization: Bearer ${token}.

Storing the token in the browser local storage is susceptible to cross-site scripting (XSS) attack. If an attacker can successfully run JavaScript code in your site, they can retrieve the tokens stored in local storage. XSS vulnerability arises when your website takes data from users without proper validation or from a third-party JavaScript code (like Google Analytics, jQuery, etc) included in the website.

Let's Start Building

Create your Next.js app. We'll call the app next-passwordless-login and use the default starter app.

yarn create next-app
cd next-passwordless-login && yarn dev

Update our website

Update your pages/index.js . Delete everything except the styling and the container div, then add this inside the container div.

<main>
    <h1 className="title">Passwordless App.</h1>

    {/* 1️⃣ TODO: Setup a div to contain the form */}

    <div className="grid">
        <div className="card">
            <h3>Public Endpoint</h3>
            <p>You should be able to access this when not logged in</p>
        </div>

        <div className="card">
            <h3>Private Endpoint</h3>
            <p>You need to log in to access this endpoint</p>
        </div>
    </div>
</main>

pages/index.js

Step 1: Show the Register/Login form

Install the dependencies:

yarn add cotter cotter-node

Add a div to contain the form below our title in pages/index.js

<h1 className="title">Passwordless App.</h1>

{/* 1️⃣ TODO: Setup a div to contain the form */}
<div id="cotter-form-container" style={{ width: 300, height: 300 }} />

pages/index.js

Then import and initialize Cotter to embed the email form.

// 1️⃣ import Cotter verification form and useEffect from react
import Cotter from "cotter";
import { useEffect } from "react";

top of pages/index.js

export default function Home() {
  // 1️⃣ Initialize and show the form
  // Add the lines here
  useEffect(() => {
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    cotter
      .signInWithOTP()
      .showEmailForm()
      .then(payload => {
        console.log(payload);
        alert("Success");
      })
      .catch(err => console.log(err));

  }, []);
  // until here

  return (...);
}

pages/index.js

You need to add your API_KEY_ID here. Create a free account at Cotter, then create a Project and take notes of the API Keys.

Now you should be able to see the login form like below.

The form will automatically send an email as necessary and show an input to enter the code. It won't send another email if you've already verified your email in this browser.

Step 2: Keep users logged in with `access_token`

Read the `console.log`

Try entering your email and logging-in. You should see that the payload we receive in the OnSuccess function contains the following object:

{
  "token": {...},
  "email": "team@cotter.app",
  "oauth_token": {
    "access_token": "eyJhbGciOiJFUzI1NiIsIn...",
    "id_token": "eyJhbGciOiJFUzI1NiIsInR5cC...",
    "refresh_token": "199:doZor3GtgsrYo4R7L...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "auth_method": "OTP"
  },
  "user": {
    "ID": "ecadbd2c-56f8-4078-b45d-f17786ed499e", // Cotter User ID
    ...
  }
}

We want to use the access_token in this tutorial, so let's grab that and store it in localStorage.

    useEffect(() => {
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    cotter
      .signInWithOTP()
      .showEmailForm()
      .then(payload => {
        console.log(payload);
-        alert("Success");

+        // 2️⃣(a) Store the access token and set logged in
+        localStorage.setItem("ACCESS_TOKEN", payload.oauth_token.access_token);
+        setIsLoggedIn(true);
      })
      .catch(err => console.log(err));
  }, []);

pages/index.js

Now let's define setIsLoggedIn(), this will help us show whether the user is logged in or not.

     import Cotter from "cotter";
     import { useEffect } from "react";
+    import { useState } from "react";

    export default function Home() {
+      // 2️⃣(a) Show if the user is logged in.
+      var [isLoggedIn, setIsLoggedIn] = useState(false);

pages/index.js

We also want to check if the localStorage contains ACCESS_TOKEN every time the page loads and update our isLoggedIn variable. Add this below the first useEffect() .

// 1️⃣ Initialize and show the form
useEffect(() => {...}, []);

// Add the lines below here
// 2️⃣(b) Check if the ACCESS_TOKEN exists every time the page loads
useEffect(() => {
    if (localStorage.getItem("ACCESS_TOKEN") != null) {
        setIsLoggedIn(true);
    }
}, []);

pages/index.js – below the first useEffect

Now let's show if the user is logged in below our form:

{/* 2️⃣(c) Show if the user is logged in. */}
<p>
    {isLoggedIn ? "✅ You are logged in" : "❌ You are not logged in"}
</p>

pages/index.js

Step 3: Logging-out

Logging-out is achieved by removing the access_token from our localStorage. Let's add the logout function inside Home before return() in pages/index.js

// 3️⃣ Log out users
const logOut = () => {
    localStorage.removeItem("ACCESS_TOKEN");
    setIsLoggedIn(false);
};

pages/index.js inside Home before return

And show the logout button:

{/* 3️⃣ Show the logout button */}
{isLoggedIn ? (
    <div
        className="card"
        style={{ padding: 10, margin: 5 }}
        onClick={logOut}
    >
        Log Out
    </div>
) : null}

pages/index.js

You can now see the if you're logged in and the logout button:

Step 4: Allowing the user from accessing public/private endpoints.

Let's add 2 routes in our pages/api

touch pages/api/public.js pages/api/private.js

Defining the routes

Let's define our /api/public endpoint in pages/api/public.js. We're just going to return that the request is successful.

export default (req, res) => {
  res.statusCode = 200;
  res.end(
    "Success! This is a public resource, you can see it without logging in."
  );
};

pages/api/public.js

Let's define our /api/private endpoint in pages/api/private.js. First we'll check if the authorization header exists.

// 2) TODO: Import Cotter

const checkJWT = (handler) => async (req, res) => {
  // 1) Check that the access_token exists
  if (!("authorization" in req.headers)) {
    res.statusCode = 401;
    res.end("Authorization header missing");
  }
  const auth = await req.headers.authorization;
  const bearer = auth.split(" ");
  const token = bearer[1];
  console.log(token);

  // 2) TODO: Validate the access_token

  handler(req, res);
}

const handler = (req, res) => {
  res.statusCode = 200;
  res.end(
    `Success! This is a private resource and you have the access_token to view it.`
  );
};

export default checkJWT(handler);

pages/api/private.js

Now let's validate the access token.

First, import Cotter's jwt validator function at the top of pages/api/private.js

import { CotterValidateJWT } from "cotter-node";

pages/api/private.js

Then call CotterValidateJWT(token) under step (2) inside checkJWT.

  // 2) TODO: Validate the access_token
  var valid = false;
  try {
    valid = await CotterValidateJWT(token);
  } catch (e) {
    console.log(e);
    valid = false;
  }
  if (!valid) {
    res.statusCode = 403;
    res.end("Authorization header is invalid");
  }

pages/api/private.js inside checkJWT

Calling the `/public` and `/private` API endpoints

Let's go back to pages/index.js and add 2 functions: getPublicResource and getPrivateResource that will call the endpoint /api/public and /api/private.

export default function Home() {
  ...

  // 4️⃣ Get Public and Private Resources
  // Add the lines here
  var [publicResource, setPublicResource] = useState(null);
  var [privateResource, setPrivateResource] = useState(null);

  // Get Public Resource
  const getPublicResource = async () => {
    var resp = await fetch("/api/public");
    setPublicResource(await resp.text());
  };

  // Get Private Resource
  const getPrivateResource = async () => {
    var token = localStorage.getItem("ACCESS_TOKEN");
    if (token == null) {
      setPrivateResource("Token doesn't exist, you're logged-out");
      return;
    }
    var resp = await fetch("/api/private", {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
    setPrivateResource(await resp.text());
  };
  // Until here

  return(...);
}

pages/index.js

Now let's call the 2 functions from our buttons and show the response from the endpoints. Update the div with className="grid" to the following code:

{/* 4️⃣ Call Get Public and Private Resources */}
<div className="grid">
    <div className="card" onClick={getPublicResource}>
        <h3>Public Endpoint</h3>
        <p>{publicResource}</p>
    </div>

    <div className="card" onClick={getPrivateResource}>
        <h3>Private Endpoint</h3>
        <p>{privateResource}</p>
    </div>
</div>

pages/index.js update the grid class

We display the response from the endpoints in the publicResource and privateResource variables.

That's it

Now you can authenticate users by sending a code to their emails and allow them to access private endpoints that require an access_token to access.

If you're curious, print out the access_token and copy it to https://jwt.io/ to see what information is decoded. The id_token contains more information about the user and the refresh_token is used to get a new access_token if it's expired.

What's Next?

Learn more about the OAuth tokens returned from Cotter and use them in your API endpoints.

If you want to authenticate users using their phone number, follow this guide on Verifying User's Phone Number via SMS and WhatsApp.

Questions & Feedback

If you have any questions or feedback, feel free to join Cotter's Slack Channel and chat us there.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

LocalStorage vs Cookies: All You Need To Know About Storing JWT Tokens Securely in The Front-End

Michelle Marcelline — Tue, 21 Jul 2020 18:20:34 +0000

JWT Tokens are awesome, but how do you store them securely in your front-end? We'll go over the pros and cons of localStorage and Cookies.

We went over how OAuth 2.0 works in the last post and we covered how to generate access tokens and refresh tokens. The next question is: how do you store them securely in your front-end?

A Recap about Access Token & Refresh Token

Access tokens are usually short-lived JWT Tokens, signed by your server, and are included in every HTTP request to your server to authorize the request.

Refresh tokens are usually long-lived opaque strings stored in your database and are used to get a new access token when it expires.

Where should I store my tokens in the front-end?

There are 2 common ways to store your tokens: in localStorage or cookies. There are a lot of debate on which one is better and most people lean toward cookies for being more secure.

Let's go over the comparison between localStorage. This article is mainly based on Please Stop Using Local Storage and the comments to this post.

Local Storage

Pros: It's convenient.

It's pure JavaScript and it's convenient. If you don't have a back-end and you're relying on a third-party API, you can't always ask them to set a specific cookie for your site.
Works with APIs that require you to put your access token in the header like this: Authorization Bearer ${access_token}.

Cons: It's vulnerable to XSS attacks.

An XSS attack happens when an attacker can run JavaScript on your website. This means that the attacker can just take the access token that you stored in your localStorage.

An XSS attack can happen from a third-party JavaScript code included in your website, like React, Vue, jQuery, Google Analytics, etc. It's almost impossible not to include any third-party libraries in your site.

Cookies

Pros: The cookie is not accessible via JavaScript; hence, it is not as vulnerable to XSS attacks as localStorage.

If you're using httpOnly and secure cookies, that means your cookies cannot be accessed using JavaScript. This means, even if an attacker can run JS on your site, they can't read your access token from the cookie.
It's automatically sent in every HTTP request to your server.

Cons: Depending on the use case, you might not be able to store your tokens in the cookies.

Cookies have a size limit of 4KB. Therefore, if you're using a big JWT Token, storing in the cookie is not an option.
There are scenarios where you can't share cookies with your API server or the API requires you to put the access token in the Authorization header. In this case, you won't be able to use cookies to store your tokens.

About XSS Attack

Local storage is vulnerable because it's easily accessible using JavaScript and an attacker can retrieve your access token and use it later. However, while httpOnly cookies are not accessible using JavaScript, this doesn't mean that by using cookies, you are safe from XSS attacks involving your access token.

If an attacker can run JavaScript in your application, then they can just send an HTTP request to your server and that will automatically include your cookies. It's just less convenient for the attacker because they can't read the content of the token although they rarely have to. It might also be more advantageous for the attacker to attack using victim's browser (by just sending that HTTP Request) rather than using the attacker's machine.

Cookies and CSRF Attack

CSRF Attack is an attack that forces a user to do an unintended request. For example, if a website is accepting an email change request via:

POST /email/change HTTP/1.1
Host: site.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 50
Cookie: session=abcdefghijklmnopqrstu

email=myemail.example.com

Then an attacker can easily make a form in a malicious website that sends a POST request to https://site.com/email/change with a hidden email field and the session cookie will automatically be included.

However, this can be mitigated easily using sameSite flag in your cookie and by including an anti-CSRF token.

Conclusion

Although cookies still have some vulnerabilities, it's preferable compared to localStorage whenever possible. Why?

Both localStorage and cookies are vulnerable to XSS attacks but it's harder for the attacker to do the attack when you're using httpOnly cookies.
Cookies are vulnerable to CSRF attacks but it can be mitigated using sameSite flag and anti-CSRF tokens.
You can still make it work even if you need to use the Authorization: Bearer header or if your JWT is larger than 4KB. This is also consistent with the recommendation from the OWASP community:

Do not store session identifiers in local storage as the data are always accessible by JavaScript. Cookies can mitigate this risk using the httpOnly flag.

OWASP: HTML5 Security Cheat Sheet

So, how do I use cookies to persists my OAuth 2.0 tokens?

As a recap, here are the different ways you can store your tokens:

Option 1: Store your access token in localStorage : prone to XSS.
Option 2: Store your access token in httpOnly cookie: prone to CSRF but can be mitigated, a bit better in terms of exposure to XSS.
Option 3: Store the refresh token in httpOnly cookie: safe from CSRF, a bit better in terms of exposure to XSS. We'll go over how Option 3 works as it is the best out of the 3 options.

Store your access token in memory and store your refresh token in the cookie

Why is this safe from CSRF?

Although a form submit to /refresh_token will work and a new access token will be returned, the attacker can't read the response if they're using an HTML form. To prevent the attacker from successfully making a fetch or AJAX request and read the response, this requires the Authorization Server's CORS policy to be set up correctly to prevent requests from unauthorized websites.

So how does this set up work?

Step 1: Return Access Token and Refresh Token when the user is authenticated.

After the user is authenticated, the Authorization Server will return an access_token and a refresh_token. The access_token will be included in the Response body and the refresh_token will be included in the cookie.

Refresh Token cookie setup:

Use the httpOnly flag to prevent JavaScript from reading it.
Use the secure=true flag so it can only be sent over HTTPS.
Use the SameSite=strict flag whenever possible to prevent CSRF. This can only be used if the Authorization Server has the same site as your front-end. If this is not the case, your Authorization Server must set CORS headers in the back-end or use other methods to ensure that the refresh token request can only be done by authorized websites.

Step 2: Store the access token in memory

Storing the token in-memory means that you put this access token in a variable in your front-end site. Yes, this means that the access token will be gone if the user switches tabs or refresh the site. That's why we have the refresh token.

Step 3: Renew access token using the refresh token

When the access token is gone or has expired, hit the /refresh_token endpoint and the refresh token that was stored in the cookie in step 1 will be included in the request. You'll get a new access token and can then use that for your API Requests.

This means your JWT Token can be larger than 4KB and you can also put it in the Authorization header.

That's It!

This should cover the basics and help you secure your site. This post is written by the team at Cotter – we are building lightweight, fast, and passwordless login solution for websites and mobile apps.

If you're building a login flow for your website or mobile app, these articles might help:

References

We referred to several articles when writing this blog, especially from these articles:

Questions & Feedback

If you need help or have any feedback, feel free to comment here or ping us on Cotter's Slack Channel! We're here to help.

Ready to use Cotter?

If you enjoyed this post and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

What on Earth Is OAuth? ASuper Simple Intro to OAuth 2.0, Access Tokens, and How to Implement It in Your Site

Michelle Marcelline — Tue, 14 Jul 2020 17:00:00 +0000

Get a quick intro on what OAuth 2.0 is and how signing in with OAuth 2.0 works – explained in simple terms using Google Sign In as an example.

We're excited to tell you that Cotter now generates access tokens and refresh tokens on authentication. Let's first go over the concepts of OAuth 2.0 and the tokens before we jump in on how to use it.

Overview

What is OAuth 2.0
OAuth 2.0 in Action
OAuth Tokens: Short-lived access tokens and long-lived refresh tokens
How to Implement OAuth 2.0 for your site

What is OAuth 2.0?

OAuth 2.0 is an authorization framework that defines how a third-party application can obtain access to a service securely without requiring security details (username, password, etc.) from the user. A common example of OAuth 2.0 is when you use "Sign in with Google" to log in to other websites.

OAuth 2.0 in Action

In general, the OAuth 2.0 flow looks like this:

OAuth 2.0 Flow with Google Sign In

Let's use "Sign in with Google" as an example.

Albert is a Google Calendar user and he's trying to use Calendly.com to help manage his calendar. We'll go over the terms in the next example.

(1) Calendly.com wants to access Albert's Google Calendar. Calendly.com redirects Albert to sign in to his Google account where he grants Calendar permission for Calendly.com. (2) Google returns an Authorization Grant and redirects Albert to Calendly.com. (3) Calendly.com gives the Authorization Grant to Google and (4) receives an Access Token. (5) Calendly.com can now use this Access Token to (6) access Albert's Google Calendar, but not his Google Drive or other resources.

Here, Calendly.com is the client, Albert is the Resource Owner, Google Account is the Authorization Server, and Google Calendar is the Resource Server.

Let's try to understand the terms in a simpler example.

Let's use an example of Alberta who stays in a hotel and wants to allow her babysitter, Candy, to access her room.

Alberta agrees that Candy shall access her room and asks Candy to get her own room key from the receptionist. Alberta gives Candy a copy of her ID and a note saying "access during daytime only".
Candy goes to the receptionist with a copy of Alberta's ID and the note. The receptionist verifies the ID and gives Candy a special room key that can only be used during daytime. Candy goes back to the room and uses her key to access the room.

Candy is the Client (just like Calendly.com) who wants to access Alberta's data. Alberta here is granting limited access to the Client. The Authorization Grant is Alberta's ID copy and her note.
The receptionist is the Authorization Server, they can generate a room key for Candy to access the room. This room key is the equivalent of an Access Token, it can be used to get resources.
The room lock is the Resource Server, it holds the resource that Candy wants: the room.

There are several different flows that OAuth 2.0 offers, this example is following the Authorization Code flow. We'll talk about the different flows in a different post :)

OAuth Tokens

As mentioned above, at the end of the flow, the client receives an Access Token. Generally, these Access Tokens are short-lived; so, what happens when it expires?

Short-lived access tokens and long-lived refresh tokens

At step 4, the Authorization Server can generate 2 tokens, an access token and a refresh token. The access token is short-lived, it should only last from several hours to a couple of weeks.

When the access token expires, the application can use the refresh token to obtain a new access token. This prevents having to ask the user to re-authenticate.

Access Token

Alright, now that we understand how things work, let's start thinking about how to generate access tokens. With a short-lived access token, we can use a JWT Token to make a self-encoded access token.

How a JWT Token Looks Like

JSON Web Tokens (JWT) is a signed JSON object. This means you can trust the data contained in the JSON object by verifying the signature. For authorizing a user, you can include the user's ID and email in the JWT.

When you give the JWT Access Token to the Resource Server (your backend API server), your server can validate the JWT Token without needing to access the database to check if it's valid.

All your server needs to do is to validate that the JWT Token is valid using a library, see the user ID of the user making the request from the token, and trust that this user ID is already authenticated.

Refresh Token

Renewing Access Token using a Refresh Token

A refresh token is a special token that is used to obtain a new Access Token. Since this is long-lived, refresh tokens are generally opaque strings stored in the database. Storing refresh tokens in the database allows you to revoke them by deleting it from the database.

Because there is no way to expire an Access Token, we should make the access token short-lived. Revoking the refresh token prevents malicious parties from refreshing an expired Access Token. This means that if your Access Token expires in 1 hour, then an attacker who obtained your Access Token can only access your API for 1 hour before it expires.

How to Implement OAuth 2.0 for your site

This sounds like a lot, but you can implement OAuth 2.0 and authorizes API requests using access tokens by using Cotter in just a few minutes.

Your website as the Client, Cotter as the Authorization Server

With the OAuth flow above, here's how it looks like:

Your website is the Client
Your user is the Resource Owner
Cotter is the Authorization Server
Your backend server is the Resource Server

Logging-in and Generating Access Tokens

We have several 5-minutes quickstarts for authenticating users and generating access tokens:

Web: HTML , React, Angular (also check out our Gatsby and Next.js tutorials).
Mobile: React Native, Flutter, iOS, Android

For this guide, we'll use React as an example. We'll build a login form with email magic link and get an access token at the end of the flow.

Import Cotter:

yarn add cotter

Initialize and show an email login form:

import React, { useEffect } from "react";
import Cotter from "cotter"; // 1️⃣ Import Cotter

function App() {
  useEffect(() => {
    // 2️⃣ Initialize and show the form
    var cotter = new Cotter(API_KEY_ID); // 👈 Specify your API KEY ID here
    cotter
      .signInWithLink() // use Magic link
      .showEmailForm() // show email login form
      .then(resp => console.log(resp))
      .catch(err => console.log(err));
  }, []);

  return (
    // 3️⃣ Put a <div> with id "cotter-form-container"
    // that will contain the form
    <div id="cotter-form-container" style={{ width: 300, height: 300 }} />
  );
}

export default App;

App.js

You can get your API_KEY_ID from the dashboard by creating a free account.

That's it. Check your console logs for an access token.

The function above covers steps 1-4 in the OAuth 2.0 flow. The response from showEmailForm() returns an access token. As described above, you should then use this access token to access a resource in your backend server.

For example, you can include this access token to your endpoint /api/private-resource and you'll check if the access token is valid before continuing with the request.

What's Next?

Now that you know how to get access tokens, here's a few more things to wrap up your login flow.

OAuth Tokens from Cotter: What tokens do you get, and how do they look like.
How to verify the access token and allow requests to private endpoints.
How to store it securely in the front end. We'll cover this next week, stay tuned!

Questions & Feedback

If you need help or have any feedback, ping us on Cotter's Slack Channel! We're here to help.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

Here's How to Integrate Cotter's Magic Link to Your Webflow Site in Less Than 15 minutes!

Kevin Chandra — Mon, 13 Jul 2020 23:01:12 +0000

In this tutorial we're going to guide you on how to authenticate your users using magic links on Webflow.

Webflow + Cotter's Magic Link Tutorial

Part 1: Cotter Setup

Go to https://dev.cotter.app to create an account. Once you have created an account make sure to create a new project and grab the API Key ID. We will be using your API Key ID later in part 3.

Part 2: Webflow Setup

For this tutorial we have created 2 pages: Login Page and Protected Page. The login page will display the embedded Cotter login form for your users to type in their email while the protected page will display protected content that only a logged in user can view.

Login Page Setup (where the login form will show up)

On the login page we need to include a section element to load Cotter's login form; moreover, we need to set that section id "cotter-form-container". This enables Cotter's JS SDK to load the login form to the section element that we just added.

After finishing the page setup we can start with adding custom code to the login page. Copy paste the code below to the custom code tab on the login page settings.

Get Cotter JS SDK

Add the code below to the head of the Login Page.

<!--Get Cotter JS SDK-->
<script src="https://js.cotter.app/lib/cotter.js" 
type="text/javascript"></script>

Initialize Cotter

Add the code below to the body of Login Page.

<!-- 2. Initialize Cotter -->
<script>
  var cotter = new Cotter("<YOUR_API_KEY_ID>"); // 👈 Specify your API KEY ID here
  cotter
    // Choose what method of login do you want
    // Sign In with Magic Link
    .signInWithLink()
    // Send Magic Link via email
    .showEmailForm()

    .then(payload => {
      // save OAuth token
      localStorage.setItem("user_session", JSON.stringify(payload));

      // redirect to the protected page
      window.location.href = "/protected";
    })
    .catch(err => {
      // handle error
    });
</script>

Make sure that you have pasted your API Key ID on the code block above.

Protected Page Setup (and any other page you want to protect)

Now let’s move on to the protected page, we need to include a header (h2) element and set that header id “welcome-text-heading” in order to load the user’s email address and a button element with button id “signout-button” to enable sign out functionality for the user.

Moreover, we’ll be adding custom code to both the header and the body. We’ll be adding custom code to the header to check if a user is logged in and to fetch the user’s OAuth token. The custom code in the body will be used to parse the user data and display his/her email on the page.

Add the code below to the header of the Protected Page

<script>
// 1. We check if a user has already logged in
var cotterOAuthToken = localStorage.getItem("user_session");

// 2. If user is not logged in then we redirect to the login page
if (!cotterOAuthToken || cotterOAuthToken.length <= 0) window.location.href = "/";

// 3. If user is logged in then we fetch the user data
let url = "https://cotterapp.herokuapp.com/login"
fetch(url, {
    method: 'POST',
    cache: 'no-cache',
    headers: {
      'Content-Type': 'application/json'
    },
    body: cotterOAuthToken
  })
  .then(resp => resp.json())
  .then(data => {
    if(!data.success) { window.location.href = "/" }
  });
</script>

Add the code below to the body of the Protected Page

<script>
// 1. Fetch the user data
let token = JSON.parse(cotterOAuthToken);
// 2. Display user email
document.getElementById("welcome-text-heading").innerHTML = `Welcome ${token.email},`;
// 3. Display sign out button
document.getElementById("signout-button").addEventListener("click", () => {
    window.localStorage.removeItem("user_session"); // Log user out
    window.location.href. "/"; // Redirect to login
});
</script>

Part 3: Publish and Test

We've arrived at the last part of this tutorial and all that you need to do is to click publish and test Cotter's magic link authentication for your Webflow website!

Questions & Feedback

Come and talk to the founders of Cotter and other developers who are using Cotter on Cotter's Slack Channel.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

If you need help, ping us on our Slack channel or email us at team@cotter.app.

Stop spending days to code your login page! Add Cotter's magic link to your Gatsby app under 5 minutes

Kevin Chandra — Thu, 02 Jul 2020 01:27:27 +0000

Supercharge your Gatsby app's authentication system with Cotter's magic link. Like how Slack does it, but simpler.

In this guide, we'll show you how to integrate Cotter's magic link authentication to Gatsby.

Let's get started

a. Install Gatsby

# If you don't have Gatsby installed, run
npm install -g gatsby-cli
# Check if Gatsby exist
gatsby -v

Our current version: Gatsby CLI version: 2.12.15

b. Create New Gatsby Project

Let's start with an empty Gatsby project and name it gatsby-cotter.

gatsby new gatsby-cotter
cd gatsby-cotter && gatsby develop

This will create a new gatsby project with the name gatsby-cotter

Head to src/pages/index.js and modify the default Gatsby homepage HTML template by copy pasting the code below:

import React, { useState, useEffect } from "react"; // 👈 Add useEffect here!
// 2️⃣ TODO: Import Cotter

import "./styles.css";

const IndexPage = () => {
  const [responsePayload, setResponsePayload] = useState(null);
  const [loggedIn, setLoggedIn] = useState(false);

  // 3️⃣ TODO: Initialize Cotter and show the form

  return (
    <div className="container">
      <h1 className="title">Passwordless App.</h1>

      {/* 1️⃣ TODO: Setup a div to contain the form */}

      <div id="user-info">
        { loggedIn ? `Welcome, ${responsePayload.email}` : "You are not yet authenticated" }
      </div>

      {
        loggedIn 
        ? <div id="user-response">
          <div className="success">Verification Success</div>
          <div className="title-response">User info from Cotter:</div>
          <pre>{JSON.stringify(responsePayload, null, 4)}</pre>
        </div>
        : null
      }
    </div>
  );
}

export default IndexPage

your src/pages/index.js should be exactly like above

ERROR: It's Ok.

You will see an error indicating that you have not specified styles.css. Create a styles.css page under src/pages/styles.css and copy the code below:

.container {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  height: 100vh;
  width: 100vw;
}

#user-info {
  padding: 10px;
  max-width: 350px;
  border-radius: 4px;
  background-color: #f5f5f5;
  margin-bottom: 10px;
}

#user-response {
  max-width: 500px;
  max-height: 400px;
}

.success {
  padding: 10px;
  border-radius: 4px;
  border: 1px solid #f0f0f0;
  text-align: center;
  color: hsl(171, 100%, 41%);
  margin-bottom: 10px;
}

pre {
  word-wrap: break-word;
  background-color: #2e2e2e;
  padding: 10px;
  border-radius: 4px;
  color: white;
  overflow: scroll;
}

.title-response {
  font-size: 13px;
  color: black;
}

src/pages/styles.css

Integrating Cotter's Magic Link

a. Install Cotter

npm install cotter

You may need to re run gatsby develop if you find any errors saying that you missed a few files inside node_modules. You can continue when if you don't see any errors.

b. Build the login form

Copy the code below

{/* 1️⃣ TODO: Setup a div to contain the form */}
<div
  id="cotter-form-container"
  style={{ width: 300, height: 300 }}
></div>

src/pages/index.js

Then we import Cotter.

// 2️⃣ TODO: Import Cotter
import Cotter from "cotter"; // 👈 Add Cotter here!

on the beginning of src/pages/index.js

Here we initialize Cotter, then show the form.

// 3️⃣ TODO: Initialize Cotter and show the form
useEffect(() => {
    var cotter = new Cotter("<YOUR_API_KEY_ID>");
},[]);

src/pages/index.js

Replace <YOUR_API_KEY_ID> above with your API Key ID. Copy the code below to display the form.

// 3️⃣ TODO: Initialize Cotter and show the form
useEffect(() => {
    var cotter = new Cotter("<YOUR_API_KEY_ID>");
+ cotter.signInWithLink().showEmailForm().then(payload => {
+ setResponsePayload(payload);
+ setLoggedIn(true);
+ });
}, []);

src/pages/index.js

To authenticate your users using a magic link via email, we will be using the signInWithLink function and showEmailForm as written above.

You can send the magic link through SMS/WhatsApp as well by using showPhoneForm

Once a user is successfully authenticated, the payload will return information such as oauth_token , user's identifier (email or phone number), and Cotter's token.

You can see that showEmailForm returns a Promise, that means you can simply handle any error by chaining a catch keyword after then.

The Finish Line

Gatsby Email Link Authentication using Cotter

Done! You can now authenticate your users using a magic link without backend servers to store your users' credentials.

Find the complete code here.

What's next?

You may have a backend service that serves your users personalized content. If so, then you will need to validate the payload on your backend server. Then, you can send your own authentication token to the client side, or simply use our oauth_token to validate your users from now on.

Learn more about OAuth tokens returned from Cotter here to know more!

Questions & Feedback

Come and talk to the founders of Cotter and other developers who are using Cotter on Cotter's Slack Channel.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

If you need help ping us on our Slack channel or email us at team@cotter.app.

Flutter Email & Phone Auth: 3 Simple Steps To Log Your Users In via Email, SMS, and WhatsApp using Cotter

Putri Karunia — Tue, 23 Jun 2020 17:00:00 +0000

When building an app, it's often a requirement to make sure your users are real and you want to know if they own the email or phone number that they signed up with so you can communicate via those channels.

In this tutorial, we'll build a flutter app that allows users to sign up and sign in with their email or phone number.

In this post:

Create a Flutter App
Sign in with Email
Sign in with Phone Number via SMS or WhatsApp
See the result: Sign in with Phone Number

Create a Flutter App

If this is your first time making a Flutter app, check out their installation guide. To create a new flutter app, run:

flutter create flutter_passwordless
cd flutter_passwordless

// Run your app
flutter run

Sign in with Email

Make a Welcome Page

We'll edit lib/main.dart to make our welcome page. Replace the contents with the following code:

import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Cotter Passwordless App',
      theme: ThemeData(
        primaryColor: Colors.deepPurpleAccent,
        buttonTheme: ButtonThemeData(minWidth: double.infinity),
      ),
      home: HomePage(),
    );
  }
}

class HomePage extends StatefulWidget {
  @override
  HomePageState createState() => HomePageState();
}

// Our Home Page
class HomePageState extends State<HomePage> {
  final inputController = TextEditingController();

  // 1️⃣ TODO: Initialize Cotter
  // 2️⃣ TODO: Make Sign Up & Login Function

  // This is a helper function that shows the response
  // from our Sign Up and Login functions.
  _showResponse(BuildContext context, String title, String content) {
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text(title),
        content: Text(content),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Container(
        padding: EdgeInsets.all(20),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // Welcome Titles
            Text("🦊", style: TextStyle(fontSize: 50)),
            Text("Welcome.",
                style: TextStyle(fontWeight: FontWeight.bold, fontSize: 30)),

            // Email Input Form
            Form(
              child: TextField(
                decoration: InputDecoration(labelText: "Email"),
                controller: inputController,
              ),
            ),

            // Sign In Button
            MaterialButton(
              onPressed: () {},
              color: Colors.deepPurpleAccent,
              textColor: Colors.white,
              child: Text("Sign In With Email"),
            ),
          ],
        ),
      ),
    );
  }
}

Sign Up New Users or Login Existing Users

Notice that we only have a "Sign in" button. We've combined the sign up and login functionality. After verifying the user's email:

If it's a new user, the SDK will automatically create a new user in Cotter, and return the new user to you.
If it's a user that already exists in Cotter, the SDK will return the existing user information.

Step 1: Add Cotter to your project

Add Cotter to your pubspec.yaml, then run flutter pub get.

dependencies:
  cotter:

pubspec.yaml

Check the latest releases in pub.dev.

You may need to restart your flutter for it to run pod install (stop flutter run and re-run it).

Initialize Cotter

Import Cotter in your lib/main.dart, then initialize it inside HomePageState.

+ import 'package:cotter/cotter.dart'; // Import Cotter

class HomePageState extends State {
  ...

  // 1️⃣ Initialize Cotter
+  Cotter cotter = new Cotter(apiKeyID: API_KEY_ID); // 👈 Specify your API KEY ID here

  // 2️⃣ TODO: Make Sign Up & Login Function

  _showResponse(BuildContext context, String title, String content) {...}

  @override
  Widget build(BuildContext context) { ... }
}

lib/main.dart

You can create a free account at Cotter to get your API_KEY_ID.

Step 2: Setup Deep-Linking

To sign in using email verification, we will open a secure in-app browser where the user can enter the OTP sent to their email. We'll need to set a redirect URL that points to your app to tell the in-app browser what to do after it's finished authenticating. Let's set the redirect URL as myexample://auth_callback.

Setup in iOS

Add the following to your ios/Runner/Info.plist.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>myexample</string> <!-- 👈 Setting scheme to myexample:// -->
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myexample</string> <!-- 👈 Setting scheme to myexample://  -->
    </array>
  </dict>
</array>

ios/Runner/Info.plist

Setup in Android

Add the following to your android/app/src/main/AndroidManifest.xml.

<manifest ...>
    <application ...> 
    ...

    <!-- Add the lines from here -->
    <activity android:name=".CallbackActivity" >
      <intent-filter android:label="flutter_web_auth">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- 👇 This is for myexample://auth_callback -->
        <data android:scheme="myexample" android:host="auth_callback"/>
      </intent-filter>
    </activity>
    <!-- Until here -->

  </application>
</manifest>

android/app/src/main/AndroidManifest.xml

Now stop flutter run and re-run it.

Step 3: Make a Sign Up/Login Function

To sign in using email verification, call cotter.signInWithEmailOTP.

// 2️⃣ Make Sign Up & Login Function
  void signUpOrLogin(BuildContext context) async {
    try {
      // 🚀 Verify email, then create new user or login
      var user = await cotter.signInWithEmailOTP(
        redirectURL: "myexample://auth_callback",
        email: inputController.text,
      );

      // Show the response
      _showResponse(context, "User Created",
          "id: ${user.id}\nidentifier: ${user.identifier}");
      print(user);
    } catch (e) {
      _showResponse(context, "Error", e.toString());
    }
  }

lib/main.dart

Call the function from our button

class HomePageState extends State<HomePage> {
  @override
  Widget build(BuildContext context) {
          ...
              // Sign In Button
              MaterialButton(
                onPressed: () {
+                 signUpOrLogin(context);
                },
                color: Colors.deepPurpleAccent,
                textColor: Colors.white,
                child: Text("Sign in With Email"),
              ),
          ...
  }
}

lib/main.dart

That's It for Email Login

Now you should be able to sign up and log in with email.

Sign In with Phone Number

Let's add another page to try signing up with a phone number. Make a new file called phoneSignIn.dart inside the lib folder:

touch lib/phoneSignIn.dart

Then, copy the code below:

import 'package:flutter/material.dart';

void main() {
  runApp(PhoneSignInPage());
}

class PhoneSignInPage extends StatefulWidget {
  @override
  PhoneSignInPageState createState() => PhoneSignInPageState();
}

// Our Home Page
class PhoneSignInPageState extends State<PhoneSignInPage> {
  final inputController = TextEditingController();

  // 1️⃣ TODO: Initialize Cotter
  // 2️⃣ TODO: Make Sign Up & Login Function

  // This is a helper function that shows the response
  // from our Sign Up and Login functions.
  _showResponse(BuildContext context, String title, String content) {
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text(title),
        content: Text(content),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Container(
        padding: EdgeInsets.all(20),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text("Sign in with Phone Number.",
                style: TextStyle(fontWeight: FontWeight.bold, fontSize: 20)),
            Text("Open pre-built phone input form.",
                style: TextStyle(color: Colors.grey)),

            // Button to open a pre-built phone input form
            Container(
              margin: EdgeInsets.symmetric(vertical: 30),
              child: MaterialButton(
                onPressed: () {},
                color: Colors.deepPurpleAccent,
                textColor: Colors.white,
                child: Text("Sign In with Phone"),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

lib/phoneSignIn.dart

Go to Phone Sign In Page from the Home Page

Let's make a button in our home page to go to this new PhoneSignInPage. Add a button in lib/main.dart.

import 'package:flutter_passwordless/phoneSignIn.dart';

class HomePageState extends State {
  @override
  Widget build(BuildContext context) {
    ...
        // Sign In Button
        MaterialButton(
          onPressed: () { signUpOrLogin(context); },
          color: Colors.deepPurpleAccent,
          textColor: Colors.white,
          child: Text("Sign In With Email"),
        ),

        // Button to go to Phone sign in
        OutlineButton(
          onPressed: () {
            Navigator.push(
              context,
              MaterialPageRoute(builder: (context) => PhoneSignInPage()),
            );
          },
          color: Colors.deepPurpleAccent,
          textColor: Colors.deepPurpleAccent,
          child: Text("Go to Phone Sign In \u2192"),
        ),  
    ...
  }
}

lib/main.dart

Initialize Cotter

Just like before, import Cotter in your lib/phoneSignIn.dart, then initialize it inside HomePageState.

+ import 'package:cotter/cotter.dart'; // Import Cotter

class PhoneSignInPageState extends State {
  ...

  // 1️⃣ Initialize Cotter
+  Cotter cotter = new Cotter(apiKeyID: API_KEY_ID); // 👈 Specify your API KEY ID here
  // 2️⃣ TODO: Make Sign Up &amp; Login Function

  _showResponse(BuildContext context, String title, String content) {...}

  @override
  Widget build(BuildContext context) {...}

lib/phoneSignIn.dart

Open your dashboard to get your API_KEY_ID. To send SMS or WhatsApp messages, you need to add a balance to your account.

Make a Sign Up/Login Function

To sign in using phone verification, call cotter.signInWithPhoneOTP. This will open a pre-built phone number input inside the in-app browser. You can also use your own input form if you want.

  // 2️⃣ Make Sign Up &amp; Login Function
  void signUpOrLogin(BuildContext context) async {
    try {
      // 🚀 Verify phone number, then create new user or login
      var user = await cotter.signInWithPhoneOTP(
        redirectURL: "myexample://auth_callback",
        channels: [PhoneChannel.SMS, PhoneChannel.WHATSAPP], // show SMS and WhatsApp options
      );

      // Show the response
      _showResponse(context, "Sign In Success",
          "User id: ${user.id}\nidentifier: ${user.identifier}");
      print(user);
    } catch (e) {
      _showResponse(context, "Error", e.toString());
    }
  }

lib/phoneSignIn.dart

Call the function from our button

class PhoneSignInPageState extends State<PhoneSignInPage> {
  @override
  Widget build(BuildContext context) {
        ...
            // Button to open a pre-built phone input form
            Container(
              margin: EdgeInsets.symmetric(vertical: 30),
              child: MaterialButton(
                onPressed: () {
+                 signUpOrLogin(context);
                },
                color: Colors.deepPurpleAccent,
                textColor: Colors.white,
                child: Text("Sign In with Phone"),
              ),
            ),
        ...
  }
}

lib/phoneSignIn.dart

That's It

Now you should be able to login using your phone number via SMS or WhatsApp.

Phone Login via SMS or WhatsApp using Cotter's Flutter SDK

What's Next?

The signUp and login functions that you implemented automatically create access tokens for you and store it securely within the device. It also saves the currently logged-in user and automatically refreshes your access token when it's expired. Learn how to:

Implement Sign in with Device so you don't have to send an email or SMS on every login.
Getting the Logged-in User
Getting Access Token, ID Token, and Refresh Token

Questions & Feedback

If you have any questions or feedback, feel free to join Cotter's Slack Channeland chat us there.

Ready to use Cotter?

If you enjoyed this tutorial and want to integrate Cotter into your website or app, you can create a free account and check out our documentation.

DEV Community: Cotter

Cotter + Cloudflare Workers + Google Calendar API: Build a Serverless Calendar Booking App

👉 Try out the live demo!

We'll use:

Why Cloudflare Workers?

What about a database?

Why do we need a backend?

TLDR

How it works

Logging In

Getting Google's Access Token via Google Sign In

Cloudflare Worker Endpoints

Making API endpoints at Cloudflare Workers to call Google's API

Create a Cloudflare Account and Setup Workers

Create a Test Worker to see how this works

Creating Endpoints

Endpoints

Endpoint #1: checkconnection

Check if the user has Google Connected.

Here are the things that we'll need to do:

Code & Env Variables

Add the Cotter Api Keys as environment variables

Endpoint #2: createevent

Create a Google Calendar Event

Here are the things that we'll need to do:

Code & Env Variables

Endpoint #3: disconnect

Disconnect the user's Google Account

Here are the things that we'll need to do:

Code & Env Variables

That's it!

👉 Try the live demo, it's fully functional

Questions & Feedback

Ready to use Cotter?

The Simplest Way to Authorize Github OAuth Apps with Next.js and Cotter

What we're building

Overview

Let's Start – Make our Home Page

Create your Next.js project

Add a Login Form in the Home Page

Add Cotter as a dependency

Add a Login Form and a Title

Enable Github Login

You should now see the Sign in with Github button in our Next.js app.

Let's see how this works before moving on to Github API

1. Let's try logging in with your email address first.

2. Let's try logging-in again but with your Github account that has the same email address

Designing our API endpoints to get data from Github

Make our API endpoint at /api/repo

1. Make a function to handle API calls to /api/repo

2. Check if the Authorization Header have a valid access token

3. Get the Cotter User ID from the access_token.

4. Get Github Access Token from Cotter API

5. Call Github API to get the repositories list

That's it, let's try our API endpoint

Showing the Repo List in our Dashboard Page

Make the Dashboard Page

If you sign-in with Github, then go to localhost:3000/dashboard , you'll see the following:

Add a NavBar to Log Out or Log In and navigate between pages

Make the checkLoggedIn function

Make the logOut function

Import the Navbar in your Home Page and Dashboard Page

Great! Now our website works well and users can log in/log out and get their Repositories list.

But, what if the user didn't Sign in with Github?

How do we fix this?

Add a button to Connect Github if not connected yet.

How do I disconnect a Github Account

That's it!

What's Next?

Questions & Feedback

Ready to use Cotter?

How to Make an Interactive Todo List CLI using Python with an Easy Login Mechanism

The API

The CLI

Let's start with a super simple CLI

Now let's build our Todo List CLI.

Start with Registering/Logging-in our users to the API

Register or Login the user to the todo list API

Create a Todo List

Add a Task to the list

Endpoint #1: `checkconnection`

Endpoint #2: `createevent`

Endpoint #3: `disconnect`

Make our API endpoint at `/api/repo`

1. Make a function to handle API calls to `/api/repo`

3. Get the Cotter User ID from the `access_token`.

If you sign-in with Github, then go to `localhost:3000/dashboard` , you'll see the following:

Make the `checkLoggedIn` function

Make the `logOut` function

Step 1: Setup a div to contain Cotter's verification form in `src/app/app.component.html`

Step 2: Import Cotter in `src/app/app.component.ts` and show the form

What does `signInWithWebAuthnOrLink` do?

Step 4: Send the `credential` to your server

Step 4: Send the `assertion` to your server and verify it