{"canonical_url":"https://engineer.company/glossary/oauth/","content_markdown":"# OAuth\n\n## What it is\n\nOAuth is a protocol that lets one application use a person's data held by\nanother service, with that person's approval and within limits they can see,\nwithout the application ever learning the person's password. The version in use\nis OAuth 2.0, published by the IETF in October 2012 as RFC 6749, and you will\nsee it written OAuth 2.0 and OAuth2 as often as plain OAuth. It replaced OAuth\n1.0, and the two are not compatible.\n\nThe specification names four roles. The resource owner is whoever can grant\naccess, usually a person. The resource server holds the protected data and\nanswers requests that carry a token. The client is the application that wants\naccess: a web app, a phone app, a script, an AI agent. The authorization server\nsigns the owner in, asks for their consent and issues tokens. A small product\nmay run the resource server and authorization server as one system; a company more often has one identity\nprovider in front of many APIs.\n\nWhat the client receives is an access token, a string that stands for a\nparticular scope and lifetime of access. It sends the token with every request\nto the resource server. The RFC calls the string usually opaque to the client:\nthe client carries it but is not meant to read it. The authorization server may\nalso hand out a refresh token, which the client trades for a new access token\nwhen the old one expires, without asking the person again.\n\nA client gets its first token through a grant. RFC 6749 defines four:\nauthorization code, implicit, resource owner password credentials and client\ncredentials. Client credentials is for a program acting on its own behalf, with\nno person involved. The authorization code grant is the one that matters for\neverything else, because current security guidance has retired the implicit and\npassword grants. That guidance, together with Proof Key for Code Exchange\n(PKCE) and bearer token rules, is being folded into a single OAuth 2.1 document\nat the IETF. In its sixteenth draft, dated 3 September 2026, it is still an\nInternet-Draft, a work in progress and not a standard.\n\nOAuth is about authorization, not authentication. A token tells the API what\nthe client may do; it says nothing reliable to the client about who the person\nis. Signing people in on top of OAuth is the job of OpenID Connect, which adds a\ntoken meant for the client to read.\n\n## Why it matters\n\nRFC 6749 opens with the problem it was written to end. To let a third-party\napplication reach your data, you gave it your password. The application then had\nto store that password, typically in clear text. It could reach everything the\npassword could reach, for as long as it liked. You could only cut off one\napplication by changing the password, which cut off every other one too. And\nwhen any of them was breached, the password and everything behind it went with\nit. OAuth removes each of those: the application never holds the password, the\ntoken carries a scope and an expiry, and access can be withdrawn from one client\nwithout touching the rest.\n\nA team meets OAuth from both sides. When you own an API, OAuth lets partners,\nintegrations and customers' own tools call it on a user's behalf without anyone\nstoring anyone else's password. When you consume one, OAuth is what calendars,\nmailboxes, accounting systems and file stores offer, so the client half is code\nyour team writes and keeps alive. AI agents that act for a person sit in the\nsame seat as any other client: they should hold a token limited to what that\nperson allowed, never the person's credentials.\n\nScopes turn least privilege into something a server can enforce. A token that\nlets a printing service read photos should not let it delete them, and a token\nissued for one API should be refused by another. The IETF's 2025 security\nguidance, RFC 9700, asks for exactly that: an access token's privileges kept to\nthe minimum the use case needs, and tokens restricted to the resource server\nthey were issued for.\n\n## What it looks like in practice\n\nThe RFC's own illustration is a printing service that wants photos from a\nphoto-sharing site. Here is that exchange as the authorization code grant with\nPKCE, the shape current guidance asks every client to use. Before anything else,\nthe client makes up a random code verifier of 43 to 128 characters and keeps it\nto itself. It hashes the verifier with SHA-256 and sends the base64url-encoded\nresult, the code challenge, along with the person's browser to the\nauthorization server:\n\n```http\nGET /authorize?response_type=code\u0026client_id=s6BhdRkqt3\u0026state=xyz\n    \u0026redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb\n    \u0026code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM\n    \u0026code_challenge_method=S256 HTTP/1.1\nHost: server.example.com\n```\n\nThe authorization server signs the person in, shows what the printing service\nis asking for and, once they approve, sends the browser back with a short-lived\nauthorization code. The client checks that `state` is the value it sent:\n\n```http\nHTTP/1.1 302 Found\nLocation: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA\n          \u0026state=xyz\n```\n\nThe code is worth nothing on its own. The client redeems it with an HTTPS\nrequest to the authorization server's token endpoint, and this time sends the\nverifier itself:\n\n```http\nPOST /token HTTP/1.1\nHost: server.example.com\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=authorization_code\u0026code=SplxlOBeZQQYbYS6WxSbIA\n\u0026redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb\n\u0026client_id=s6BhdRkqt3\n\u0026code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\n```\n\nThe server hashes the verifier, compares it with the challenge it stored next\nto the code, and only on a match returns the tokens, marked so that no cache\nkeeps them:\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json;charset=UTF-8\nCache-Control: no-store\nPragma: no-cache\n\n{\n  \"access_token\":\"2YotnFZFEjr1zCsicMWpAA\",\n  \"token_type\":\"Bearer\",\n  \"expires_in\":3600,\n  \"refresh_token\":\"tGzv3JOkF0XG5Qx2TlKWIA\"\n}\n```\n\nFrom here the client sends `Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA` with\neach call to the photo API. An hour later the token has expired, the API answers\n`401 Unauthorized` with `error=\"invalid_token\"` in its `WWW-Authenticate`\nheader, and the client spends the refresh token on a new one. Asking for\nsomething outside the granted scope earns `403 Forbidden` and\n`insufficient_scope` instead. The verifier protects against code interception: a\ncode copied off the device in transit, the attack PKCE was first written\nagainst, cannot be redeemed by anyone who lacks the verifier, and the verifier\nitself was not sent in the authorization request or the browser redirect.\n\nThe same delegation is what lets software take part in agent workflows. On this\nsite's page about\n[turning existing business software into tools AI agents can call](/ai-tools/),\nOAuth provides the delegated access: an agent acts for a user without a password\nchanging hands, and only within that user's rights.\n\n## Where it goes wrong\n\n**A loose redirect check sends the code to someone else.** An authorization\nserver that accepts any redirect URI starting with a registered prefix, or one\nmatched by a wildcard, can be talked into delivering a code to a page the\nattacker controls. RFC 9700 requires authorization servers to compare redirect\nURIs with exact string matching against the registered ones, with one exception\nfor port numbers on localhost for native apps, and forbids clients and servers\nalike from running open redirectors that forward the browser to any URL found\nin a query parameter.\n\n**The callback accepts a response nobody asked for.** If the client takes\nwhatever code arrives at its redirect URI, an attacker can push their own code\nthrough a victim's browser, and the victim ends up working in the attacker's\naccount. This is cross-site request forgery aimed at the redirect. A client may\nrely on PKCE for protection once it has confirmed the server supports PKCE;\notherwise it sends a one-time `state` value bound to the person's browser\nsession and rejects a response that does not carry it back.\n\n**Tokens travel in URLs.** The implicit grant puts the access token straight\ninto the redirect, where browser history and `Referer` headers can carry it to\nplaces it was never meant to go, and nothing binds it to the client that asked\nfor it. RFC 9700 says clients should not use it, and the OAuth 2.1 draft leaves\nit out. The same applies to an API that accepts a token as a query parameter:\nRFC 6750 says page URLs should never carry bearer tokens. Use the code grant and\nsend tokens in the `Authorization` header.\n\n**The app asks for the password anyway.** The resource owner password\ncredentials grant lets a client collect a person's username and password and\nswap them for a token, which defeats the reason OAuth exists. RFC 9700 states\nthat it must not be used: it exposes the credentials to the client, trains\npeople to type their password into places other than the authorization server,\nand was never designed to work with two-factor authentication or sign-ins that\ntake several steps. Send people to the authorization server with the code\ngrant, and use client credentials when no person is involved at all.\n\n**A stolen token works for whoever holds it.** RFC 6750 defines a bearer token\nas one that any party in possession of it can use: holding it is the whole\nproof. Keep\naccess tokens short-lived, restrict each to the API it was issued for, and where\nthe stakes justify it, bind tokens to the client with mutual TLS (RFC 8705) or\nDPoP (RFC 9449). Refresh tokens for public clients, such as phone and browser\napps, must be either bound to the client or rotated: each refresh returns a new\ntoken and invalidates the old one. If a stolen copy is used too, one side ends\nup presenting an invalidated token, the server revokes the active one, and the\nattack stops at the price of sending the real client back to the person for a\nfresh grant.\n\n## Further reading\n\n- [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)\n  — the four roles, the four grant types and the endpoints, as published in\n  October 2012.\n- [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)\n  — the code verifier and challenge, with the S256 example used above.\n- [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://www.rfc-editor.org/rfc/rfc9700)\n  — the January 2025 guidance: exact redirect matching, PKCE for every client,\n  and no implicit or password grant.\n- [RFC 6750: Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750) — how a\n  client presents an access token and how an API says it is missing, expired or\n  too narrow.\n- [The OAuth 2.1 Authorization Framework](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/)\n  — the working group draft that folds these documents into one, still an\n  Internet-Draft in October 2026.\n\n\u003chttps://engineer.company/glossary/oauth/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How OAuth lets an app act for a user without the password: the four roles, a code exchange with PKCE step by step, and five ways a deployment leaks.","formats":{"gemtext":"https://engineer.company/glossary/oauth/index.gmi","gopher":"https://engineer.company/glossary/oauth/gophermap","html":"https://engineer.company/glossary/oauth/","json":"https://engineer.company/glossary/oauth/index.json","markdown":"https://engineer.company/glossary/oauth/index.md","pdf":"https://engineer.company/glossary/oauth/index.pdf"},"kind":"page","language":"en","title":"What is OAuth?","url":"https://engineer.company/glossary/oauth/","version":1}