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.
- 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
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.
In general, the OAuth 2.0 flow looks like this:
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 use an example of Alberta who went to a hotel and wants to allow her babysitter, Candy, to access her room.
- 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".
- 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.
- 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 :)
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?
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.
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.
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.
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.
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.
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
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.
yarn add cotter
You can get your
API_KEY_ID from the dashboard by creating a free account.
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.
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!
If you need help or have any feedback, ping us on Cotter's Slack Channel! We're here to help.