How a person signs in

A person signs in to the authorization server with an email address and a password, and stays signed in until they sign out or the session runs out. That is the whole of the surface: a sign-in page, an account page that names you and says when your session ends, and a sign-out action. There is no second place a person authenticates and no way to authenticate a person without one of these.

The sign-in page needs no scripting. It works in any browser with scripting turned off.

Signing out ends the session on the server, not only in the browser. A copy of the session taken before the button was pressed is dead too.

⚠ Closing the browser does not sign anybody out. A session lasts half a day from the moment it was created and survives a restart of the server, because it is a record rather than something held in memory. If you need somebody out now, that is the revoke act below, not a request that they close a tab.

The five acts of an account's life

All five are performed by a human hand. There is no automatic enrolment, and no account comes into existence because somebody asked for one.

They can be performed at a shell on the machine, or from an administrative panel in a browser. Both routes run the same rules and mean the same thing. The shell is what you use for the very first account on a new installation — the one where there is nobody to send a link to yet — and over a remote connection, and in a script.

No mail is ever sent. The invitation is printed as a link and you send it however you already talk to colleagues. That is deliberate rather than unfinished: a link the product mailed for you would sit in a queue on a machine the product does not control.

⚠ An invitation link is shown once, and it cannot be printed again. Only a one-way digest of it is stored, so nobody — including whoever wrote the product — can recover it. If it is lost, issue a new one; the old one stops working the moment you do. It also stops working after a week unless you shorten or lengthen that deliberately, because an invitation is a password nobody has chosen yet, sitting in a mail system.

An invited account already exists and cannot be signed in to. The list shows it as invited and not yet claimed, and the sign-in page refuses it until the link is used. If the address belonged to somebody who was revoked, inviting them again brings them back, and claiming the link gives them access.

⛔ There is no way to change somebody's email address. The address is the login identifier and nothing renames it. Invite them at the new address and revoke the old account.

When it refuses somebody

Every refusal on this surface names what to do next. What is worth knowing is why three of them behave the way they do.

It never says whether an account exists. A wrong password and an address nobody has an account for produce the same answer, the same page, and the same amount of work — the last one on purpose, so the two cannot be told apart by how long the answer takes either. An error that distinguished them would turn the sign-in page into a way of asking whether a named person works at your company.

After several failures in quick succession, that address stops being checked at all for a few minutes, and the page says how many. Nobody has to unlock anything; the count clears itself. This applies to an address nobody has an account for exactly as it does to a real one — otherwise "does the lockout fire" would answer the same question, five knocks at a time.

A sign-in page left open across a restart of the server costs one reload. The form is protected by a key held in memory and never written to disk, so a restarted server cannot recognise a form rendered by the old one. The page says so and you type your details again. A key stored so that it can survive a restart is a key that also survives a copy of the backup.

⚠ The same applies to the sign-out button on a stale page, and it fails in the direction that surprises people: the request is refused, and refused without ending the session, because a sign-out the server cannot attribute to you is exactly the request a hostile page would make. Reload the account page and press it on the fresh copy. Until then, you are still signed in.

Giving somebody a new password

Replacing a password closes everything the old password could still do — every session the account has, including the person's own open browser, anything half-way through being authorized, and every standing credential a program holds on their behalf.

It goes that far because the reason to replace a password is that the old one may be in somebody else's hands, and whoever had it could already have spent it on something that outlives it. A session opened with a password outlives the password by up to half a day. A standing credential is worse: it works with no browser, no session and no password, and obtaining one takes nothing but the password you are now replacing. A reset that closed the first door and left the second standing would be a remedy against a thief who did not think of it.

⚠ What that costs is not nothing. A colleague who merely forgot their password also loses the programs working on their behalf, and comes back by signing in and authorizing them again. The command says how many were withdrawn, so you can warn them.

⚠ A link is not the act for a password you believe is stolen. Sending somebody a link to choose their own password changes nothing until they use it — their current password and their open browsers keep working, deliberately, so that a colleague who never opens their mail is not locked out by a link they did not ask for. If you need them out now, that is revoke. When they do use the link, the closure above happens in full: the only difference between the two forms is who chooses the password and when the closing happens, never what is closed.

And what happens to somebody who was in the middle of something. A reset also refuses anything in flight — a sign-in that had already checked the old password, a browser that had already been let through, a program half-way through an exchange. Two of those end in ways worth being able to explain:

• a standing credential can be issued a fraction of a second before the reset reaches it, and is then withdrawn immediately. The record keeps both lines, so you will see one issued and revoked at the same instant. It never served a request.
• a sign-in landing in the middle of the reset, using the new password, can be let in and then told on the very next page that it is not signed in. Signing in again straight away works, and that is what the page says. If a colleague reports this within a second or two of your reset, the answer is "try once more", not an investigation.

⇒ If you are asked whether anything was issued after the cut-off, the honest answer is possibly one, and if so it is already withdrawn on the same row. Do not promise that nothing was ever issued.

Taking access away

This is the act for five o'clock on somebody's last day, and it closes more doors than it looks like it closes:

• their sessions are destroyed, not merely marked. The next page they open sends them to the sign-in form.
• their password is removed. It is not sitting here waiting for the day somebody re-admits the account.
• any unclaimed invitation is cancelled, including one sent last week. Without this, a leaver holding an old link could set a new password after being revoked.
• every standing credential a program holds on their behalf is withdrawn. This is the one that is easiest to miss and matters most: such a credential works with no browser, no session and no password.
• anything in flight is cancelled, from the command's first statement rather than from the moment it finishes — a program half-way through an exchange cannot walk away with a working credential while the command is still running.
• their administrative role, if they held one. It is not a way in; it is authority over the organization. The report says when this happens and it is a line to read.

⚠ The one door it cannot close. A token already in a program's hands keeps working until it expires, which is at most ten minutes after it was issued. Nothing can recall it, for the reason set out in What a token carries. So the honest sentence to an auditor is not "cut off at the moment of the command" — it is cut off at the moment of the command, with any token already issued expiring within ten minutes.

⚠ If the command reports that it could not close every way in, treat the account as still having access until you have run it again and it has succeeded. That warning is deliberately pessimistic and stays that way. Running it twice is safe, and the second run tells you it changed nothing.

⚠ If the person you revoked was the last one who could administer the organization, the command says so. Nobody can administer it until somebody grants that role again, the panel refuses everybody until then, and the only place it can be changed is a command on that machine. Read that line before you walk away.

Revoking is not removing, and that is the point. The account stays in the list as revoked and its history is intact, which is what an audit asks for. Freeing the same email address for a different person is a separate and much heavier ceremony, performed by hand against the database, and it throws away things no command can give back — the account's whole audit trail, the record that this person ever had access here, and any link between the old account and the new one. ⛔ Do not reach for it when what you meant was revoke.

What is counted, and what is deliberately not

Seats are counted. Work is not. One line is written when an account becomes able to sign in, and one when it stops:

And what is never recorded: a sign-in, a sign-out, an authorization, a token issued, a token refreshed, a request made with one. Nothing per act, ever.

That is a product decision and not an oversight about disk. A record of what your people did is a different thing from a count of how many of them there are — different to keep, different to protect, and different to be asked for by a third party. The authorization server keeps the count, and you can read the whole of it off the list of who has access, which is the point: a bill you can check yourself.