Lesson 18.618.6 A token made for one door

In everyday life. A concert wristband is printed for one venue and one date, and it has a hologram that the gate staff check by eye. They do not phone the ticket office for each fan. A wristband from last week's show, or from the venue across town, does not get you in, however real its hologram.

What you will learn. How a connector can trust a token without asking anyone, what the token says, and why it works for one connector only.

Why it matters. The connector decides alone, on every request, from the token in front of it. Miss one check, and a real token opens the wrong door.

One request, start to finish. Brightline also runs a second connector, a policy-search connector, that trusts the same sign-in server. A builder tests it with a token made for it. Later, by mistake, the same token is sent to the AP connector.

1. The AP connector checks that the token is genuine (how, just below). It is: the same sign-in server made it.
2. The AP connector checks who the token was made for. The token says: made for the policy-search connector's address.
3. The AP connector refuses with 401. A real token, made for a different door.

How can a connector trust a token without asking?

In step 8 of 18.2 the connector does not phone the sign-in server. It checks the token itself. Think of a wax seal on an old letter. Only the king has the seal stamp. But a picture of the seal is posted in every town square, so anyone can compare a letter's seal with the picture and know the king sent it, and that nobody changed it on the way. A token's signature works the same way. The sign-in server has a private signing key, the stamp, that never leaves it. It publishes matching public keys, the posted pictures. Each token says which stamp sealed it. The connector fetches the public keys once, keeps them, and fetches them again when a token names a stamp it has not seen (at most every 30 seconds), and every few minutes anyway (18.15). It checks every token's signature against them. A forged token, or one with a single changed letter, fails the check.

What are public and private keys?

The stamp and the posted pictures are a key pair: two long numbers that a computer makes together, so that they fit each other.

• The private key signs. Only its owner has it, and here that is only the sign-in server.
• The public key checks. Anyone may have it, so the sign-in server posts it for anyone to fetch.
• A signature made with the private key checks out only against its own public key. If even one letter of the token changes, the check fails.
• Knowing the public key does not let anyone work out the private key. That is why posting it is safe.

So, for every call:

1. The sign-in server signs the token with its private key.
2. The connector checks the signature with the sign-in server's public key.
3. The connector also checks the token's expiry, who it is for, and its permissions.

The AI app receives only the token. It never sees the private key, and neither does the connector.

Does a signature hide what a token says?

To encrypt a message is to scramble it so that only someone with the right key can read it. Signing hides nothing. Anyone who holds a token can read what it says. The signature only makes sure that any change is noticed.

What does a token say?

A sign-in token is usually a JWT (JSON Web Token, said "jot"). It has three parts: a small label section, a body of facts, and the signature. Each fact in the body is a claim. Six claims matter:

The first five are standard. tenant is Brightline's own. The iss claim is the same sign-in server name the app checked in 18.4. Now the connector checks it too, inside the token. Anyone holding a token can read its body, because the seal protects it from changes, not from reading. So a token never carries anything private.

How is a token made for one connector?

When the app asks for a token (steps 3 and 7 of 18.2), it names the connector it wants the token for. The specification says it must. The sign-in server writes that address into the token as its audience, and the connector must refuse a token whose audience is not itself.¹

What is the confused deputy?

A story shows why the audience check matters:

1. Brightline approves a free "invoice helper" connector from a marketplace, and lets it use Brightline's own sign-in server, so staff need only one sign-in for every tool. That is a common choice.
2. Ana's app signs her in for the helper and hands the helper a token made for it. Because both connectors share one sign-in server, the issuer is the same, so the issuer check cannot tell the two tokens apart.
3. The helper is hostile. It sends that token on to Brightline's connector, hoping to read Ana's invoices.
4. Brightline's connector reads the audience, "made for the invoice helper", and refuses.

Without the audience check, Brightline's connector would have served the helper as if it were Ana. Security people call this the confused deputy: a trusted server tricked into acting for someone else. For the same reason, a connector must not pass a token it received on to any other service.

Why do tokens live for such a short time?

A sealed token cannot be called back. The connector checks tokens itself, without asking the sign-in server, so it cannot know if one was canceled a minute ago. The safeguard is time. Brightline's sign-in tokens last 10 minutes, and its refresh tokens 7 days. An app gets a refresh token only if it asks for one. When a sign-in token runs out, an app that has one uses its refresh token to get a new sign-in token. An app without one sends the person back to sign in. At each refresh, Brightline's sign-in server checks again: is this person still in the company? Does their role still allow this? Not every sign-in server does this by itself, so Brightline asks for it as a rule of its own. So a removed person loses access within 10 minutes at most. 18.15 explains how refresh tokens are kept safe.

At work. The builder asks Claude Code to show the claims of a token it got for the TypeScript connector, without printing the token itself, and reads aud: the TypeScript connector's address. The Python version has its own address, so it refuses the same token with 401, because the token names the wrong audience. The checks in 18.13 confirm this on every build.

The operating rule: accept a token only if its seal checks out against your sign-in server's public keys, its issuer is that server, its audience is you, and it has not expired. Never accept a token made for someone else, and never pass yours on.

The standards behind this concept: JWT (RFC 7519),² the published public keys, called a JWKS (RFC 7517),³ and naming the connector when asking for a token, called a resource indicator (RFC 8707).⁴

Figure 18.9. A token's claims, each with the check it gets. The seal proves the claims were not changed.