Forem: Michelle Marcelline

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.

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.

Forem: Michelle Marcelline

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

OAuth 2.0 Recap:

Common OAuth 2.0 Flows

Which Flow Should I Use?

Web Server Apps and Command Line Scripts

→ Use Authorization Code Flow

Authorization Code Flow

How do I do this from the command line?

Single Page Apps & Mobile Apps

→ Use Authorization Code Flow with PKCE

How does the PKCE flow work without a Client Secret?

Authorization Code Flow with PKCE

Server-to-Server API calls

→ Use Client Credentials Flow

Client Credentials Flow

TV Apps and other apps on input-constrained devices

→ Use Device Code Flow

Device Code Flow

That's It!

References

Questions & Feedback

Ready to use Cotter?

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

What is WebAuthn?

Registration with WebAuthn

Logging-in with WebAuthn

Implementation

Try WebAuthn in Action.

Short Guide for Implementing WebAuthn with React

Implement Login with WebAuthn

What does signInWithWebAuthnOrLink do?

Implementation with vanilla JS

Registration

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

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

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

Step 4: Send the credential to your server

Login

Step 1: Send a request to your server to login

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

Step 3: The front-end signs the challenge

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

A few things to think about:

Support for WebAuthn

That's It!

References

Questions & Feedback

Ready to use Cotter?

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

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.

A Recap about Access Token & Refresh Token

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

Local Storage

Cookies

About XSS Attack

Cookies and CSRF Attack

Conclusion

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

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

So how does this set up work?

That's It!

References

Questions & Feedback

Ready to use Cotter?

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

What is OAuth 2.0?

OAuth 2.0 in Action

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

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

OAuth Tokens

Short-lived access tokens and long-lived refresh tokens

Access Token

Refresh Token

How to Implement OAuth 2.0 for your site

Your website as the Client, Cotter as the Authorization Server

Logging-in and Generating Access Tokens

Import Cotter:

Initialize and show an email login form:

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

What does `signInWithWebAuthnOrLink` do?

Step 4: Send the `credential` to your server

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