OAuth2 (and brief OIDC) Overview
February 22, 2023
Background
OAuth allows you to give a third party fine grained access to your resources (via access tokens) without granting them full ownership like you would if you gave them login credentials.
Example Cases
You have probably ran into OAuth many times in the real world. Does the following sound familiar? You are scheduling a doctor’s appointment at the doctor’s office. The site confirms your appointment and asks if you want to add this appointment to your Google Calendar. When you click Yes, you are redirected to Google, where it (Google) asks you if the doctor’s site can have permission to your Google Calendar. You say yes and now the appointment appears on your Google Calendar.
This is oauth, you did not give the doctor’s site your Google credentials, but you did authorize it to have (temporary) access to your Google Calendar and only your Google Calendar. Also only after you consented, it was able to add the appointment. The doctor’s site did not get access to Gmail, GDrive, or any of your other Google services.
Another example, you go to a store to print some photos (like Staples or Walgreens). The store’s machine has an option to print photos from your Google Drive. You choose the Google Drive option, and then are redirected to Google to login and give consent to your photos being accessed. You agree, then you find your photos and print them.
Overview
oAuth Terms
Client
The third party application that is requesting access to your data. They will make a request to access your data with certain permissions.
- This would be the doctor’s website that is trying to schedule your appointment.
Resource
The data that needs to be accessed.
- This would be time slots on Google Calendar.
Resource Owner
You, the owner of the data and who decides to give or deny access.
Resource Server
The server or api that hosts the data.
- This would be Google Calendar.
Authorization Server
The server that issues and validates access tokens according to the oauth spec.
- Google’s Authorization Server that handles access tokens for its Google Services (Calendar, Drive, etc..).
Scopes
A way to ask for segmented permissions on the third party system (via the access token).
- Example: download file permission (would not have upload, delete, etc..)
First Step in OAuth - Registering OAuth App
The very first step for the application developer (the third party), is to register an OAuth app on the service which will give back a client id (and potentially client secret) for identifying the app. In the example above, the doctor’s site would need to register an OAuth App with Google. You will have to find the OAuth app registration instructions for the service you want to integrate with.
OAuth Flows
Once you have registered an OAuth app, you can implement an authorization flow (process for user to give access to your app) in your application. I’ll only go over the most common flow below, and briefly note differences with other flows. The flow chosen corresponds with the application type (website, mobile, smart tv, etc..).
Authorization Code Flow - Custom Frontend + Backend Option
- User clicks in doctor’s site to connect their Google Calendar.
- Frontend redirects to Google Authorization Server to bring up user consent page.
- Would look something like: “Would you like to give Doctor’s site access to your Google Calendar?“. The user would also decide what permissions they will give (ex: add appointment).
- The frontend passes the client id in this redirection.
- Once consent is given, the authorization server redirects the user back to the frontend via the desired redirect URI and passes the auth code in a query param.
- Valid redirect URIs are registered during the OAuth App creation.
- The authorization server only gives back an authorization code, not an access token because sending back data through the browser url is not secure. The authorization code will be exchanged for an access token soon.
- The frontend then calls its own backend with the authorization code so that the backend can request an access token.
- The backend has the client secret stored safely (considered back channel) and so it will use the authorization code and client secret to request an access token from Google’s authorization server.
- If someone had stolen the auth code from the browser: They could pass the auth code and client id to the authorization server to try to get the access token, but it would fail because the hacker would not have the client secret for that id so the authorization server would reject the request. Also they cannot do anything with the auth code by itself, since it does not give access in any way.
- Once the authorization server verifies the auth code, client id and secret, it then issues an access token (and optionally refresh token) to the backend.
- This access token does have permission to access Google’s API now (ex: Google Calendar), but only has the scopes (permissions) that the user granted to the doctor’s site.
- The backend can now go ahead and use the access token to retrieve the data or execute the operations (add appointment to Calendar) it needs. It can also store the access and refresh tokens if it desires (thought needs to go into how to safely store the tokens, i.e encrypting in database).
Note on PKCE: The Authorization Code Flow (explained above) should be used with PKCE. I will only summarize the PKCE additions since I wanted to focus on a conceptual understanding of the auth code flow. With PKCE the only changes are the following two things. 1) The frontend generates a random secret, called the pkce code verifier, at the time of authorization server redirection, and passes a hashed value of that to the authorization server along with the usual params (client id, etc..). 2) When the backend calls the authorization server to get an access token, it will have to pass the plain text pkce code along with the usual params (client id, secret, auth code, etc..). If the pkce code verifier does not match, the auth server will reject the token request.
Note on SPAs: The flow is pretty much the same except that there is no client secret. Since SPAs (Single Page Applications) do not have a safe place to store client secrets, one is not issued and is not used in the flow. PKCE provides the protection needed. No very safe way to store access tokens for SPAs, would recommend either adding a backend or not storing access tokens at all.
Note on Mobile Apps: Similar to SPAs. The flow is pretty much the same except that there is no client secret. PKCE provides the protection needed. Storing access tokens can be done in phone secure storage (if available on device).
OIDC
OAuth is good for authorizing services, that is, giving them permission to do something on your behalf. It is not meant for authenicating users, that is figuring out who the user is. That is where OIDC (OpenID Connect) comes in.
OIDC is a wrapper around OAuth with the goal of figuring out who the user is, identifying them (name, email, and some id I can store in my database). OIDC is what you are using when you log into the doctor’s site with “Sign In With Google”. It is OAuth where the resource is your user information. Since you may have already given your user information with sites like Google and Facebook, applications can request your user information there instead of having you register a separate username/password with their own service. Everytime you use “Sign In With Google”, the application will get the same “ID” from Google/Facebook that represents who you are in their system. It frees the application developer from having to handle user authenication and password security, and saves you the hassle of having to create accounts (and passwords) for every service you use.
More Reading: