The broker portal has a new sign-up page. A person types an email address, a password, and picks a brokerage from a list: brk-north. The portal sends a link to the address. The person clicks it, and the account turns active. The next morning the account lists quote Q-5531, which belongs to brk-north.
Every step worked as designed, and the design has a hole. The email link proved one thing: whoever filled in the form can read that inbox. It did not prove that the person is a real, specific human. It certainly did not prove that the person works for brk-north. That fact came from a drop-down list, which any visitor can pick. If the portal turned the picked brokerage into the account's tenant, then anyone with an inbox can read a brokerage's quotes by choosing its name.
This page is about the moment an account is born, and about the moments it is repaired and retired. The question each time is the same: what did this step actually prove, and what did it only assume?
What sign-up proves, and what it does not#
Picture the four facts the portal would like to know about the person behind the form. Each needs a different kind of evidence.
| Question | Evidence that answers it | What the sign-up form gave |
|---|---|---|
| Can this person read the inbox they typed? | A one-time code or link sent to that inbox | Yes: the clicked link |
| Is this a real, specific person? | Identity evidence checked against an authority | Nothing |
Does this person act for brk-north? | A grant by someone who may speak for brk-north | A drop-down choice, which is a claim |
| Is it the same person at the next login? | An authenticator bound to the account | A new password |
The table shows why "the email is verified" is a weaker sentence than it sounds. A verified email is an address the account owner has shown they can read. It is a useful fact: the portal can send a reset code there, and a typo in the address is caught early. It is possession of an inbox, and nothing about a real-world identity or an employer.
Plain English. Sign-up creates an account. It does not create trust. Trust comes from evidence, and each kind of evidence answers one question only.
Before AI. A backend engineer has seen this split in every enterprise system. Human resources creates the person in the directory; an administrator adds the person to an LDAP group; the application stores a salted hash of a password and checks it at login. Nobody let new hires type their own department into a form. The portal for external brokers needs the same split, with the brokerage playing the part of the department.
Identity proofing: linking an account to a real person#
The second question in the table, "is this a real, specific person?", has a name. Identity proofing is the process of linking an account to a real-life person by checking evidence: a document, a record held by an authority, sometimes a live session with a trained person. NIST SP 800-63A-4 defines it as "the process of establishing a relationship between a subject accessing online services and a real-life person". A tiny example: a bank asks for a passport photo page and a selfie before it opens an account; a newsletter asks for nothing.
How much proofing a service needs is a risk decision, and NIST gives it a scale. The identity assurance level (IAL) is "the robustness of the identity proofing process". Guideline (NIST SP 800-63-4, read 2026-11-18): IAL1 supports the real-world existence of the claimed identity; IAL2 adds more evidence and a more rigorous validation; IAL3 adds an on-site attended session with a trained proofing agent and at least one biometric characteristic. NIST also describes a category with no proofing at all: "There is no requirement to link the applicant to a specific, real-life person."
A confirmation code sent to an email address has a precise role in that scheme. Guideline (SP 800-63A-4, read 2026-11-18): confirmation codes confirm access to a postal address, email address or phone number, and they can be one verification step inside an IAL1 or IAL2 process. On its own the code is not proofing. An inbox can be created in a minute by anyone.
Three levels that are easy to blur#
NIST names three assurance levels, and each answers a different question. Keep them apart; a design that mixes them makes wrong promises.
| Level | Question it answers | Where it is decided | In the insurance example |
|---|---|---|---|
| IAL (identity assurance) | How sure are we that this account belongs to this real person? | Once, at enrollment, and again at some recoveries | Is this really an employee of a licensed brokerage? |
| AAL (authentication assurance) | How sure are we, at this login, that the same person is back? | At every sign-in and step-up | Password today; a passkey before a decision (see Authenticators) |
| FAL (federation assurance) | How well protected is the assertion that carries the login to the application? | Each time an identity provider tells an application who signed in | The insurer's identity provider tells the portal backend who the broker is |
Guideline (SP 800-63-4, read 2026-11-18): AAL is "the robustness of the authentication process itself"; FAL is "the robustness of the federation process used to communicate authentication and attribute information" between the identity provider and the relying party. None of the three says what the person may do. A broker proofed at IAL2 and signed in at AAL2 still may only read quotes of the brokerage that granted the access. That is an authorization question, decided on the record (see Authorization).
Common confusion. "We verified the user" can mean any of four things: the inbox, the real identity, the login, or the permission. Ask which one before anyone builds on the sentence.
The smallest primitive: a password stored so a leak does not hand it over#
Before the brokerage question, the account needs a credential. Most portals still start with a password, and the oldest failure in this area is storing it badly. If the user table leaks, the attacker should get nothing they can type into a login form.
The rule from the guidelines is short. Guideline (SP 800-63B-4, read 2026-11-18): "Passwords SHALL be salted and hashed using a suitable password hashing scheme", the salt "SHALL be at least 32 bits in length", and the cost factor "SHOULD be as high as practical". Two words in that sentence need a plain meaning.
A password hash is the output of a one-way function that is deliberately slow and memory-hungry. The server stores the output, never the password, and at login it computes the function again and compares. Slow matters because an attacker with a leaked table tries billions of guesses; a function that costs a tenth of a second and a hundred megabytes per guess turns billions into a few. A fast hash such as plain SHA-256 is the wrong tool for passwords for exactly this reason.
A salt is a random value stored next to each hash and fed into the function with the password. Two people with the same password get different hashes, so one precomputed table cannot crack every account at once. Guideline (OWASP Password Storage Cheat Sheet, read 2026-11-18): use a unique random salt per password; prefer Argon2id (minimum m=19456, t=2, p=1); use scrypt (N=2^17, r=8, p=1) if Argon2id is unavailable; bcrypt is for legacy systems only.
The code below shows the shape with the Python standard library's hashlib.scrypt and OWASP's scrypt minimum. It demonstrates three things: a fresh salt per password, parameters stored with the hash so they can be raised later, and a comparison that does not leak timing. It is a minimal shape for teaching, not part of examples/uw-auth/; production code uses a maintained library (for example an Argon2id binding) or the identity provider's own storage.
import hashlib
import hmac
import os
N, R, P = 2**17, 8, 1 # OWASP minimum for scrypt (128 MiB), read 2026-11-18
MAXMEM = 256 * 1024 * 1024 # above 128 * N * R bytes; the default limit is lower
def hash_password(password: str) -> str:
salt = os.urandom(16) # unique per password, from the OS random source
digest = hashlib.scrypt(password.encode(), salt=salt, n=N, r=R, p=P, maxmem=MAXMEM, dklen=32)
return f"scrypt${N}${R}${P}${salt.hex()}${digest.hex()}"
def verify_password(password: str, stored: str) -> bool:
_, n, r, p, salt_hex, digest_hex = stored.split("$")
digest = hashlib.scrypt(password.encode(), salt=bytes.fromhex(salt_hex), n=int(n), r=int(r), p=int(p),
maxmem=MAXMEM, dklen=32)
return hmac.compare_digest(digest, bytes.fromhex(digest_hex))
Three details carry the weight. The salt comes from os.urandom, and the Python documentation asks for "about 16 or more bytes from a proper source". The maxmem argument is there because OWASP's scrypt setting needs 128 MiB, more than the library's default limit; without it the call fails rather than silently weakening. And hmac.compare_digest is used because the Python documentation describes it as "designed to prevent timing analysis". What this code does not do: rate-limit guesses, check a blocklist of breached passwords, add a pepper, or upgrade old hashes. Those belong to the login service, and the folded notes below cover them.
The rules for the password itself changed in the current NIST revision, and many sign-up forms still enforce the old ones. Guideline (SP 800-63B-4, read 2026-11-18): a password used as the only factor must be at least 15 characters; one used only as part of multi-factor authentication at least 8; the maximum allowed should be at least 64; verifiers "SHALL NOT impose other composition rules"; they "SHALL NOT require subscribers to change passwords periodically"; they compare new passwords against a blocklist of common and compromised ones; and they "SHALL allow the use of password managers and autofill".
The insurance example: how u-broker-n1 really joins brk-north#
Back to the sign-up page. The fix is not a better drop-down. The fix is to stop treating brokerage membership as something a visitor declares. Membership is a grant, and someone who may speak for the brokerage makes it.
In the example the broker is the principal u-broker-n1. The record that says it belongs to tenant brk-north lives in the directory, the identity provider's view of principals. It never comes from the sign-up form or from a request parameter. Here is the entry from examples/uw-auth/directory.py, PRINCIPALS (an excerpt: one principal, the type annotation left out):
PRINCIPALS = {
"u-broker-n1": {"type": "person", "roles": ["broker"], "tenant": "brk-north", "business_unit": None,
"assignments": [], "entitlements": [], "client_id": "svc-portal-bff",
"scopes": ["quotes.read", "quotes.submit"], "purpose": "broker, signs in to the broker portal"},
}
The function subject_for in the same file builds what the policy decision point sees, and its docstring states the rule: the verified context comes from "a token it validated plus the directory, never from request parameters". Running it in a scratch copy of the example and asking the policy decision point (pdp.decide) about two quotes gives:
{'principal_id': 'u-broker-n1', 'principal_type': 'person', 'roles': ['broker'], 'tenant': 'brk-north', 'scopes': ['quotes.read', 'quotes.submit']}
Q-5531 200 R-AZ-03 broker of tenant brk-north on its own quote
Q-6620 404 R-AZ-03 record belongs to another tenant: not found (existence not revealed)
The broker reads its own brokerage's quote Q-5531 and gets 404 for Q-6620, which belongs to brk-south. The broker sees a quote_id; inside the insurer the same record is submission SUB-1004 (for Q-5531), and the decision is made on the record both ids point to. The point for this page is upstream of that decision: the tenant attribute was right because it came from a trusted source. If sign-up had written whatever the visitor picked, the same correct policy would have answered 200 to a stranger. The example itself has no registration code; the onboarding flow below is described, not run.
The flow the portal should run, with who acts at each step:
| Step | Who acts | What it establishes |
|---|---|---|
| 1. Invitation | The brokerage's own administrator, already trusted for brk-north, invites an address | Who may speak for the brokerage made a grant |
| 2. Email confirmation | The invited person clicks a single-use link | Control of the invited inbox |
| 3. Credential | The person sets a password (and, better, a passkey) at the identity provider | An authenticator bound to the account |
| 4. Membership | The identity provider records tenant brk-north and role broker | The attributes the policy will read |
| 5. Proofing, if required | A proofing step, if the insurer's risk assessment asks for IAL2 | That the account is a real, specific person |
Step 5 is conditional on purpose. Whether a broker portal needs IAL2 is the insurer's risk decision, not a universal rule. Steps 1 and 4 are not optional: without them, any inbox becomes a tenant member.
Diagram: Four lanes of onboarding · each proves one thing, one writes the tenant
Read each lane as one question. The email lane proves the person can read an inbox. The proofing lane, when the insurer's risk assessment asks for it, links the account to a real person. The membership lane is the only one that writes the tenant and role, and only someone trusted for the brokerage may start it. The credential lane binds a password or a passkey for later logins. The policy decision point reads the membership lane's attributes; it never reads what a visitor typed into a form.
- Inbox control
- invited address gets a link: The identity provider sends a single-use confirmation link to the address the brokerage administrator invited.
- link clicked: inbox confirmed: Proves that the person can read that inbox. Says nothing about a real-world identity or an employer.
- Real person (if required)
- identity evidence checked: Evidence is checked against an authority. Required only if the insurer's risk assessment asks for it; it is not implied by any other lane.
- Brokerage membership
- brokerage admin invites: A person who may speak for the brokerage grants membership. A visitor cannot pick a tenant from a list.
- directory records tenant + role: The identity provider stores the attributes the policy decision point will trust, with one owner who can change or remove them.
- Credential
- password stored as salted hash: The identity provider stores a slow, salted hash of the password, never the password.
- passkey added (recommended): A phishing-resistant authenticator for later logins and step-up. Its details live on the Authenticators page.
- First request
- PDP reads tenant from the directory: The policy decision point decides quote reads on the record, using the tenant the membership lane wrote.
Read the diagram from left to right. Each lane answers one question from the first table, and only the membership lane writes the attribute the policy decision point will trust. The email lane stays narrow: it proves the inbox and feeds recovery later, nothing more.
What this is not. Granting the brokerage role is authorization data, and keeping it current when people join, move and leave is identity governance. Provisioning protocols such as SCIM carry that data; they do not enforce anything. That lifecycle has its home in Identity governance.
Account recovery: the back door that skips the front door#
A month later the broker loses the phone with the password manager. The portal needs a way back in. Account recovery is the process that lets a person regain access after losing an authenticator, and it is the step attackers like most. A recovery path that asks for less than a login is a cheaper login.
Here is how that goes wrong, as an illustrative scenario (not an example case). The portal requires a password and a one-time code at login. Its "forgot password" page emails a link that resets the password and signs the person in. The broker's email account has no second factor. An attacker who guesses that email password clicks "forgot password", follows the link, and is inside the portal. The second factor at login was never asked for. Nothing broke; recovery was designed weaker than login.
The guidelines close each part of that path. Guideline (OWASP Forgot Password Cheat Sheet, read 2026-11-18): return a consistent message for existing and non-existing accounts, with uniform response time; reset tokens are random, long, single-use and expire; "Don't automatically log the user in"; do not change the account until a valid token is presented. Guideline (OWASP MFA Cheat Sheet, read 2026-11-18): recovery must not "provide an attacker with a way to bypass MFA"; security questions are "no longer recognized as an acceptable authentication factor". Guideline (SP 800-63B-4, read 2026-11-18): "In all cases, account recovery SHALL cause a notification to be sent to the subscriber"; at AAL2, recovery needs two codes from different methods, or a code plus a bound single-factor authenticator, or repeated identity proofing.
Diagram: Recovery that restores one factor · and skips none
Time runs down the page. The broker has lost the phone that held the passkey. The reset link proves the inbox, and the portal still asks for the remaining bound authenticator, the password. Only then does it bind a new authenticator, notify every address on the account, and end existing sessions. If no bound authenticator remains, the path goes to the brokerage administrator, who repeats the original grant. At no point does a single emailed link sign the person in.
- Broker to Identity provider: forgot my passkey. Recovery starts. The response is the same whether or not the account exists.
- Identity provider to Broker's inbox: single-use link, short expiry. A random, single-use token. The account is not changed yet and nobody is signed in.
- Broker to Identity provider: link + password. The remaining bound authenticator is still required, so the inbox alone does not restore the account.
- Identity provider to Broker: register a new passkey. One lost factor is replaced. The other factor was proven, not skipped.
- Identity provider to Broker's inbox: notice: account recovered. NIST 63B-4: account recovery SHALL cause a notification. Existing sessions end.
- Brokerage admin to Identity provider: re-invite (if no factor left). With no bound authenticator left, the brokerage repeats the original grant instead of a weaker path.
The sequence shows the corrected path: the reset link proves the inbox, then the portal still asks for a remaining bound authenticator (or sends the person to repeated proofing), and only then sets a new credential, notifies every address on the account, and ends existing sessions. The design principle is that recovery restores one lost factor; it never replaces all of them at once.
The account lifecycle: an account outlives the reason it was created#
The account will also change and end. An account lifecycle is the sequence from creation through changes (a new role, a move to another brokerage) to suspension and deletion. The broker in brk-north might move to brk-south. If the portal only ever adds attributes, that person keeps reading brk-north quotes after the move.
The people side of lifecycle has three duties for this page. First, every attribute that drives authorization (tenant, role) must have one owner who can change or remove it. Second, a leaver's account must stop working everywhere, including sessions already open and tokens already issued; the example's own case UW-A17 (this site's own case series) shows a leaver deactivated through a SCIM-style store right after a sign-in. Third, dormant accounts should be found and disabled, because an account nobody uses is an account nobody notices being used. Standard (RFC 7643, read 2026-11-18): the SCIM active attribute is "a Boolean value indicating the user's administrative status"; what the receiving application does with false is up to that application. The full joiner, mover and leaver process lives on Identity governance.
In a coding agent. A coding agent never gets a person's account. It works through a repository-scoped GitHub App installation, not a personal access token borrowed from a developer, so its identity can be removed without touching any person's account. A person with merge rights reviews and merges what it proposes. The Coding agents page owns this case; the shipping workflow is on diff-to-deploy.sammuthu.com.
Failure mode: the self-declared tenant#
Put the opening scene into the request path. A visitor signs up with an inbox, picks brk-north, and the portal backend writes tenant: brk-north into the account. The identity provider now issues that account a token whose tenant claim is brk-north. The API gateway checks the token: valid signature, right audience, scope quotes.read. The quote service asks the policy decision point about Q-5531; the rule "a broker reads quotes of its own tenant" compares brk-north with brk-north and allows.
Every check passed, and every check was correct. The policy was right; its input was false. A valid token is not a permission, and a correct permission check on a false attribute is not one either. The defect sits at enrollment, which is why authorization reviews must include the question "where does each attribute come from, and who may write it?"
Architecture choice: who vouches for the broker#
The recurring decision of this site applies here: what is the simplest credible design for this principal, and what would make it grow?
| Design | Simplest credible when | Grow when | Residual risk |
|---|---|---|---|
| Insurer staff create broker accounts by hand | A few brokerages, low volume | Onboarding becomes a queue | Staff error; slow leaver removal |
| Brokerage administrator invites its own brokers (delegated administration) | Many brokerages, each with one trusted contact | A brokerage wants its own sign-in | The administrator account is a high-value target |
| Federation with the brokerage's identity provider | Large brokerages with their own directory | Many federations to maintain | Trust in the brokerage's joiner and leaver process |
| Self-sign-up with approval queue | Public interest forms, before any data access | Any access to tenant data | Approval becomes a rubber stamp |
This site's recommendation: use a managed identity provider for credentials and recovery, and make tenant membership come only from delegated administration or federation. Self-sign-up may create an account with no tenant and no access, which is harmless, but it never writes tenant. Federation (the OAuth and OIDC page covers the protocols) moves the joiner and leaver problem to the brokerage, which knows its staff best, and keeps the question "may this person read this quote" with the insurer.
Standards and libraries for this chapter#
Guideline (NIST SP 800-63-4, Final, July 2025, read 2026-11-18): the base volume plus 63A (proofing and enrollment), 63B (authentication and authenticator management) and 63C (federation). It supersedes SP 800-63-3. Its scope is government systems; private services use it as a well-argued reference, not as a legal requirement. Guideline (OWASP Password Storage, Authentication and Forgot Password cheat sheets, read 2026-11-18): living pages without version numbers; the read date is the version.
Product (FastAPI, as documented on 2026-11-18): the FastAPI security tutorial installs pwdlib[argon2] and states "The recommended algorithm is "Argon2""; documented shape, not run here. Product (identity providers): a managed identity provider usually owns password storage, recovery and enrollment flows; which hashing scheme and recovery options a given product uses is in that product's documentation and is compared on the Frameworks page.
Security notes#
Security note. Never log the password, the reset token, the confirmation code or the full email of a failed attempt. Log the account id, the event and the outcome.
Security note. A breached-password blocklist check at sign-up and at password change catches more real attacks than any composition rule, and NIST forbids the composition rules anyway.
Production pitfall. The forgot-password link host must be fixed or checked against an allowlist. OWASP warns that building it from the request's Host header lets an attacker point the link at their own site.
Monday checklist#
- Find where each authorization attribute (
tenant, role) is written at sign-up. If a visitor can choose it, remove that path. - Confirm passwords are stored with Argon2id, scrypt or (for FIPS) PBKDF2 at OWASP's minimums, with a unique salt per password.
- Remove composition rules and periodic forced changes; add a breached-password check; allow paste and password managers.
- Walk the forgot-password flow as an attacker: does it sign the person in, skip the second factor, or reveal whether an account exists?
- Check that recovery sends a notification and ends existing sessions.
- List accounts with no sign-in for 90 days (an illustrative threshold; set your own) and decide who reviews them.
Exercises#
- A product manager wants to show "Verified" next to every broker whose email is confirmed. What should the badge say instead?
AnswerName the fact, not the trust
"Email confirmed". The confirmation proves control of an inbox; "Verified" reads as identity proofing or brokerage membership, which it is not.
- The portal moves from a password plus SMS code to passkeys. Does the IAL of existing brokers change?
AnswerIAL and AAL move separately
No. IAL comes from the proofing done at enrollment. Passkeys raise the authentication assurance (AAL) of each login; they do not tell you more about who the person is.
- A broker moves from
brk-northtobrk-south. Which three things must change for the move to be complete?
AnswerAttribute, sessions, tokens
The directory's tenant attribute (removed, then granted by brk-south's administrator), the open sessions, and any issued tokens that still carry brk-north; otherwise access survives until they expire.
Advanced perspective#
Running password hashing in productionPepper, rehash on login, and the cost of slowness
Upgrading parameters. Store the algorithm and its parameters with every hash, as the sketch does. When you raise the cost, you cannot recompute old hashes (you do not have the passwords), so you rehash at the next successful login: verify with the stored parameters, then write a new hash with the new ones. Accounts that never sign in again keep old hashes; a common policy forces a reset for them after a deadline.
Pepper. NIST says verifiers "SHOULD perform an additional iteration of a keyed hashing or encryption operation", and OWASP calls the key a pepper: one secret shared across all hashes, kept apart from the database (a secrets manager or an HSM). It helps when only the database leaks. OWASP describes it as defense in depth only. Rotating a pepper has the same problem as raising parameters, so plan the key id from the start.
Slowness is a denial-of-service lever. A login endpoint that spends 128 MiB and noticeable CPU per attempt can be driven into the ground by unauthenticated requests. Rate-limit before hashing (per account and per source), and size the login service for the hashing cost. NIST's 63B caps consecutive failures on one authenticator at no more than 100; OWASP ties lockout counters to the account, not the IP address.
Account enumeration against usabilityWhere "consistent responses" collides with sign-up
OWASP asks for the same message and the same response time for existing and non-existing accounts at login and at forgot-password. Sign-up is harder: "this email is already registered" tells an attacker the address has an account. The usual answer is to make every sign-up end at "check your inbox", and to send a different email to an existing account ("someone tried to register with your address; sign in or reset here"). The attacker learns nothing from the page; the owner learns something from the inbox.
Timing leaks are subtler than messages. If an unknown account returns before the slow hash runs, the delay reveals which accounts exist. Run a dummy hash with the same parameters on the unknown-account path. For a broker portal, enumeration matters more than it seems: a list of valid broker addresses at brk-north is a ready target list for phishing.
Proofing in a business-to-business portalThe person, the firm, and who carries which risk
A broker portal has two identities to establish: the firm and the person. NIST 800-63A addresses the person. Establishing that a brokerage firm exists and may sell the insurer's products is a business onboarding step (contracts, and any licensing checks the insurer's regulators require). It is a pattern outside the identity standards, and it happens once per firm, not per person.
Once the firm is established, delegated administration hands the per-person decision to the firm: the brokerage's administrator vouches for each broker. The insurer then relies on the brokerage's joiner and leaver process, so the contract should say how fast the brokerage removes leavers, and the portal should make removal one click. With federation the reliance is stronger still: the brokerage's identity provider asserts who signed in, and NIST 63C's federation assurance (FAL) describes how well that assertion is protected (signed, audience-restricted, protected from injection).
Proofing every broker at IAL2 is possible and sometimes required. It adds cost and friction for each person, and it does not answer the membership question. A proofed person can still claim the wrong firm.
Recovery designs comparedSaved codes, recovery contacts, repeated proofing
NIST 63B-4 lists the recovery options and their rules. Saved recovery codes need "at least 64 bits from an approved random bit generator", are stored hashed and invalidated after use. Issued codes have short validity: 10 minutes by text or voice, 24 hours by email. Recovery contacts and repeated identity proofing are the other two methods. At AAL2, one emailed code alone does not restore the account.
The trade-off is support load against attack surface. Saved codes cost nothing to run, and most people lose them. A help desk that resets accounts by phone is the weakest recovery of all unless it follows a scripted proofing step, because the attacker only has to sound convincing. For a broker portal with delegated administration there is a natural recovery contact: the brokerage's administrator can re-invite the broker, which repeats the original grant instead of inventing a weaker one.
In one breath#
Sign-up creates an account; it proves only what its evidence proves. A verified email is control of an inbox, identity proofing (IAL) links an account to a real person, and brokerage membership is a grant that someone trusted for the brokerage makes. Store passwords with a salted slow hash from a maintained library, and design recovery so it restores one lost factor without skipping the others.
The broker u-broker-n1 now has an account whose tenant came from a trusted grant and a password stored safely. The next login, though, has to be remembered between requests: the browser will hold something that stands for the broker, and anything a script on the page can read, an attacker can read too. That is the job of Sessions and browser security.