Internet Identity

In order to access and interact with applications running on the Internet Computer, it is often necessary for users to authenticate. One of the most commonly used methods to authenticate on the Internet Computer is via Internet Identity.

Internet Identity (II) is a blockchain authentication framework supported by the Internet Computer. Users begin the process by creating identity "anchors" to which they assign compatible cryptographically enabled devices, such as the fingerprint sensor on a laptop, the face ID system on a phone, or a portable HSM, such as a YubiKey or Ledger wallet. Thereafter, they can signup and authenticate to dapps running on the Internet Computer using any of the devices they have assigned to their anchor. This provides a high level of convenience, allowing users to authenticate to dapps with a very low level of friction, yet, while also benefiting from a high level of security and without the need to directly manage or handle cryptographic key material themselves. II offers some degree of privacy for users, by ensuring that whenever an anchor is used to interact with a dapp, the dapp sees a specially generated pseudonym for that dapp, which prevents the dapp from tracking users across the various dapps they use. A user can create as many identity anchors as they wish.

Unlike most authentication methods, users are not required to set and manage passwords or provide any personal identifying information to dapps or to Internet Identity.

How the technology works

Internet Identity builds on Web Authentication (WebAuthn) API supported by modern web browsers and operating systems, and the "chain key cryptography" framework that powers the Internet Computer. Essentially, the Internet Computer signs the list of public keys inside the devices assigned to each anchor using its master chain key, which client side code, for example running in the web browser, is aware of.

Dapps that integrate with Internet Identity prompt the user to authenticate using an identity anchor. If the user doesn't have an identity anchor yet, it is easy to create one and add authentication methods to it. For more details, see How to use Internet Identity. For each device added, a pair of cryptographic keys (private and public key) is generated. The public key is stored on the Internet Computer blockchain, while the private key remains locked inside the authentication device together with any biometric data that governs access to it. Adding multiple authentication devices to an identity anchor allows the user to access dapps across all of their devices.

When a user accesses a dapp that uses Internet Identity for authentication, they first specify the identity anchor they want to use. After authenticating using an identity anchor using an assigned device, their browser connects to Internet Identity and generates a session key for use with that dapp. Finally, the user is asked to authorize access to the dapp.

The user's browser downloads the authorization and then redirects the user to the dapp. The dapp verifies the authorization from Internet Identity and grants the user access as an application-specific anonymous identity called a pseudonym. Internally, users have a different pseudonym for each dapp, but a pseudonym for any single dapp is the same across all of the user's devices. All devices of a particular user simple represent different methods they can use to authenticate their Internet Identity anchor.

A user can register as many identity anchors as they want for redundancy, or different purposes. For example, a user may create an anchor for use with SocialFi or GameFi, and another for use with pure DeFi. They may only feel comfortable adding facial recognition to their SocialFi and GameFi anchor, say, and only use more secure portable HSM devices like YubiKeys and Ledger wallets with their pure DeFi anchor.

Registration

When registering a new identity anchor, the user’s browser first generates a fresh session key pair. Once the user activates their secure device, it generates a fresh key pair that will act as the master key pair for this identity anchor. The secure device then signs a delegation from the master public key master_pk to the session public key session_pk, so that the browser can sign a registration ingress message under session_pk using a delegated signature under the principal SHA224(master_pk) · 0x02.

Note that the secret key corresponding to master_pk never leaves the secure device, while the secret key corresponding to session_pk is kept in browser storage where the same-origin policy shields it from being accessed by other canisters than the II canister. The II canister creates a new II anchor and links the principal to the identity anchor. When the user adds an additional device to the anchor, the II canister adds the principals derived from the master public key of the new device to the anchor.

All subsequent operations for this identity anchor must be authenticated under one of the principals associated with the anchor. The user’s browser will use an existing session key pair if the browser memory for the II canister origin contains one with a valid delegation, or creates a new one by repeating the previous procedure. Note that II does not use local storage for II – that's why the user always has to use biometrics/tap the Yubikey. Once the user closes the tab, the delegation is gone.

Authentication

A single page load can involve multiple signed requests and responses. To avoid a user having to activate their security token for each individual message, the user’s browser will generate a session key pair for each relying canister and have the public key for the session certified by the II canister.

More specifically, when the user visits a relying canister and clicks to login with Internet Identity, the user’s browser generates a fresh session key pair and stores it in the browser storage for the relying canister; refer to the public key as rel_session_pk. The browser is then redirected to the II canister, passing rel_session_pk along by encoding it as part of the URL.

The browser signs an ingress message to log in to the II canister using the authentication procedure above, meaning, re-using a valid session key for the II canister if one exists, or creating a new one if not.

When the user clicks to agree to authenticate to the relying canister, the browser creates a second ingress message to the II canister (also signed with the session public key) that contains the relying canister identity and the relying session public key rel_session_pk

The II canister computes a unique self-authenticating principal for this user anchor and this relying canister as

SHA224(|id_provider| · id_provider · seed) · 02

where the seed is computed based on a secret salt held by the II canister, the user’s identity anchor, and the relying canister as

where anchor is the user’s identity anchor, rel_canister_id is the principal of the relying canister, and seed is a secret seed held by the II canister.

The salt was randomly chosen when the II canister was initialized and is stored in the II canister state. This offers some privacy against canisters that try to track users by linking principals that belong to the same identity anchor. The privacy guarantee does not hold against an adversary who knows the secret seed, though, e.g., a node provider participating in the subnet of the II canister. Note that this only affects privacy, not security: knowledge of the seed does not enable the adversary to impersonate any users.

In its response, the II canister includes the nonce as well as a certified variable (also known as a canister signature) linking the relying canister ID to rel_session_pk and an expiry time. The user’s browser is then redirected to the relying canister, where it signs ingress messages under rel_session_pk.

User experience

[|Internet Identity] does not use passwords and usernames to log in. Internet Identity takes advantage of the Web Authentication (WebAuthn) API to provide secure cryptographic authentication. This means that a user authenticates by "something they have" (e.g a phone, yubikey, etc...) rather than "something they know" (e.g. a password).

From the point of view of the user, a user would use the following methods to authenticate:

Computers
1. Yubikey or Ledger hardware wallet (with computers with USB ports)
2. Thumbprint or face recognition (with computers with electronic fingerprint recognition features like Touch ID or Windows Hello)
Smartphones
1. Face ID (for smartphones with facial recognition systems)
2. Thumbprint (for smartphones with electronic fingerprint recognition features like Touch ID)

Key Features

Ease of Use

Internet Identity provides a secure way for users to generate identity anchors and authenticate to applications running on the Internet Computer without the need to remember and manage passwords.

Privacy

No personal identifying information is needed to generate an anchor and as Internet Identity generates different pseudonyms for different applications, privacy is provided for users as interactions across dapps cannot be tracked.

Availability

Since an anchor's key material is generated and stored on the user's device, it is not the case that a particular service or application can hinder the availability of an individual's anchor as a method of authentication.

Key Concepts

Anchor

An anchor is a number attached to a user's identity. This number is auto-generated by II and there is only one per identity.

Example: 193431

Devices

Users can add many devices to the same identity anchor. A common example is that users may add their smartphone and desktop computer to an identity anchor. It is recommended to add multiple devices in case users lose access to a device. Devices names are chosen by the user and there can be many per identity.

Example:

"Macbook Pro Alice"
"iPhone Alice"

Recovery Mechanisms

In addition to adding multiple devices and using security keys, a user can set up account recovery at the prompt by clicking Add a recovery mechanism to an Identity Anchor.

Seed Phrase

A user can select this option to generate a cryptographically-secure seed phrase that they can use to recover an Identity Anchor. It is important that the user ensures this phrase is stored somewhere safe and is known only to the user, as anyone who knows the seed phrase will be able to take full control of this Identity Anchor. Note that the first string in a user's seed phrase is the Identity Anchor. This number is needed to begin the recovery process.

The user must click the copy button and then continue or the seed phrase will not be registered.

Security Key

A dedicated security key can be used to recover an Identity Anchor in the event that a user loses access to their authorized devices. This key must be different from the ones the user actively used to authenticate to Internet Identity using the given Identity Anchor. This key should be kept somewhere safe and ensure it is available only to the user. As above, anyone in possession of this security key will be able to take full control of the user's Identity Anchor. A user will need to know the Identity Anchor to begin recovery.

Security

Internet Identity is a canister running on the NNS network, so developers can verify it is running the code it is claimed to run. To verify the code, see Verifying the Internet Identity Code: A Walkthrough.

Support

To see current support of WebAuthn, see Webauthn Support.

FAQ

How do I get an Identity Anchor from Internet Identity?

The one and only place to generate an Identity Anchor is to visit https://identity.ic0.app/.

Detailed instructions can be found by visiting https://smartcontracts.org/docs/ic-identity-guide/auth-how-to.html

Do I really need to link another device or save the seed-phrase?

Although it is not necessary, it is really useful to link another device or to save the seed-phrase in case you lose access to your Identity Anchor on a particular device. Further, as your Identity Anchor may be used to generate accounts for wallets or dapps, access to these may also be lost if you lose access to your Identity Anchor.

What happens if I lose my device?

If you lose your device and want to recover, you can click on the 'Lost access and want to recover' link at https://identity.ic0.app/.

If you have an Identity Anchor tied to only one device and you lose that one device, you will be locked out. As a best practice, it is recommend to add multiple devices and recovery mechanisms to every Identity Anchor.

How can I add more devices?

If you want to add another device, you can click on the 'Already have an anchor but using a new device?' link at https://identity.ic0.app/

Detailed instructions can be found here: https://smartcontracts.org/docs/ic-identity-guide/auth-how-to.html#_add_a_device

Does Internet Identity share my personal information with dapps when I authenticate?

No. Internet Identity uses a different Principal (a "pseudonym") for each dapp that you authenticate to using Internet Identity. Since the pseudonyms Internet Identity generates for you are different for each dapp, dapps cannot use them to track you outside of their realm.

Does Internet Identity support Windows Hello?

Yes! Internet Identity supports authenticating via Windows Hello. If Windows Hello is set up on your PC then Internet Identity will offer you to authenticate through Windows Hello.

Detailed instructions can be found here: https://smartcontracts.org/docs/ic-identity-guide/hello-guide.html

Why can't I log in with a new device?

If you can't log in with an existing Identity Anchor, it may be the case that the anchor hasn't been added to the new device. If this is the case, simply visit https://identity.ic0.app/ , click on the 'Already have an anchor but using a new device?' link, add the device and try again.

It may also be the case that the face ID or the fingerprint system is not enabled on the device. Ensure that these are enabled, and try to log in again.

Is there a way to revoke a dapp's access to my Identity Anchor?

There is no explicit revocation method, but privilege delegation to Internet Identity is limited in time, so will expire. Alternatively, simply once the browser tab is closed, the delegation is gone.