Who’s on FirstLearn

7 min read

What if nobody is there to sign in?

A nightly job has no Alice to click Allow. So whose access does it use? Settle that before you choose a protocol, because everything else follows from it.

This lesson builds on the ones before it. If you arrived here first and a term is unfamiliar, lesson 1 is where they start, and each is in the glossary.

Two answers, and only two

Every request an agent makes uses somebody’s authority. There are two possibilities.

  • A person’s. The token names that person. What the agent can do is capped by what the person can do, and by what they approved. This is what the previous lesson showed.
  • Its own. The token names the agent. Nobody approves anything at the moment it runs. An administrator decided in advance what this agent is allowed to do.

This guide calls whoever’s authority is being used the principal. Which of the two it should be is not a matter of taste. It follows from the work.

Whose authority is one question. Which software is acting is another, and a token can answer both: one that names Alice also names the app it was issued to. The next lesson puts a second piece of software on the path.

Sort five agents

For each one, whose authority should it use? Choose, then read why.

1An assistant that summarizes your unread email each morning.

  • Right. Yours. It should be able to read your mailbox and nobody else’s, and a token that names you is what makes the mail service enforce that.

  • Not quite. Then it needs access to every mailbox it might ever summarize, and all that keeps it in yours is the agent itself: its code, and its word about whose request this is.

2A nightly job that flags invoices that do not match a purchase order.

  • Not quite. Nobody in particular asked for tonight’s run, and it should not stop working when one employee leaves. The work belongs to the organization.

  • Right. No person is involved. An administrator decides once what this job may read and write, and the job runs as itself.

3A support bot that tells each customer the status of their own orders, and must never show one customer another’s.

  • Right. Each customer’s. The answer depends on who is asking, so each request should carry that customer’s authority, and the order system can then refuse anything else.

  • Not quite. It is often built this way. But then the order system sees one caller for every customer, and whatever keeps customer A out of customer B’s orders rests on the bot’s word about who is asking. That is the API key problem from the first lesson.

4An agent that posts a digest of yesterday’s deploys to the team channel.

  • Not quite. The digest is the same whoever is reading it, and it runs on a schedule. There is no one whose access it would be borrowing.

  • Right. Scheduled, shared, and the same for everyone. It reads deploy records and posts to one channel, as itself.

5Alice asks an agent to watch her inbox while she is on vacation and file her receipts.

  • Right. Alice’s. But notice that she will not be there. The agent holds her access, on a refresh token, with nobody watching. Keep reading: this combination has a section of its own.

  • Not quite. It is her mailbox, so it is her authority. An agent with its own standing access to mailboxes could read anyone’s.

The pattern in those five: the mail assistant, the support bot and the agent filing Alice’s receipts act for a person. The invoice job and the deploy digest act as themselves. A rule of thumb that covers most cases:

  • If the right answer depends on who is asking, the agent acts for that person.
  • If the work belongs to a team or a company, and runs on a schedule or a trigger, the agent acts as itself.

How an agent proves it is itself

Acting as itself, the agent still needs a token, and the routine is a shorter version of the previous lesson. It proves which software it is to the authorization server, gets a short-lived access token, and sends that to the API. There is no browser and no consent screen, because there is no user. OAuth calls this client credentials.

Which service plays the authorization server depends on where the agent runs. Inside a company it is usually the sign-in system its services already trust. In a cloud it is the cloud’s own token service. On Kubernetes the cluster can play the part itself. The pod asks for a token addressed to the API it is going to call, and that API asks the cluster whether the token is good and was meant for it. The token a pod gets by default is addressed to the cluster itself: never send that one anywhere else.

The interesting part is the first step. What does the agent prove itself with? There are three common answers, and they are not equally good.

A key it storesA secret it trades for tokensAn identity from its platform
What the agent holdsOne long-lived API key, sent on every requestA long-lived client secret or private key, and short-lived tokensShort-lived credentials only
Who issues itWhoever runs the APIThe authorization server, for a secret. A key pair is your own, with the public half registered thereThe platform the agent runs on: a cloud, Kubernetes, a CI system
If a copy leaksIt works until someone notices and replaces itA token stops in minutes. The secret works until it is replacedIt stops when it expires: minutes to hours, depending on the platform
Who replaces itYou, by handYou, by handThe platform, on its own

The third column is called workload identity. The platform that started the agent already knows exactly what it started, so it can vouch for it. It hands the job a short, signed note saying what the job is, and replaces the note before it expires. The job trades that note for access.

Nothing had to be stored, but there is still something to take. Anything running inside the job can pick that note up, including a command or a web request the model was talked into making. Keep it, and the local address the platform hands it out from, out of reach of the model’s tools.

An identity nobody had to store for the agent

The agent’s identity: Issued by the platform

What the access token says

about:      invoice-job
issued to:  invoice-job
for:        billing.example
allows:     read invoices
expires:    in 10 minutes
The same three questions
Who is acting?The invoice job. The platform that started it vouches for that, so no long-lived secret had to be stored for the job.
For whom?Nobody. The token is about the agent itself: the same name appears twice.
Who said they could?An administrator, in advance, by writing a rule: this job may read invoices. Nobody approved tonight’s run.

Everything from the token lesson still holds: one audience, a narrow scope, a short life. What changes is who the token is about, and that the only limit on this agent is the rule an administrator wrote.

In the figure the platform and the authorization server are two different systems, and the second has agreed to accept identities that the first one issues. That agreement is called federation. A cloud accepting a note from your CI system is the usual example. Where a platform’s own services accept its own notes, nothing is federated: it is all one system.

The trap in the middle

The fifth agent in the exercise was neither one thing nor the other: Alice’s access, and no Alice. It has a person’s full authority and no person watching. Of every arrangement in this guide, it is the one most likely to end badly.

Sometimes it is what the job needs. If you find yourself there:

  • Ask for the narrowest scope that does the work. Filing receipts does not need permission to send mail.
  • Find a way to reach the person for anything that cannot be undone. The final lesson shows how.
  • Know how the access is switched off, and who can do it, before the agent runs for the first time.

Check yourself

Answer before you read on. Nothing is recorded.

1Your agent runs as a nightly job and calls an internal billing API. Security asks what identity it runs as. Which is the best answer?

  • Right. It names one workload, it is issued where the job runs so nothing long-lived has to be stored, and what it can reach is written down in one rule: here, billing and nothing else.

  • Not quite. That is a credential, not an identity. It usually has no expiry, it has to be stored and replaced by hand, and anyone who copies it is the job.

  • Not quite. Then the job can do everything you can, its actions are logged as yours, and it breaks or lingers when you change teams.

2An agent gets a token as itself, with no user involved. Who does the token say it is about?

  • Not quite. The administrator wrote the rule, but is not named in the token. The token is about whoever’s authority is being used: here, the agent’s own.

  • Right. With no user, the agent is both the app the token was issued to and the subject it is about.

  • Not quite. A token is always about someone or something. Here it is the agent.

3Alice connects her mailbox to an agent and leaves for two weeks. The agent keeps working on a refresh token. What is the main risk?

  • Not quite. That would be an inconvenience. The risk is in what the agent can do while it keeps working.

  • Not quite. It can: the token names the client it was issued to. The trouble is how much that app can do while unsupervised.

  • Right. A person’s authority, and no person present to notice. Narrow the scope, keep a way to reach Alice for anything that cannot be undone, and know how the grant is revoked.

What to keep

  • Every request uses somebody’s authority: a person’s, or the agent’s own. Decide which first.
  • Acting for a person: the token names the person, and what they can do is the ceiling.
  • Acting as itself: the token names the agent, and the rule an administrator wrote is the only limit.
  • An agent’s own identity is best issued by the platform it runs on and short-lived, not stored as a secret.
  • A person’s access with no person watching is the arrangement to be most careful with.

The names for these

The rest of this guide, and every specification, uses these terms. Each links to its entry in the glossary.

In this lessonIts nameDefined as
Whoever’s authority a request usesPrincipalThe party whose authority is being exercised. A person, an organization, or the agent itself.
An account that belongs to softwareService accountAn account that belongs to software, not to a person. In OAuth terms, a client acting under its own identity.
Getting a token as itself, with no userClient credentialsThe OAuth grant in which a client obtains a token as itself, with no user involved.
A running piece of software, such as the invoice jobWorkloadA running piece of software, such as a pod, a function or a process. Distinct from the person or organization it works for.
An identity the platform issues to itWorkload identityAn identity assigned to a workload by the platform it runs on, proven with a short-lived credential the workload did not have to be given in advance.
One system accepting identities that another issuedFederationOne system accepting identities issued by another, by prior agreement and usually by trusting its signing keys.

Go deeper

The same ground at full depth, when you want it. None of it is needed for the next lesson.