Skip to content

Latest commit

 

History

History
145 lines (99 loc) · 9.68 KB

README.md

File metadata and controls

145 lines (99 loc) · 9.68 KB

Internet Identity

Canister Tests Rust Frontend checks and lints GitHub all releases

🔗 https://identity.internetcomputer.org • 📜 Specification
―
📚 Forum • 🚑 Report an Issue • 📞 Discord

Internet Identity is an authentication service for the Internet Computer. It is the authentication system that allows hundreds of thousands of users to log in to Dapps like Distrikt, DSCVR and more.

Internet Identity is:

  • Simple: It uses some of the WebAuthn API to allow users to register and authenticate without passwords, using TouchID, FaceID, Windows Hello, and more.
  • Flexible: Integrating Internet Identity in a Dapp (or even Web 2 app) is as simple as opening the Internet Identity's HTTP interface, https://identity.internetcomputer.org, in a new tab. No need to interact with the canister smart contract directly.
  • Secure: Different identities are issued for each app a user authenticates to and cannot be linked back to the user.

For more information, see What is Internet Identity? on internetcomputer.org.

Table of Contents

Getting Started

This section gives an overview of Internet Identity's architecture, instructions on how to build the Wasm module (canister), and finally pointers for integrating Internet Identity in your own applications.

Local Replica

Use the Internet Identity canister in your local dfx project by adding the following code snippet to your dfx.json file:

{
  "canisters": {
    "internet_identity": {
      "type": "custom",
      "candid": "https://github.com/dfinity/internet-identity/releases/download/release-2025-04-04-v3/internet_identity.did",
      "wasm": "https://github.com/dfinity/internet-identity/releases/download/release-2025-04-04-v3/internet_identity_dev.wasm.gz",
      "init_arg": "(opt record { captcha_config = opt record { max_unsolved_captchas= 50:nat64; captcha_trigger = variant {Static = variant {CaptchaDisabled}}}})",
      "remote": {
        "id": {
          "ic": "rdmx6-jaaaa-aaaaa-aaadq-cai"
        }
      },
      "frontend": {}
    }
  }
}

To deploy, run dfx deploy.

To access Internet Identity or configure it for your dapp, use one of the following URLs:

  • Chrome, Firefox: http://<canister_id>.localhost:4943
  • Safari: http://localhost:4943?canisterId=<canister_id>

Note on Apple Silicon

If you are running into build issues on Apple Silicon (specifically, if rollup is trying to access @rollup/rollup-darwin-x64), try using nvm to install node.

Architecture Overview

Internet Identity is an authentication service for the Internet Computer. All programs on the Internet Computer are Wasm modules, or canisters (canister smart contracts).

Architecture

Internet Identity runs as a single canister which both serves the frontend application code, and handles the requests sent by the frontend application code.

💡 The canister (backend) interface is specified by the internet_identity.did candid interface. The (backend) canister code is located in src/internet_identity, and the frontend application code (served by the canister through the http_request method) is located in src/frontend.

The Internet Identity authentication service works indirectly by issuing "delegations" on the user's behalf; basically attestations signed with some private cryptographic material owned by the user. The private cryptographic material never leaves the user's device. The Internet Identity frontend application uses the WebAuthn API to first create the private cryptographic material, and then the WebAuthn API is used again to sign delegations.

For information on how Internet Identity works in more detail, please refer to the following:

Building with Docker

To get the canister (Wasm module) for Internet Identity, you can either download a release from the releases page, or build the code yourself. The simplest way to build the code yourself is to use Docker and the docker-build script:

$ ./scripts/docker-build

The Dockerfile specifies build instructions for Internet Identity. Building the Dockerfile will result in a scratch container that contains the Wasm module at /internet_identity.wasm.gz.

We recommend using the docker-build script. It extracts the Wasm module from the final scratch container.

💡 You can find instructions for building the code without Docker in the HACKING document.

Integration with Internet Identity

The using-dev-build demo shows a documented example project that integrates Internet Identity. For more, please refer to the Client Authentication Protocol section of the Internet Identity Specification to integration Internet Identity in your app from scratch. For a just-add-water approach using the agent-js library (also used by using-dev-build), check out Kyle Peacock's blogpost.

If you're interested in the infrastructure of how to get the Internet Identity canister and how to test it within your app, check out using-dev-build, which uses the Internet Identity development canister.

Stable Memory Compatibility

Internet Identity requires data in stable memory to have a specific layout in order to be upgradeable. The layout has been changed multiple times in the past. This is why II stable memory is versioned and each version of II is only compatible to some stable memory versions.

If on upgrade II traps with the message stable memory layout version ... is no longer supported then the stable memory layout has changed and is no longer compatible.

The easiest way to address this is to reinstall the canister (thus wiping stable memory). A canister can be reinstalled by executing dfx deploy <canister> --mode reinstall.

Getting Help

We're here to help! Here are some ways you can reach out for help if you get stuck:

  • Internet Identity Bug Tracker: Create a new ticket if you encounter a bug using Internet Identity, or if an issue arises when you try to build the code.
  • DFINITY Forum: The forum is a great place to look for information and to ask for help.
  • Support: Create a support request if you'd like to keep things private.

Links