Lesson 18.518.5 Who is the app?

In everyday life. A delivery driver arrives at an office building. Reception does not just take the driver's word. It checks the delivery company's own website for the driver's details, and it lets the driver through only to the loading dock listed there.

What you will learn. How a sign-in server learns which app is asking, and the two good ways to introduce an app to it.

Why it matters. A person can only approve an app if the screen shows its true name, and a wrong return address would send the code to the wrong place.

One request, start to finish. Ana's coworker connects an AI app that has never met this connector before. Before the app can send her to the consent screen, the sign-in server needs to know which app is asking, so it can show the app's name and know where to send the browser back.

1. The app arrives with an ID that is a web address. Its ID is an https address that the app's maker runs.
2. The sign-in server fetches that address. It gets a small document naming the app and listing the exact return addresses the app uses.
3. The sign-in server checks the request against the document. The return address in the request must be one the document lists. If not, the sign-in stops.
4. The consent screen shows the app's name from the document, so the person knows who they are approving.

What must the sign-in server know about an app?

The sign-in server needs two facts about each AI app: a name it knows the app by, called the client ID, and the app's return address. Agreeing on these two facts is called registering the app. There are two good ways:

• The app describes itself. The client ID is a web address, and the small document at that address names the app and lists its return addresses, as in the steps above. That document is called a Client ID Metadata Document. Nobody has to set anything up in advance, which suits AI apps meeting a connector for the first time. The specification says both sides should support it.¹
• You register the app in advance, called pre-registration. You create a client ID in the sign-in server yourself and type it into the AI app's settings. It always works, and you control it fully, but you set up each app by hand.

The specification also lists an older third way, dynamic client registration (an older way in which any app could sign itself up), now on its way out. Brightline keeps it switched off.

What about return addresses on your own computer?

A coding agent on your computer waits for the browser at 127.0.0.1, the address that means "this computer" (17.1), on a free port it picks each time. So for these addresses the sign-in server accepts any port, while checking the rest of the address exactly. That includes the name of the computer: localhost also means "this computer", but a return address listed with 127.0.0.1 does not match one sent with localhost. The app's listed address and the address it sends must use the same one.

Why does Brightline keep an approved list?

Brightline's sign-in server accepts app documents only from a short approved list of app makers. Fetching an address a stranger chose can be used to reach a company's private computers, and Brightline's hosting cannot fully guard against that, so it trusts only known makers (field guide F3 explains). An app whose maker is not on the list is pre-registered instead.

At work. Codex arrives with its document address. The sign-in server fetches it, checks the return address, and shows "Codex" on the consent screen. In a test, an agent sends a client ID that points to an address inside a private network. The sign-in server refuses before it connects. In the lab, a pre-registered Claude Code uses a fixed port instead (field guide F5).

The operating rule: every AI app has a client ID, and every return address is checked exactly. Let apps describe themselves where you can, pre-register them where you cannot, and fetch a stranger's address only by careful rules.

The standards behind this concept: Client ID Metadata Documents (an IETF draft),² and return addresses on your own computer (RFC 8252).³

Figure 18.8. The sign-in server fetches the app's own description, checks the return address, and refuses a fetch into a private network.