Internet Identity and the principal model

A passkey is a WebAuthn credential. The private key is generated and held by the user's device or platform authenticator, and it never leaves it. Authentication is a signature over a challenge, which means there is no shared secret for a server to store and no password to phish. The documentation notes that the identity provider also supports OpenID accounts from major providers, and that the authentication method used is reported back to the application.

The specification distinguishes passkeys from temporary key or PIN identities, which are less secure and generally live only in a browser database. An application can indicate whether it will accept the weaker method, and the documentation recommends against it for anything that matters. That is a useful reminder that the security of the flow depends on which authenticator the user chose, not only on the protocol.

Recovery is the part of any passkey system that deserves scrutiny. The identity provider supports recovery phrases and recovery devices, and the documentation is explicit that losing access to every registered authenticator and recovery method means losing the identity. There is no support desk that can restore it, because there is no account record to restore.

The application does not sign every request with the user's passkey. Instead, the frontend generates a session key pair, and the identity provider issues a delegation that authorises that session key to sign on behalf of the user's identity. The documentation describes the client delegation as signed by the identity provider's canister and carrying a maximum lifetime, with a shorter default. The application then signs its canister calls with the session key, and the network verifies the delegation chain.

A delegation chain can be longer than one link. The specification describes an intermediate delegation from the security device's key to a session key managed by the identity frontend, so that the device is not invoked for every signature. It also describes a pattern for mobile applications in which a proxy frontend holds an intermediate key and issues a second delegation to the mobile app's key, with the chain returned over an app link or a URI fragment.

The documentation is careful about the trust this creates. An intermediate key can impersonate the user, so it must be handled confidentially and should be short-lived. The specification also advises clients to support chains longer than one link and delegations with target restrictions, so that a future version of the protocol does not break them.

Every canister call carries a caller principal, and the backend reads it from the protocol rather than from an argument. The documentation is emphatic on this point: the principal is not passed as a function parameter, because a parameter can be forged by whoever constructs the call. The backend reads the caller from the message context, and any access control is enforced there.

That is the same pattern Bitcoin uses in a different form. A Bitcoin script authorises a spend by checking a signature against a public key; a canister authorises an action by checking the caller principal against a stored list. In both cases the authorisation is derived from the message itself rather than from data the sender supplies alongside it. The canisters page covers the message model that carries the caller.

The documentation also notes a common failure mode: an application that reads the identity before the sign-in flow has resolved will see the anonymous principal, which is a valid principal that represents no user. Treating it as a signed-in user is a bug, and the fix is to wait for the flow to complete rather than to special case the value.