OAuth 2.0 and OpenID Connect: done right

A “Sign in with…” button hands your app a code and leaves the app to check what came back. OAuth 2.0 and OpenID Connect are the rules for that exchange, and the same exchange can be built so that a copy of a code is worthless or so that it is a login. In this lesson’s first program, a server that ignores PKCEPKCE: Proof Key for Code Exchange (RFC 7636). The app makes a random verifier, sends its SHA-256 hash, the challenge, with the authorization request, and sends the verifier itself when it swaps the code for tokens. A copy of the code is useless without it. issued tokens for 4 of 5 requests, a bare copy of a code among them, and a server that enforces it issued tokens for 1.

By the end you will be able to run the authorization code flow with PKCE, check the callback and the ID token, give each token only to the party it is for, choose where a browser app keeps its tokens, and link accounts without letting an email address decide who someone is.

Use the authorization code flow with PKCE, and avoid the other grants for people

OAuth 2.0 lets an app act for a person at an API: the person signs in at an authorization server, and the app receives an access tokenaccess token: A token that an app presents to an API to act for a person, limited by scope and by the audience it was made for. The API decides what it allows. The app treats it as an opaque value. that the API accepts. OpenID Connect is a layer on top of OAuth 2.0 that adds sign-in, because it also returns an ID tokenID token: A signed JWT from an OpenID Connect provider that says who signed in: the issuer, the subject, the audience and the times. It is for the app that asked for it, and not for APIs., a signed statement of who signed in. Step through the flow that carries both:

Three random values tie the flow together. The statestate: A random value that an app sends in an authorization request and checks again on the callback, tied to the person's browser session. It shows that the callback answers a request that this browser made. ties the callback to the browser that asked. The nonce ties the ID token to this sign-in. The PKCE verifier ties the code to the app that asked for it. The grants differ in how they get a token, and for a person signing in only one is right:

• Authorization code with PKCE. The app sends the person to the server, receives a code that works once and swaps it for tokens, proving with the verifier that it is the app that asked.
• Client credentials. A service gets a token for itself with its own credentials, and no person is involved.
• Implicit. The server puts the tokens in the redirect URL itself, and RFC 9700 says that clients should not use it.
• Resource owner password credentials. The app collects the person’s password and sends it on, and RFC 9700 says that it must not be used.

The program checks the PKCE test vector of RFC 7636 and then sends five requests to two small servers, one that ignores PKCE and one that enforces it:

"""PKCE: the verifier stays with the app, its hash goes with the request, and a copy of the code alone is worth nothing."""

import base64
import hashlib


def s256(verifier):
    """The code challenge: BASE64URL(SHA-256(verifier)), with no padding (RFC 7636)."""
    return base64.urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest()).rstrip(b"=").decode()


# The test vector of RFC 7636, appendix B.
VERIFIER = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
CHALLENGE = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
print("RFC 7636 appendix B, challenge as computed:", s256(VERIFIER) == CHALLENGE)


class AuthServer:
    """A small authorization server. One that enforces PKCE requires a challenge from this client and checks the verifier."""

    def __init__(self, enforces_pkce):
        self.enforces_pkce = enforces_pkce
        self.codes = {}
        self.count = 0

    def authorize(self, challenge=None):
        if self.enforces_pkce and challenge is None:
            return None, "refused: no challenge"
        self.count += 1
        code = f"code-{self.count}"
        self.codes[code] = challenge
        return code, None

    def token(self, code, verifier=None):
        if code not in self.codes:
            return "refused: code used"
        challenge = self.codes.pop(code)  # a code works once
        if self.enforces_pkce and (verifier is None or s256(verifier) != challenge):
            return "refused: verifier"
        return "tokens issued"


def cases(server):
    results = []
    code, _ = server.authorize(CHALLENGE)
    results.append(("the app exchanges its code and its verifier", server.token(code, VERIFIER)))
    code, _ = server.authorize(CHALLENGE)
    results.append(("a copy of the code arrives with no verifier", server.token(code)))
    code, _ = server.authorize(CHALLENGE)
    results.append(("a copy arrives with a verifier it made up", server.token(code, "x" * 43)))
    code, _ = server.authorize(CHALLENGE)
    server.token(code, VERIFIER)
    results.append(("the app's own code is used a second time", server.token(code, VERIFIER)))
    code, error = server.authorize(None)
    results.append(("an authorization request with no challenge", server.token(code) if code else error))
    return results


ignores, enforces = cases(AuthServer(False)), cases(AuthServer(True))
print(f"\n{'case':<46}{'server that ignores':<22}server that enforces")
for (name, a), (_, b) in zip(ignores, enforces):
    print(f"{name:<46}{a:<22}{b}")

RFC 7636 appendix B, challenge as computed: True

case                                          server that ignores   server that enforces
the app exchanges its code and its verifier   tokens issued         tokens issued
a copy of the code arrives with no verifier   tokens issued         refused: verifier
a copy arrives with a verifier it made up     tokens issued         refused: verifier
the app's own code is used a second time      refused: code used    refused: code used
an authorization request with no challenge    tokens issued         refused: no challenge

The challenge computed from the verifier matched the vector. The server that ignores PKCE issued tokens for a bare copy of the code, for a copy with a made-up verifier and for a request that carried no challenge. The one that enforces it refused all three and issued tokens only for the app’s own exchange. Both refused a code used a second time, because a code works once. RFC 9700 asks every public client to use PKCE and recommends it for confidential clients too.

A callback is only as safe as the checks it runs Pro: opens with a Pro, Premium or Ultimate pass