TodayTools

OAuth 2.0 with OpenID Connect

How OAuth 2.0 works

Sign in with another account, safely

Donate
L7ApplicationPort 443TCP
What brings you here?

Watch it happen

How much detail

Sign in with another account: authorization code flow with PKCE, an OpenID Connect ID token, then an API call.

Leo's browser
Photo print app
Sign-in server
Photo API
InternetRequestResponseLookupEncrypted

6 steps, 14 packets

First up: Send to sign-in. Press Play to watch it happen, one step at a time.

0 of 60/6

What is OAuth 2.0?

OAuth 2.0 lets one app use your account on another service without ever seeing your password. You sign in on the account provider's own page, agree to what the app may do, and the app receives a limited, short-lived access token instead.

OpenID Connect adds a signed ID token on top, so the app also learns who you are. Together they power every Sign in with... button. The safe modern pattern is the authorization code flow with PKCE, which makes a stolen code worthless.

Think of it like this. OAuth is like a hotel valet key. You do not hand over your house keys; the front desk (the sign-in server) gives the valet (the app) a key that only starts the car, only for tonight, and that you can cancel at any time. The ID token is the desk's signed note saying who the car belongs to.

Step by step

Normal

6 steps

Sign in with another account: authorization code flow with PKCE, an OpenID Connect ID token, then an API call.

  1. 1

    Send to sign-in

    Redirect with PKCE and state

    The app makes a random secret (the code verifier) and keeps it. It sends the browser to the sign-in server with the SHA-256 of that secret (the code challenge), a random state and a nonce.

  2. 2

    Sign in and agree

    On the sign-in server's page

    Leo types his password, or uses a passkey, only on the sign-in server. He sees what the app wants and agrees. The browser comes back to the app with a one-time code.

  3. 3

    Callback

    The app checks state

    The app checks that state matches the one it sent. Then it swaps the code for tokens over a direct back-channel call, not through the browser.

  4. 4

    Token exchange

    Code plus verifier

    The app sends the code and the original verifier. The sign-in server hashes the verifier and compares it with the challenge from step one. Only the app that started the flow can pass. Back come an access token, a refresh token and an ID token.

  5. 5

    Check the ID token

    Who signed in

    The ID token is a signed JWT. The app checks the signature with the server's published keys, then iss, aud, exp and that nonce matches. Now it knows this is Leo.

  6. 6

    Call the API

    Bearer access token

    The app calls the photo API with the access token. The API checks it and that the scope includes photos.read. The app never learned Leo's password and cannot do more than he allowed.

Stolen code

3 steps

A rogue app grabs the one-time code, but without the PKCE verifier the sign-in server refuses it.

  1. 1

    Normal sign-in

    The code comes back in a redirect

    Leo signs in as usual. The code travels back to the app inside a redirect URL.

  2. 2

    Code leaks

    A rogue app sees the redirect

    On phones, another app can register the same redirect address and catch the code. Codes can also leak through logs or browser history.

  3. 3

    Exchange refused

    invalid_grant

    The rogue app sends the code to the token endpoint, but it does not have the code verifier, which never left the real app. The hash check fails and the server answers invalid_grant. Many servers also cancel the code after a failed try.

Token expired

3 steps

An hour later the access token has expired, so the app quietly gets a new one with its refresh token.

  1. 1

    API says no

    401 invalid_token

    Access tokens are short-lived on purpose, here one hour. After that the API answers 401 with a WWW-Authenticate header that says why.

  2. 2

    Refresh

    grant_type=refresh_token

    The app sends its refresh token to the token endpoint. It gets a new access token and, with rotation, a new refresh token too, so a stolen old one stops working.

  3. 3

    Try again

    200 OK

    The app repeats the API call with the new token. Leo notices nothing.

Myths and mix-ups

  • OAuth 2.0 on its own is for permission, not login; OpenID Connect adds the who-are-you part.
  • The app never sees your password; you type it only on the sign-in server's page.
  • An access token is not proof of identity for the app; the ID token is.
  • PKCE is not only for phone apps; current best practice uses it for every client.
  • The old implicit flow, which put tokens in the URL, is no longer recommended.

Try it yourself

Run these on your own computer to see OAuth 2.0 at work.

  • Make a PKCE pair

    v=$(openssl rand -base64 48 | tr -d '=+/\n'); echo "verifier: $v"; printf %s "$v" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '='

    Prints a random verifier and its S256 challenge, exactly as an app makes them.

  • Read a provider's settings

    curl -s https://YOUR-SIGN-IN-SERVER/.well-known/openid-configuration

    Every OpenID Connect provider publishes its authorize, token and keys addresses here.

  • Watch a sign-in

    F12, then Network, tick Preserve log, then click a Sign in with button

    Find the authorize request: look for response_type=code, state and code_challenge in the address.

OAuth 2.0 at a glance

Layer
Application (7)
Port
443 (always over HTTPS)
Transport
HTTPS redirects and back-channel calls
Recommended flow
Authorization code with PKCE
Tokens
Access, refresh and (OpenID Connect) ID token
Token format
Often a signed JWT, or an opaque string
OAuth 2.0
RFC 6749 (2012)
OpenID Connect
Core 1.0 (2014)

Defined inRFC 6749 (OAuth 2.0)RFC 6750 (Bearer tokens)RFC 7636 (PKCE)OpenID Connect Core 1.0RFC 7519 (JWT)RFC 9700 (OAuth 2.0 security best practice)

Header fields

What OAuth 2.0 puts in its messages, with example values from the stories above.

HTTP/1.1

Request
GET /authorizeThe sign-in server stores the challenge for later.
client_id
print-appWhich app is asking.
scope
openid profile photos.readopenid asks for an ID token. photos.read is the only API access requested.
state
af0ifjsldkjA random value the app checks on return. It stops a stranger from slipping their own code into Leo's session.
code_challenge
E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cMSHA-256 of a secret verifier that stays inside the app. The verifier itself is never sent here.
code_challenge_method
S256
Status
200 OK
Consent
profile, photos.readThe user sees exactly what the app is asking for and can say no.
code
SplxlOBeZQQYbYS6WxSbIAGood for one use, for about a minute. On its own it is not enough to get tokens.
grant_type
authorization_code

Test yourself

Question 1 of 5Score 0

What does PKCE protect against?

Questions people ask

What is the difference between OAuth and OpenID Connect?

OAuth 2.0 lets an app access an API on your behalf. OpenID Connect is a layer on top that adds an ID token, so the app also learns who you are. Sign in with buttons use both.

Is Sign in with another account safe?

Yes, when done right. You type your password only on the provider's page, the app gets a limited token, and you can remove its access at any time in your account settings.

What is PKCE in OAuth?

Proof Key for Code Exchange. The app makes a secret, sends its hash at the start and the secret itself when swapping the code for tokens. A stolen code is useless without it.

How long does an OAuth access token last?

It depends on the provider, often between a few minutes and an hour. Refresh tokens last longer and are used to get new access tokens without signing in again.

What does invalid_grant mean?

The token endpoint refused the code or refresh token: it was already used, expired, made for another app or redirect address, or the PKCE verifier did not match.

Donate