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

1. What is OAuth 2.0
2. OAuth 2.0 in Action
3. OAuth Tokens: Short-lived access tokens and long-lived refresh tokens
4. 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 Google to sign-in where he granted Calendar permission for calendly.com. (2) Google returned an Authorization Grant and redirected Albert to calendly.com.
• (3) Calendly.com gave the Authorization Grant to Google and (4) received 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 Accounts 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 went to a hotel and wants to allow her babysitter, Candy, to access her room.

1. Alberta agrees that Candy should access her room, and asked Candy to get her own room key from the receptionist. She gave Candy a copy of her ID and a note saying "access during daytime only".
2. Candy went 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 the daytime.
3. Candy goes back to the room and used her key to access the room.

• Candy is the Client, a regular website (like Calendly.com) that wants to access Alberta's data. Alberta here is granting limited access to the Client. The Authorization Grant is Alberta's copy of the ID card 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 wanted: 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 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 just validate the JWT Token without needing to access the database to check if it's valid.

All your server needs to do is validate that the JWT Token is valid using a library, and 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, generally refresh tokens are opaque strings stored in the database to allow you to revoke these tokens.

Because there is no way to expire an Access Token, we should make the access token short-lived. Revoking the refresh token prevents any 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 Cotterfunction 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;

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.