Among the many authentication methods available, GitHub OAuth has emerged as a useful tool for improving user login experience while strengthening security measures.

Django, a Python web framework, has recently gained popularity in web development due to its efficiency and versatility. Adding GitHub OAuth to your Django projects helps improve the authentication process.

Django developers can use GitHub OAuth to access a user's GitHub profile and (with permission) their repositories to personalize the user experience and tailor application services.

This article will walk you through how to implement GitHub OAuth. You'll see the benefits to your Django projects as we go. By embracing this technology, you can give users a seamless login experience while adhering to strict security standards.

Prerequisites

If you wish to follow this guide, you need to have a basic understanding of these tools or have them installed on your PC:

• GitHub
• Django
• Django Rest Framework

How to Create a GitHub OAuth Application

You must sign into your GitHub account to create a GitHub OAuth application.

First, login to your GitHub account, click on your GitHub profile picture, and select Settings.

Login to GitHub and select "Settings" from the sidebar menu

Then, once the new page comes up, scroll to the bottom and select Developer Settings.

Scroll to the bottom and select "Develop Settings"

Select OAuth Apps and click on New OAuth App.

Creating a new OAuth app

Define your OAuth application by naming it.

• The Homepage URL should be the URL that leads to the homepage of your website.
• The Authorization callback URL should be a site, or a page users view after their GitHub account has been authenticated.

Once you are done defining it, click Register application.

Register your application once all the info has been filled in

Next, you'll need a client secret and a client ID key to access your GitHub OAuth app on your Django project.

The Client ID is already defined once you create an application. Click Generate a new client secret to create a client secret key.

Creating a client secret key

You might be prompted to sign in. Do so to continue.

Sign in to continue

Once you log in, your client's secret key will be generated. Copy and save it on your .env file.

Copy your secret key to your .env file

Now that you’ve set up your GitHub OAuth application, let’s connect it to your Django project.

How to Integrate GitHub OAuth with Django

This part will link your Django project's GitHub OAuth application to it using the social-auth app package.

First, install the dj-rest-auth package and define it on your settings.py.

pip install dj-rest-auth

Then configure dj-rest-auth package on your settings.py.

# Application definition
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "django.contrib.sites",
    "rest_framework",
    "rest_framework.authtoken",
    "dj_rest_auth",
    "allauth",
    "allauth.account",
    "allauth.socialaccount",
    "allauth.socialaccount.providers.github",
    "oauth2_provider",
    "users",
]

You'll need to enable the authentication classes for dj-rest-auth by updating REST_FRAMEWORK and AUTHENTICATION_BACKENDS on your settings.py.

Optionally, you can configure allauth if you intend to use templates. Do this on your settings.py file.

AUTHENTICATION_BACKENDS = ("allauth.account.auth_backends.AuthenticationBackend",)

REST_USE_JWT = True  # Use JWT for authentication with dj-rest-auth
SITE_ID = 1 #Set site ID

SITE_ID = 1  # Set the site ID

# Disable email verification for simplicity
ACCOUNT_EMAIL_VERIFICATION = "none"
LOGIN_REDIRECT_URL = "/"  # Redirect URL after successful login
LOGOUT_REDIRECT_URL = "/"  # Redirect URL after logout

SOCIALACCOUNT_PROVIDERS = {
    "github": {
        "APP": {
            "client_id": "YOUR_GITHUB_CLIENT_ID",
            "secret": "YOUR_GITHUB_SECRET_KEY",
            "key": "",
            "redirect_uri": "http://localhost:8000/accounts/github/login/callback/",
        }
    }
}

A Django app is required for this guide. Let's call it users. Head over to the views of the Django app and define the following code:

from allauth.socialaccount.providers.github.views import GitHubOAuth2Adapter
from allauth.socialaccount.providers.oauth2.client import OAuth2Client
from dj_rest_auth.registration.views import SocialLoginView

class GitHubLogin(SocialLoginView):
    adapter_class = GitHubOAuth2Adapter
    callback_url = CALLBACK_URL_YOU_SET_ON_GITHUB
    client_class = OAuth2Client

# Define the urls.py on the Django app
urlpatterns += [
    path('github/', GitHubLogin.as_view(), name='github_login')
    ]

How to Set Up a New Application

To specify the GitHub OAuth credentials, you'll need to log into the Django social application model. This will provide your Django project with an additional degree of protection. Because of this, changing the OAuth credentials will be simple and won't damage your existing code.

Start by logging into your Django admin, clicking Social Applications, and selecting Add Application. This will prompt you to create a new application.

On Django admin, select "Social applications"

You will be prompted to enter information on the new page.

• Select GitHub as the provider.
• Give your social app a name.
• Enter the Client Secret and Client ID created from your GitHub OAuth app.
• Select the site on Available sites and move it to Chosen sites. Once done, click Save. This will create a new application.

Create/Add a Social application

Change your site domain to localhost since this is still the development phase.

Select, "Site" to change the existing the site domain

Select example.com and change it to http://127.0.0.1:8000/ then Save.

Change your site domain from example.com to http://127.0.0.1:8000/

How to Test the Defined Social App

Once you are done defining and setting up the social Django app on your project, you will need to test it and make sure that it works.

If you open the route http://127.0.0.1:8000/auth/github/, you'll need to enter some information such as Access token, ID token, and code.

We'll manually get this information, as the front end is meant to get and parse this information.

Go to the GitHub registration page to test the defined social app

To do this, head over to https://github.com/settings/apps and select Personal access tokens then select Generate new token. Use the second option, Generate new token (classic), since this guide is focused on authenticating users just to get their GitHub user info.

On GitHub settings, select "Personal access tokens" then select "Generate new token".

Give the token a name and select scopes. Ensure you check all the user scopes. Then generate a new token.

Define your new token

Your new token should look like this. Ensure you store it somewhere safe.

Copy the generated personal access token generated by GitHub.

Head over to http://127.0.0.1:8000/auth/github/. Enter the access token generated and voilà! Your user access token and GitHub username will be sent as a response on the body.

Using your token and GitHub username ensure the backend system works

How to Implement OAuth Authentication Flow

You have successfully installed and tested the dj-rest-auth package. Next, you will learn how to test the OAuth flow and how it obtains user data from GitHub.

To test the GitHub OAuth authentication flow, you'll need to send a request to https://github.com/login/oauth/authorize.

You can do so by either using curl:

"https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://127.0.0.1:8000/auth/callback/&scope=user"

(and making sure you use the same redirect URI defined in your GitHub OAuth application) or opening https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://127.0.0.1:8000/auth/callback/&scope=user on your browser. It will redirect you to an authorization page.

Send a request to GitHub OAuth authentication flow

Click Authorize YOUR USERNAME to authorize the user.

Click "Authorize" to authorize your GitHub user

You will be redirected to a URL showing the code. With the code, you can generate the access token needed to authenticate the user.

Use the code from GitHub to generate an access token for your auth

To get the access token, send a request to this URL: https://github.com/login/oauth/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=CODE

Or you can choose to use curl to send the request.

"https://github.com/login/oauth/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=CODE"

This should either download the access token for you or return it as a response body depending on how you defined it. The response should look like this:

Your response from your backend authentication system

Now, with this token, you can authenticate your user when they make any request.

Conclusion

In conclusion, setting up GitHub OAuth on Django is a helpful way to enable users to log in to your web applications using their GitHub credentials.

By following this guide, you can enhance your application's security and access your users' data which improves the user experience of your Django app.

In this article, we will give you a quick rundown of how to set up a GitHub OAuth application.

Create Your Application

Begin by navigating to your GitHub settings (make sure you are logged in!). Scroll down to the bottom of the sidebar and click "Developer Settings".

This will take you to the application page:

You may see some applications you've previously authorised.

Click the "New OAuth App" button to create a new application.

Fill in the form and click "Register application". This will create your application and take you to the settings page.

For OAuth applications, you will need the Client ID. You will also need to generate a client secret. Click the "Generate a new client secret" to do so.

Make sure to save this secret in a secure location as you will not be able to view it again.

Using Your New Application

Now that you have a client ID and secret, you can use your OAuth application in your project.

If you want to learn how to do so, freeCodeCamp's curriculum can teach you.

Happy coding!

There is, of course, a more complex process involved in setting up social login, but for a user it's as simple as clicking a button to log in.

The ease of not having to remember an ID/password and just being able to signup/login through the click of a button is extremely beneficial to the user.

What if I Told You This Was Way More Secure? 😉

Social logins really help us achieve a few things:

• Support for multiple devices
• Single Sign On
• Simple to implement
• The ability to share data for users without having to release personal information
• Ability revoke an active session i.e not allow a third party access to the login and data
• There are no long-lasting credentials being exchanged

So What Technology Drives Social Login? 🤔

The underlying protocol used is something called OAuth. It is defined as:

An open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications.

Now with a basic understanding of social login and the above definition you probably have some idea of how this works – but let me use a simple example to explain how to use OAuth.

I remember my friend Sumedh describing it as an interaction between a Mother, Father, and their Son. Imagine that the mother wants some groceries from the market and she wants the son to buy them for her.

Before I go into the conversation let me set some context.

Mother: The user of the application

Son: Third party client or in technical terms the OAuth Client

Father: The Social Account or in technical terms the OAuth Provider

The conversation could possibly go like this:

Mother: Hey son, go to the market and bring me some coffee powder. Take the required money from your father.

Son: Okay.

Son (OAuth client) goes to father (OAuth provider)

Son: Hey dad, mom told me to take money from you since she wants some things from the market.

Father (OAuth provider) asks mother (User) about the permission to give money to their son (OAuth client)

Father: Hey, shall I give him the money and how much?

Authorization of your application takes place here.

Mother: Yes, please give it to him.

Permission grant by mother (User)

Son (OAuth client) gets the required things from the market and returns them to mother (User). Here returning things to mother (User) can be thought of redirecting the user (or logging them) into the third party site.

For a more technical understanding of how this works in code, Richard Schneeman has this amazing video below:

Now Lets Put All of This in Context

Let's take as an example the DEV Community. If you wanted to create an account on the DEV Community using Twitter, what would happen?

Basically, if the "Sign up with Twitter" button exists, then the initial setup between the OAuth Client (Dev.to) and the OAuth Provider (Twitter) is already done.

The Client triggers a permission granting page for the OAuth Provider based on the credentials it receives from the initial setup. This looks something like below:

Once you login and grant permission, the OAuth Provider redirects you back to the client and the client gets a token to access your information from the OAuth Provider. This access token enables the client to get specific data from the provider

Based on that data the client then creates an account and logs you in

What Happens on Successive Login?

Thats a good question. Now OAuth has multiple grant types, and based on that we have different ways to get an access token from the OAuth Provider.

For all subsequent logins, the OAuth Client will hit the provider and generate a new access token to get access to the data and do the login.

Thus this enables us to achieve Single Sign On, the ability to share data for users without having to release personal information, the ability to revoke access, and the ability to not have long lasting credentials exchanged.

This all leads to a more secure experience.

Conclusion

I hope this short blog post helps you understand why social logins are more secure than the traditional username/password option. I will be writing about the different OAuth Grant types in the future and will be providing code examples as well.

Thanks for reading! I really hope that you find this article useful. I'm always interested to know your thoughts and happy to answer any questions you might have in your mind. If you think this post was useful, please share it to help promote this piece to others.

Thanks for reading! :)

P.S Do feel free to connect with me on LinkedIn or Twitter

This post is originally from www.jaredwolff.com

Privacy.

Performance.

Brilliant looks.

Can you have all three?

(Of course!)

Having a statically generated blog is great. Many folks use services like Disqus and Google Analytics to make them even better. Not surprising if you were one of them! Privacy concerns are are the forefront of everyone’s attention. So, rather than keeping the status quo, it’s time to do something about it!

If you've been looking to protect your site visitor's privacy and improve performance this blog post is for you.

In this article we'll be using DigitalOcean’s Docker droplet. It allows you to host several different applications/services on one (virtual) machine. By the end of it you'll know how to run your own comments server using Commento. Plus i’ll share a few tricks i’ve learned along the way to make it much easier for you.

Leeeets go!

Reverse Proxy

One of the most important aspects of this setup is the reverse proxy. A reverse proxy acts like a router. Requests come in for a certain domain. That request is then routed to the service associated with that domain.

Here’s a diagram from the Nginx Reverse Proxy + Let’s Encrypt Helper documentation. It'll help illustrate the idea.

Another benefit is that there’s an extra layer of protection to the outside world. Your websites run in a private network and the only access is through the Nginx reverse proxy. Point your DNS to the server and Nginx handles all the magic.

Here's how to get it setup:

1. Go ahead and set up your Digital Ocean Droplet. All the info you need is right here. The $5 version is more than sufficient.

2. Go here to clone the repository. You can also run this in your terminal. Make sure you SSH into your Digital Ocean droplet first!

   git clone git@github.com:evertramos/docker-compose-letsencrypt-nginx-proxy-companion.git

3. Change directories to the cloned repository.

4. Copy .env.sample to .env and update the values inside. I had to change the IP value to the IP of my Digital Ocean Droplet. I left all the other ones alone.
5. Run docker-compose up -d to start everything. (you can run without the -d option to make sure everything starts ok. Or you can attach the log output using docker container logs -f <container name

When pointing your sub-domains to this server, make sure you use an A record. Here's an example of mine:

Depending on your DNS provider, you'll have to figure out how to set an A record. That is beyond the purpose of this article though!

Setting Up Commento with Docker Compose

Here is the current docker compose file i'm using for Commento. It includes a few more environment variables for configuring Github, Gitlab and Google. It also includes the environment variables for setting the SMTP settings. These parameters are important. Otherwise you can't receive password reset or moderation emails!

version: '3'

services: commento: image: registry.gitlab.com/commento/commento container_name: commento restart: always environment: COMMENTO_ORIGIN: https://${COMMENTS_URL} COMMENTO_PORT: 8080 COMMENTO_POSTGRES: postgres://postgres:postgres@postgres:5432/commento?sslmode=disable COMMENTO_SMTP_HOST: ${SMTP_HOST} COMMENTO_SMTP_PORT: ${SMTP_PORT} COMMENTO_SMTP_USERNAME: ${SMTP_USERNAME} COMMENTO_SMTP_PASSWORD: ${SMTP_PASSWORD} COMMENTO_SMTP_FROM_ADDRESS: ${SMTP_FROM_ADDRESS} COMMENTO_GITHUB_KEY: ${COMMENTO_GITHUB_KEY} COMMENTO_GITHUB_SECRET: ${COMMENTO_GITHUB_SECRET} COMMENTO_GITLAB_KEY: ${COMMENTO_GITLAB_KEY} COMMENTO_GITLAB_SECRET: ${COMMENTO_GITLAB_SECRET} COMMENTO_GOOGLE_KEY: ${COMMENTO_GOOGLE_KEY} COMMENTO_GOOGLE_SECRET: ${COMMENTO_GOOGLE_SECRET} COMMENTO_TWITTER_KEY: ${COMMENTO_TWITTER_KEY} COMMENTO_TWITTER_SECRET: ${COMMENTO_TWITTER_SECRET} VIRTUAL_HOST: ${COMMENTS_URL} VIRTUAL_PORT: 8080 LETSENCRYPT_HOST: ${COMMENTS_URL} LETSENCRYPT_EMAIL: ${EMAIL} depends_on:

• postgres networks:
• db_network

• webproxy

  postgres: image: postgres container_name: postgres environment: POSTGRES_DB: commento POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres networks:

• db_network volumes:

• postgres_data_volume:/var/lib/postgresql/data

  networks: db_network: webproxy: external: true

  volumes: postgres_data_volume:

To set the environment variables, put them inside an .env file. Make sure the .env file is in the same directory as docker-compose.yml. When you run docker-compose up it will apply the variables set in the .env file. Nothing gets set if they're left blank.

Set the required COMMENTS_URL and EMAIL or you may run into problems. The best way to set these is by pacing them in the .env file. Here is an example:

COMMENTS_URL=comments.your.url EMAIL=you@your.url

Getting OAuth Key & Secret

Commento works with most popular OAuth providers. Thus visitors can leave comments without making an account.

The instructions are similar for each. I've outlined the steps for all of them below.

Twitter

1. Login to Twitter.com and apply for a developer account: https://developer.twitter.com/en/application/use-case

   

2. Describe how you'll use the API. You can use what I wrote.

   

3. Double check your entry and click Looks Good!

   

4. Agree to the terms of service.

   

   

5. They'll tell you to check your email for a confirmation. Confirm your email and you should be able to create your first app!

6. Once approved to to Get started click Create an app.

   

7. Next screen, again click Create an app

   

8. Enter all the appropriate details. For the callback URL, use https://<your URL>/api/oauth/github/callback where <your URL> is your Commento subdomain.

   

9. Finally, once you're done filling out the information to go the Keys and Tokens area. Save both the key and token. Enter them into the .env file. You can use COMMENTO_TWITTER_KEY and COMMENTO_TWITTER_SECRET

   

Gitlab

1. Login to Gitlab.com and go to to top right and click Settings

2. Then click on Applications

   

3. Enter a name for your app. I put Commento.

4. Set the Redirect URI to https://<your URL>/api/oauth/gitlab/callback

5. Select the read_user scope.

   

6. Click the green Save Application button

7. Copy the Application ID and Secret and place them in your .env file using COMMENTO_GITLAB_KEY and COMMENTO_GITLAB_SECRET

   

Github

1. To get your OAuth key and secret, you'll need to go to this URL: https://github.com/settings/developers

2. Once there, click on New OAuth App

   

3. Enter your details. For the callback URL, use https://<your URL>/api/oauth/github/callback where <your URL> is your Commento subdomain.

   

   Note: Make sure you include https in your URLs.

4. Grab the Client ID and Client secret and put that into your .env file using COMMENTO_GITHUB_KEY and COMMENTO_GITHUB_SECRET

   

Google

Setting up Google is just about as tedious to set up as Twitter. Despite how scary I just made it out to be, it's completely doable. Here are the steps.

1. Go to this URL: Google Developer Console

2. Create a new project

   

3. Click the GoogleAPIs logo in the top left corner to go back once you have a project. (Make sure the dropdown next to the GoogleAPIs logo is the same as your new project!)

4. Then, click Credentials on the left side.

5. Update the Application Name and Authorized Domains in the OAuth consent screen

   

6. Click Create credentials then OAuth client ID

   

7. On the Create OAuth client ID enter the subdomain associated with Commento to Authorized Javascript origins. Then, enter the full callback URL. For example https://comments.jaredwolff.com/api/oauth/google/callback. Make it yours by replacing comments.jaredwolff.com with your URL.

   

   Once entered, click the create button.

8. Grab the client ID and client secret

   

9. Update your .env file using COMMENTO_GOOGLE_KEY and COMMENTO_GOOGLE_SECRET

Install your application

You've entered your OAuth Credentials email, domain and SMTP credentials. It's time to wrap this show up!

1. Once you're done editing your .env file. Run docker-compose up (For files not named docker-compose.yml, use the -f flag. Example: docker-compose -f commento.yml up
2. Watch the output for errors. If it looks good you may want to kill it (CTRL+C) and run with the -d flag

3. On first start, Commento will prompt you with a login screen.

   

4. Create a new account by clicking Don't have an account yet? Sign up.

5. Enter your information and click Sign Up

6. Check your email and click the included link:

   

7. Log in with your freshly made account.

8. Then, click Add a New Domain.

   

9. Once created go to Installation Guide. Copy the snippet and place it where ever you want your comments to live. In my case, I put the snippet in an area just after my <article> tag.

   

10. Re-compile your site and check for success!

    

    Checkmark! Finally, I recommend you try logging in with each individual OAuth configuration. That way you know it working for your website visitors. ?

Alternatives

I spent a good chunk playing around with some of the alternatives. This is by no means a definitive guide on what will work best for your site. Here are some of the top ones as of this writing:

https://utteranc.es/#configuration

https://github.com/netlify/gotell

https://github.com/eduardoboucas/staticman

https://posativ.org/isso/

https://www.remarkbox.com

https://www.vis4.net/blog/2017/10/hello-schnack/

https://github.com/gka/schnack

There's also a huge thread over at the Hugo blog which has a ton more links and resources as well:

https://discourse.gohugo.io/t/alternative-to-disqus-needed-more-than-ever/5516

Conclusion

Congrats! You are now hosting your own comments server! ?

In this article you've learned how to harness the power of Docker and a Nginx Reverse Proxy. As an added bonus, you know how to set up OAuth credentials! That way future setup will be easy peasy.

By the way, this is only the tip of the iceberg. You can set up the same server for analytics, data collection and more. All the example code including code for other applications can be found here.

Finally, if you're looking pay for Commento head to www.commento.io and sign up for the service. You'll be supporting awesome open source software!

If you have comments and questions let's hear em'. Start the conversation down below. ???

Most of the times I try to learn something new and put it into practice, I quickly start to feel like I’m lost in a myriad of dance moves. I’m desperately trying to find the right way to do things, while not really understanding what’s going on or how I ended up on the wrong side of the room…

Just trying things out until something works.

Maybe it’s because of the way my learning process works, or maybe guides and tutorials are targeted at more experienced or technical people. But, after I’m done wrapping my head around the subject, I always feel like there should be an easy guide for understanding the key concepts and making it easier to apply them in a project.

So this time, I’ve decided to stop wishing for it and make it myself, using the last thing that I learned.

And that thing was OAuth 2.0.

What is OAuth?

Let’s start with the basics: OAuth stands for Open Authorization. It’s a process through which an application or website can access private user data from another website.

This other website usually works only as a trusted identity provider. It gives the requesting app some basic information about you so that the app can create a profile. This way, you don’t have to fill in a boring sign-up form and deal with yet another password ?

You’ve already used this at least a gazillion times, in fact you used it every time you clicked on “Log in with Facebook / Google / GitHub / …”. Next, you were shown a consent screen that displayed which information from your (let’s say) Facebook profile you’re allowing that-hot-new-app.com to read (and sometimes, write). After that, since that-hot-new-app.com trusts the identity provided by Facebook, they can create a profile for you on their database using the data that they received.

The communication between that-hot-new-app.com and Facebook usually ends here. This is why your profile picture won’t change all across the Internet if you change it on Facebook. They just never go back to Facebook and ask for updated data.

When marimba rhythms start to play…

There’s another purpose for building this kind of mechanism, one with way more potential: using the identity provider as a service provider (in an ongoing manner). This means communicating with it regularly to supply enhanced features for your users.

A nice example of this is Relive, a service that connects with different sports tracking apps to create Earth view videos of your run or ride. Every time you finish an activity, Relive prompts you offering to create a video from it. If you say yes, they’ll process it, and notify you when it’s ready for social media bragging… I mean sharing ?

There’s really no technical difference between these two usages. That’s why you should be cautious about where you log in with your social media or Google/Gmail account.

It might sound scary, but there's really nothing to fear. Just bear in mind that you’re authorizing that-hot-new-app.com to access that information about you that’s detailed in the consent screen, potentially on a recurrent basis. Be aware of the permissions you grant, and make sure you know how to disable them whenever you don’t feel trusting anymore.

For instance, if you are using your Google account for accessing that-hot-new-app.com but don’t want to allow that anymore, just go to your Google account settings and disable their access.

All the main identity providers offer control over this.

All right, but how do you dance the OAuth?

Before you land on that-hot-new-app.com and even click on “Log in with YourFavoriteIdentityProvider”, someone — probably a developer — has to create an application on the provider’s site.

This is a way of registering that-hot-new-app.com so that, later, the provider knows who’s asking for private data.

In this step, the developer will set up some information about the application, like the app's name or website and — most importantly — a redirect URI. The provider (like Google or Facebook) will use this to contact the requesting app and tell them that the user said yes ?

I promise you won't have to write it by hand, we pride ourselves on our paperlessness.

Once the app is registered, the provider will give that-hot-new-app.com a clientId and a clientSecret which will be used in the communications between them. They work sort of like a username and password for the application.

You'll get the clientID and clientSecret right after you click on Save application

It's very important that you keep your clientSecret in a secure location and don't share it with strangers. If someone gets access to it, they could request private user data from the provider on your behalf, and then use it for evil!

We don't want that.

Hands on waists or shoulders

Apart from setting up all those things, the developer has to find out what kind of data the provider gives access to, and how it’s segmented.

These “segments” are known as scopes and they define access rights, usually separated in read/write categories. So, for example, that-hot-new-app.com can request for “profile:read” and “contacts:read” scopes. This means they can read whatever the provider assigns to the “profile” and “contacts” segments. Other things won’t be accessible, for example your posts or what content you like.

Well, just to make things simple for now on, let’s say that that-hot-new-app.com is a website that integrates with Typeform, a service for creating beautiful and smart forms and also the company I work for. You definitely want in on the hottest thing right now, and quick, so on their website you click on “Log in with Typeform” to get right into the action. What’s next?

Here’s a home-made, organic, and cholesterol-free diagram to use as a map for the whole thing. It may look a bit complicated but don’t worry, we’ll examine each step up next.

Colorful notes bring joy to my heart

Authorize: the first step in the OAuth dance

So, you take the initiative and click on “Connect with Typeform”. Here, that-hot-new-app.com (THNA from now on, ’cause I’m getting tired of writing dash-separated words) will send you to Typeform’s authorize endpoint (/oauth/authorize) and provide:

• their clientId (remember, that’s THNA’s username)
• their desired scopes (or access rights)
• and their redirect URI again (Typeform already knows it from when we set up the whole thing, but we send it again as an extra layer of security)

That URL will look something like this:

https://api.typeform.com/oauth/authorize?client_id=yourClientId&scope=accounts:read+forms:read+results:read

Typeform will use this information to generate a consent screen where you can review what sort of things you’re authorizing THNA to see and do.

Once you have thoroughly read what you’re consenting to and happily click on “Allow”, Typeform will send you to the redirect URI with a temporary, like so:

https://that-hot-new-app.com/auth/redirect?code=xxxXXXxxxXXXxxx

Token: it takes 2 to tangOAuth ?

All this back and forth feels like someone’s taking you for a tango spin, right?

The second step of the OAuth dance is when THNA receives that code, and exchanges it for an OAuth Token.

So THNA takes that code and sends it back again to Typeform, along with the redirect URI (yes, again!), and the client secret (that’s the app’s password!).

As reward for a dance well danced, THNA will get a shiny OAuth Token ✨ which it can use to interact with Typeform on behalf of the user, that is… you!

Stay with me, sway with me

From now on, in every request THNA makes to Typeform on your behalf, they’ll have to include an Authorization header with that access token. With it, Typeform (or any other provider) can identify:

• who’s asking for the data (in this case, THNA)
• who’s the data about (you!)
• and also make sure they have the correct authorization to access that data (only what you consented to).

Ready for the dance floor ?

So now that you know all the steps and spins of the OAuth dancing technique you should be ready to create your own choreographies, I mean, integrations, and make the Internet an even greater place.

Drawings by yours truly, cover photo by Gez Xavier Mansfield on Unsplash.