OAuth

In the mid-2000s, as web services started connecting to each other, an awkward screen appeared everywhere. A service you had just joined would offer to find people you knew, and to do it, it asked you to type your email account's username and password right there. What the user meant to share was a contact list. What actually changed hands was the key to the entire mailbox.

There was no way to take it back, either. Decide you no longer wanted that service and the password was already sitting on its servers; the only way to cut the connection was to change the email password. Doing that broke the four other services you had given the same password to. If any one of them got breached, the rest opened along with it.

The root of the problem was that proving who you are and granting what someone may do had been collapsed into a single act. A password is a way of proving identity, so the moment you give it away, the recipient can do everything you can do. What was missing was a way to write down "let this service read only my contacts" in a form a machine could act on. OAuth is that form, standardized — drafted in 2007, with the 2.0 version in use today finalized in 2012.

It lets one service reach part of your data at another service without your password going anywhere. Four properties come with that.

1. Scoped permission — the grant says what may be done with it. The entries are called scopes and read like "read calendar," one line at a time. A grant that says read cannot delete an event.
2. Revocation — when the user clicks disconnect in their account settings, that one grant dies. Grants issued to other services keep working.
3. Expiry — grants carry a lifetime, often as short as an hour, after which a refresh token fetches a new one. A leaked value doesn't stay useful forever.
4. No password exposure — the service borrowing the permission never sees the password, so it has nothing to store and nothing to update when the user changes it.

The flow runs in four steps. Say Pagedeck is adding a feature that embeds Google Calendar events inside a document.

1. The user clicks connect calendar in Pagedeck, and the browser moves over to a Google page.
2. The user types their password on that page. Google is the one serving it, so Pagedeck can't see what was typed. The same page lists the permissions Pagedeck asked for.
3. On approval, Google sends a short authorization code back to Pagedeck's server. A code rather than a token comes first because the real key shouldn't ride through the browser's address bar.
4. Pagedeck's server trades that code, together with a secret only it knows, for an access token. From then on, every calendar request carries the token.

What travels here is the product of authorization. It is a different job from authentication, which establishes who is making the request. Handling login takes one more layer on top, a specification called OpenID Connect. Signing up with a Google account — social login — is exactly that combination.

Three alternatives exist, and which one fits depends on whose permissions are being borrowed.

The first is collecting and storing the user's password directly. It is the easiest thing to build. It also brings back every problem described above, and it stops working entirely once the other service turns on multi-factor authentication (MFA). The budgeting apps that used to scrape bank accounts worked this way; most have since moved to official integrations.

The second is an API key: the service issues one long string, and every request carries it. There's no screen where a person clicks approve, which suits automation running between servers. The trade is that one key usually carries every permission on the account, and with no expiry it stays valid until a human notices and revokes it. It fits places where only your server and theirs are involved, such as a payment processor integration.

The third is hanging authentication off the company's own account system. Instead of employees registering separately with ten internal tools, one corporate account gets them through, and closing that account on their last day closes everything attached. This only covers people inside your organization, though. An outside user lending you access to their own Google data is still OAuth's job.

"This isn't login, we're just borrowing permissions. Let's request two scopes and nothing more."

A warning that asking for more than you need makes users stop at the consent screen.

"If we store the refresh token in plain text, how is that different from holding their password?"

A refresh token with no expiry is effectively a long-lived key, so it belongs in encrypted storage.

"That account's connection dropped and sync stopped. I'll send them a prompt to approve it again."

The user revoked the grant, or the token aged out.

When Pagedeck first built the calendar integration, Theo cut the requested permission list twice. His first draft asked for write access to events and the attendee list, when all the feature needed was the title and the time. With the shorter list, noticeably fewer people backed out at the consent screen. The consent screen is the last place a user can change their mind, so the wording that appears there moves the completion rate as much as the feature itself does.

The most common misreading is treating it as a kind of login. Sign in with Google sits on top of this standard, so it looks that way. What the standard defines is the procedure for lending and returning permissions; nothing in it reports who the user is. Build without that distinction and you end up with code that lets someone in because their token is valid, which opens a path where a token issued for a different service gets pasted in to reach someone else's account. When identity matters, add OpenID Connect and verify the separate identity token it issues.

The other one is assuming that a grant, once collected, means permanent access to the user's data. Tokens can be revoked at any moment, and providers sometimes retire a scope outright. Design around the integration as if it were your own database and a feature goes dark the day it disconnects. Decide what the screen shows in that state at the same time you build the connection.