oAuth APIs Explained

key.

Welcome to Syntax.

In this episode, we're gonna be talking about OAuth.

What is OAuth, why you should know about it, and you've probably seen it around. You've most definitely have used it before whether you know that or not And how you can really understand that the finer points of why you should, pick up OAuth or why you should use it or how you should use it. The main concept is big bullet points. My name is Scott Tillinski. I'm a developer.

With me, as always, is Wes Boss. Wes,

What's up? I got my old face on today, excited to talk about the o auth. Did you you're riding the Ola Coaster? The

That's, like, my favorite movie, by the way. I I, I used to What was that? This office space? Office space. Yeah. Yeah. I I had it on VHS, and I used to watch it maybe every single week. I I could probably

recite to you the entire movie from from the start. It's Love a brilliant it's one of the very few movies that I would just watch over and over and over again. It's just like references

And society is so good. I, yeah, I I I couldn't tell you why, but, like, just 2 days ago, I had it in my head. It was like, that part where he's like, hey, Peter. I don't want you messing up my life too. It's like obviously, it doesn't say messing up, but, for some reason, that was in my head. I was like, man, this Comic gold is hilarious.

If you have not seen Office Space, go see Office Space and you can, get your own face as well. O OAuth.

Wes.

Yes.

Is it auth? It's not just o's. It's auth as well, and it's basically the way that you can authenticate for your website using another services authentication service.

That's like the big thing. You want to log in with GitHub on some place. You want to log in with Google on some place, OAuth.

Yeah. It's a standard for accessing someone else's API via authenticating into their services.

Exactly. It's most commonly used for 2 things logging in with something. Log in with Twitter, log in with GitHub, and also being able to access content on behalf of somebody else's account. So if I wanted to have access to your Git repos or like I'm specifically doing this one because I was doing my taxes, and I want to I have a bunch of scripts that. I use to automatically categorize a lot of my expenses, as well as automatically detect if an expense has HST, which is our local tax. Not all of my expenses do. So I have to, like, go through everyone and check the box, and it's annoying. Your own scripts for this? Well, Like, how it doesn't like, how would it know if there's HST or not? Because it's just it imports them from my credit card, and it says I spent This much money on x, y, and z, but that's as far as it knows as to who it is. It doesn't have the receipt coming off of my credit card. Right? So I know that there's specific expenses that do have HST. Like, I can search for Fido or tech savvy.

The phone bill and Internet. Those things have HST, right? So I want to automatically apply or also categorizing them. Right. Like it does a pretty good job at categorizing them. But, like, there's that last 10%. You want to make sure it's proper, so you still have to go through them all. So I basically said, well, look, I know what all my expenses are.

Would it be nice I wrote a bunch of scripts to go through it, and I actually just wrote them and paste them into the the terminal or into the console, and and it did it for me. But I was like, you know what? I got to do this through their API. So I set up FreshBooks, and I'm making an app that will access somebody else's account. It's mine, but it could be anyone's on their behalf. So if you're writing an application that needs to access data from another service on behalf of the person who has logged in to your service.

That is generally what OAuth is used for. Tokens. It's pretty complicated and people get really frustrated at it because there's probably between 4 7 different types of tokens.

And it's it's a long ways away from the simple world of here's the API key, and you can go go. That said it is ultimately way more simple than rolling your own off, which,

I have a course on, and I've done several times myself. So, you know, I I'm I'm no I'm no, you know, spring chicken when it comes to auth. And and, honestly, when you when you go from writing your own auth to using OAuth, it it does feel like magic or it feels like very simple. So, if you're out there and you're struggling with it, just know that it is saving your bacon in a lot of ways because you're not having to Compare a lot of hashes yourself. You're not having to do any encoding or any, any any of those lovely things that you have to do

Node and crypto wallet stuff. All right, so we're going to go through all of the big names of words here. We've got client ID, we We got client secret, we got callback URL, we have authorization code, we have access token, refresh token and state.

So let's start with the first 2, client ID and client secret. These are essentially the username and passwords for your application. So when you are going to use let's let's use

GitHub as an app. GitHub. It's the one everybody uses, especially Exactly. You're you're logging in to Netlify or to Vercel or someplace. Exactly. Always.

You're signing in with GitHub and

then Vercel now has access to the repos that you've told that you have access to. Exactly. So we're going to use GitHub as an example here. But this obviously works with everything or almost every not almost every API, but most APIs out there are OAuth based.

So you when you want to make an application, you have to go and sign up for an application on that service. You go to GitHub, you go to apps, say create a new application.

You call it Scott's Cool GitHub Helper.

And then they will give you 2 things, a client ID that's in a public identifier of your application, And they will give you a client secret. And this is essentially the password to your application so that you can use it. So this doesn't give you access to anybody's repos, including your own. Yet it just gives you the ability to request access to those specific

repos or to that person's application. Yep. And and and then, basically, what all of this is doing is it's kind of putting some of these permission based things in the hands of the service. So GitHub has control over the permissions. What what the application is able to see from GitHub. GitHub has control over it, and they can use their own interface to say, what do you approve this service of of using or seeing, at this given time, giving the user full control and, you know, to say, hey. Look at this stuff, but maybe don't look at this stuff. Here's the things that you need to be able to see to access the the stuff that I want you to see, whether that's deploying an app with my repos or whether it's just simply

accessing the service. So once you have your client ID, what you do is when you have a button that says Log in with GitHub or like, yeah, you want to log into my application, but you have to use your GitHub account so we can get access to your stuff.

You send them to a specific URL on GitHub and you pass along the client ID, again, your application, as well as often there's a list of permissions that you are requesting.

Are you requesting read and write access to absolutely everything, or are you accessing the ability just to see public info? Or do you want to be able to read stuff, but not delete stuff. Should you be able to edit stuff? And every single application will have its own set of permissions, and you have to specifically ask what permissions you want. Sometimes you set those permissions at an application level.

And sometimes you set those on a per person level. It depends on the specific application and that URL will then give the person you send them to the actual application. This is not on your server anymore. Now they're on GitHub and they say allow.

They click on whatever.

And what will happen is that when you register your application with GitHub, you give them what's called a callback URL, which is here is the URL that you should send the person back to with something that's called an authorization code once you've done it. So you authenticate with GitHub.

GitHub will say, okay, looks good.

I generated an authorization code and now I'm sending you back to the original URL of your application.

And in the URL query param, there will often be an ampersand code equals,

and it's a long hash that goes inside of there. Mhmm. And and just so, people are aware too, This is something that needs to be dynamically set probably from an ENV variable. Right? The callback URL because localhost.

You know, you're you're calling back to a local host. So you need to be kind of aware that maybe this isn't something you should hard code. Yeah, the the callback URL

is you generally pass it along with the request.

But when you register your application, You have to give it a list of allowed callback URLs.

And this is a use case where you often have to bring Cloud for Tunnel or ngrok or any of the stuff we talked about in that last episode because sometimes they'll allow local hosts Often they won't.

But a way around that is you can just you can just give it a URL.

And it will just return to you a fake URL and it will be a broken page. And then you can just copy the code out of the URL bar

internally. Yeah. But there's there's better ways. Now go back to listen to our episode on local tunnels and stuff we wanna hear about that. And it's the same type of flow that you end up having with any kind of webhook. Right? Anytime anytime a web service is sending information to your computer specifically for a function, You probably wanna be using Ingramrock or any of those types of deals. So, this this is no different.

So now that you have your authorization code, You that's still not access to your users' information. That is simply just the ability to Get access to the access to the information.

So you then take that authorization code, and you take your client ID, which we already had, And you take your client's secret. This is the 1st time we're talking about the secret. So basically, you're taking your username, your password, and the specific authorization code for that user, and you send those 3 things back to your service GitHub, and then they send you back. Finally, if all of those things are good, they will send you back what's called an access token.

And the access token is you can see that as your final API key key that will give you access to your users' information.

Mhmm. And then you could simply use that token in your requests to access the information just like you would almost any other API. Right? This slot and honestly reminds me a lot of, like, payment flow APIs where you're, like, having to get an approval, and then, okay, you take that approval, and then you use that approval to then gain the token that says, alright. I now have access to this thing. I'm ready to go, and I can then use that token.

And in addition to that, there's the whole refresh token business.

So the idea of a refresh token is that the authorization, token or the access token is is not necessarily long living, but the refresh token can be. So the refresh token lives longer and then will generate you essentially a new token to set refresh the access to this login without having the user be having to relog in every time. I don't know I don't know if a lot of you remember, but there was a period in the web where, like, you were having to log in to services almost every single time you. Mhmm. Arrived at them and and then places got better about that about having longer lasting tokens. But the the refresh token basically will allow you to maintain access Without having to grant, new access via relogging in every single time you visit the site even after that, token has, reached its limit in terms of length and how long it's alive. Yeah. And

how long those tokens are good for depends on the service.

And when you when you get that access token back in that last step, they'll often also give you an expiry.

If they don't give you an expiry, you can just write some code that will say you can write a function that says get access token or or generate new access token. And basically what that will do is it will try the token. If it's not good, then it will just go take the refresh token and get a new one. And you save that access token as well as your refresh token and your expiry. You save all 3 of those things in your database, and they should never, ever be sent to the client. They should never be in the browser because that is essentially your user's password. Right? That's this is actually how,

Linus Tech Tips got hacked. Did you see that the other day? Yeah. I did see that. So they They were he clicked a link or some not he, but somebody on their team clicked a link that was a PDF in an email and that stole their access and refresh token, I believe.

But yeah. So so now when somebody has access to those tokens, they don't actually have access to your password. So it's not like they could reverse your password out of that because they are it's a one way hash. But the same regard, they if you have those tokens, you can get into the service. You don't need the password to get into the service if you can get those tokens with your request.

So if anybody has those tokens, those those tokens are essentially the key to the kingdom. So it's not like they could say, oh, I have access to all your passwords, but now they essentially have access to the key to your house. You can have 2 factor auth set up,

and often you'll need to put in your 2 factor auth to generate an access token.

But as soon as somebody has that access token, yeah, that's the key, you're pooched. That's it. That's a single key to be able to get access to all of your users' information. And that's why they expire so often is because maybe they're only good for 8 hours. And if a database leak gets out or something like that, all of those access tokens will be stale.

Again, I guess if they have the refresh token, they could know if they have the refresh token, they still can't get a new version unless they also had your client secret. And hopefully, you don't have those 2 things in in the same place as well. But The way that the Linus Tech Tips things happen is that somebody was just logged in and they you have an access token that's sitting in like a cookie somewhere in your browser. And they basically just took all of the cookies from the Chrome application folder and just copy paste. Put it on. I did it with my sister's bookmarks the other day. She's like, she called me up and she's like, my bookmarks are gone. Like I just something happened and everything in Chrome is gone. So I just like I went into her like application folders and found like there's 2 Chrome profiles.

Oh, and I just copied the one that had more stuff into the new one and rebooted the thing and all of her bookmarks were back. And I'm assuming that also

Had all of her access tokens and whatnot in there. And this is an important point too because if somebody has access to your local file system, these things have to be stored somewhere. Right? Yeah. They're stored in your local computer. So somebody has access to that. They can have access to a whole lot of stuff.

Like, whereas these HTTP only cookies. They can't get them through the network because they're not sent on the request unless, you're explicitly making it, being sent, or being told from the origin. So, if somebody has access to your local system, your local file system, that can be a big problem. You know, one thing that,

What is it? Raycast does? Is Raycast stores all of their settings and everything in a SQLite database that is Yeah.

We talked to them about this. Yeah. Because I was like Yeah. I tried to, like, get access to everything in Metascula, and that can get access to any of it. Right? And obviously, they can decrypt it somehow because they have whatever the keys are. But if some me having access to my entire computer could not get access to it. So there is I guess there is ways to do that type of thing as well. It depends on how secure you need to be. But yeah. Yeah. Last thing we have here is something called state. This is not something I see a whole bot, but it is something specifically Google. I have seen this one in the Google APIs.

And what this is, is it's another piece of it's another token that is generated before your request, and it will allow you to ensure that the same Device or application that is making the request is also the one that is getting the token back. So basically you say, okay, here I am, the application. All right, I'm going to make a random token. Dogs are cool.

And then you send that. You hash that token, send it to Google, and then Google comes back and says, all right, well, here's here's your code to get your access token.

But also, here's the state that you made up.

If the person receiving the code To generate the authorization code is not the same device, then they will have no memory of that because They're saying to store the state in just like memory or local storage or something like that. So it's assuming that it's making sure that the device that requested it is also the device that is getting it. It's just another step to prevent against different attacks in OAuth. Yeah.

So that is OAuth. Hopefully, it explains. I know a lot of people who's grown when you hear OAuth, and sometimes I get really excited about using an API. And then I'm just like, oh, my goodness. Like, freaking all these different steps and whatnot. And if that is the case, I know Scott was laughing at the fact that if you don't want to set up an entire web browser because I was just writing node scripts.

I don't have a user facing URL.

What you can do is when you want to get access to that token, you just console log the URL, you click it and you log in and it will send you back to your callback URL, which is essentially a broken local host URL.

You can literally just copy the that code out of there, Put it into a variable or put it into don't put it in a variable, actually. Put it put it in your .env file, and then you can use that token for as long as as you want, especially when you have the refresh token. So if you're just doing it once for a simple script, Obviously, this is not going to work for users who need to log in with your application, but if you just need to use OAuth because I want to access my own data via some company's API. That's actually, I think, a pretty good use case for it. Totally. But I I will think that 9 90% of the people doing this are gonna be doing in the context of a website, though. So,

maybe important to know. But, yeah, I I mean, I totally agree that you could do it that way as well if you're, You're an elite hacker, and you want to just write some scripts here. I should say all of this beats writing your own auth from scratch. So if it feels like there's a lot of steps here, you're you're writing 1 file instead of 10 files, so it's a it's a little bit easier. And and it's a standard. Like, you don't have to

figure out, Okay, how does this obtuse API work with Yahoo! And then how does it work with Google? And how is it? OAuth is generally the same flow that we talked about. The only thing that really differs is how you send the authorization code in your request. Sometimes it's a bearer token that gets sent via header. Sometimes it's a query param over a URL. It really depends on the specific application.

So you just have

to look at the docs for that. But 90% of it is standard across all OAuth APIs. Yeah. And if you see, if you see that whole bear auth thing, just know that it's a different different strategy for doing the same thing. You're just sending the the token along in part of your request. Sometimes people see that bear auth thing and think it's like a whole whole, can of worms in itself, but it it's really just a different process of sending that token to Yeah. The request.

Just a header. No different than when you say accept content application JSON.

Yeah. You just have another header that says, bearer or no authorization header. The header is like authorization

bears.

Yeah. You got it. Yeah.

Oh, yeah. That's it. Hopefully you enjoyed that. Let us know what you think And, catch you later. Peace. Peace.

Head on over to syntax.fm

for a full archive of all of our shows. And don't forget to subscribe in your podcast player or drop a review if you like this show.