OAuth 2.0 and OIDC as a Client

"Sign in with Google" means Stagedoor never sees the buyer's password. The service sends her to the identity provider, the provider authenticates her by whatever means it has, and sends back a one-time code; Stagedoor exchanges the code, server to server, for tokens, one of which is a signed statement of who the provider vouches for. OAuth 2.0 is the delegation protocol underneath, OpenID Connect is the identity layer on top of it, and Stagedoor is the client in both, which is the only role this topic covers. Being the provider, the thing that issues tokens to other people's apps, is a different book.

The first implementation had the steps right and the trust wrong. It exchanged the code correctly, then read the email claim from the id token and looked up the buyer by email, without checking who had issued the token or for whom. A token minted by any provider, for any app, carrying email: marek@stagedoor.example, logged in as Marek. The flow to know is the authorization-code flow with PKCE; the mistakes are all in what the service believes at the end of it.

The Roles

Four parties. The buyer is the resource owner: the account is hers. Her browser is the user agent, the thing that gets redirected. Stagedoor is the client, registered with the provider under a client_id and, because it has a backend that can keep one, a client_secret. Google is the authorization server, and under OpenID Connect also the identity provider. OAuth alone lets Stagedoor obtain an access token for something of the buyer's, her calendar or her contacts, with her consent; it says nothing about who she is. OIDC adds the id token, a JWT of Topic 26 signed by the provider, whose claims identify her. "Sign in with" is OIDC: Stagedoor asks for scope=openid email and wants the id token, and the access token Google also returns is for calling Google's APIs, which Stagedoor does not do.

The Authorization-Code Flow

Stagedoor generates two random values and stores both in the buyer's pre-login session: a state of 128 bits, and a code_verifier of 43 to 128 characters whose SHA-256, base64url-encoded, is the code_challenge. It redirects the browser to the provider's authorization endpoint with the client_id, the registered redirect_uri, the scope, the state and the challenge. The buyer authenticates with Google and consents. Google redirects her browser back to the redirect_uri with a code and the same state. Stagedoor's backend then calls the token endpoint directly, sending the code, the client_secret and the code_verifier, and receives the id token and the access token in the response body.

# 1. the browser is sent here; the buyer authenticates with Google, not with Stagedoor
GET https://accounts.google.com/o/oauth2/v2/auth
    ?response_type=code
    &client_id=8123...apps.googleusercontent.com
    &redirect_uri=https://stagedoor.example/auth/google/callback
    &scope=openid%20email
    &state=Q3x9...                       # random, stored in the pre-login session
    &code_challenge=E9Melhoa...            # SHA-256 of the verifier, base64url
    &code_challenge_method=S256

# 2. Google sends the browser back with ?code=4/0Ab...&state=Q3x9...; the backend exchanges it, server to server
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=4/0Ab...
&redirect_uri=https://stagedoor.example/auth/google/callback
&client_id=8123...&client_secret=...&code_verifier=dBjftJeZ...   # proves this client started the flow

# response: {"id_token": "eyJ...", "access_token": "ya29...", "expires_in": 3599, ...}

The first request is a redirect, so the buyer's browser carries it and the buyer sees Google's login page, not Stagedoor's. The second request is made by api-01 to Google over its own TLS connection, with the client secret and the verifier that only the backend knows, and the tokens come back in that response, to the backend. The browser never holds a token. It holds a code that is single-use, expires in minutes, and is worthless without the verifier and the secret, which is the whole reason the code exists as a separate step: the thing that travels through the browser is not the credential.

state and PKCE

The two random values defend against two different attacks. state binds the callback to the session that started the flow. Without it, an attacker starts a login on his own account, stops at the callback, and gets the victim to open that callback URL; the victim's browser completes the attacker's login, the victim is now signed in to Stagedoor as the attacker, and her next order lands in his order history with her card behind it. With state, Stagedoor compares the callback's value with the one in the victim's own session, finds no match, and refuses.

PKCE binds the code to the client that requested it. An attacker who intercepts the code, from a log, a referrer header or a compromised redirect, cannot exchange it, because the token endpoint demands the code_verifier whose hash was sent at the start, and the verifier never left Stagedoor's backend. PKCE was designed for mobile apps that cannot hold a secret; the OAuth 2.1 draft, still a draft as this chapter is written, makes it mandatory for every client using the authorization-code flow, and lets it stand in for state's anti-forgery role. Stagedoor sends both regardless, because state also carries where the buyer was going before login, and because two independent bindings cost 256 random bits and nothing else. OIDC adds a third value, a nonce sent on the redirect and echoed inside the id token, which binds the token itself to the session; Stagedoor sends it too.

What the Id Token Proves

The id token is a JWT signed with Google's private key, and Stagedoor verifies it with Google's public keys, fetched from the JWKS URL in Google's discovery document and cached for an hour as Topic 26 described. All five checks apply, with two of them fixed: iss must be Google's issuer string, and aud must be Stagedoor's own client_id. A token issued to another app has a valid Google signature and fails the audience check, and that is the check the first implementation skipped. The nonce claim must match the one Stagedoor sent.

What the token then proves is that Google vouches for the subject named in sub, a string that is stable for that Google account for as long as it exists. That is the identity. The email claim is a fact about the account that may change, may be unverified (Google sets email_verified beside it, and not every provider does), and with Apple's relay is a forwarding address the buyer can turn off. Stagedoor links accounts by the pair of issuer and subject: a row in an identities table with iss, sub and user_id. Email is what the account page displays, and a match on email alone is never a login.

After the Flow

The id token is consumed once, at the callback, to find or create the user. Then Stagedoor issues its own session, exactly the cookie of Topic 25, as if the buyer had typed a password; the domain never learns which login path produced the principal. Google's access token is discarded unless a scope Stagedoor actually uses needs it, and Stagedoor uses none. The refresh token Google may return is not requested.

The design this replaces forwarded Google's access token to the browser as Stagedoor's credential and verified it against Google on each request. That made Google's expiry Stagedoor's expiry: an hour, then a silent logout. It made Google's revocation Stagedoor's: a buyer who removed the app from her Google account was logged out of Stagedoor with no line in any log explaining why, and support spent a week on it. And it made Google's availability Stagedoor's, one outbound call per request to a service that owed Stagedoor nothing. The provider vouches at the door; after that, the session is Stagedoor's own.

Being a Provider Is a Different Book

Everything above is the client side. The other side, issuing tokens to third-party apps, running consent screens, defining scopes as a product and rotating the keys everyone else verifies against, is a product in itself, and Stagedoor does not build one: when an organizer's box-office software wants to read ticket sales, it gets an API key of Topic 28, not an OAuth authorization. No course in the catalogue covers the provider side yet; CyberSecurity Deep Dive covers the threat model that both sides share. The comparable tools row names Keycloak, Auth0 and Ory as the way to be a provider without writing one.