Local Testing of Internet Identity with Alternative Frontend Origins

Hello ICP community,

I’m in the process of integrating Internet Identity with several applications. One of these applications is based on the Web2 paradigm and I need to ensure that they share the same principal ID. This is critical for a seamless user experience across both the Web2 and Web3 parts of our ecosystem.

However, there are challenges:

  1. Canister deployment and upgrades: Continuous deployment and upgrading of canisters on the mainnet isn’t feasible for intensive development phases, especially given the rapid iterations we are going through.
  2. Signature verification with local replica: I have found that the production version of Internet Identity cannot be used with a local replica due to the inability to verify the signature.
  3. derivationOrigin constraints: I’m aware from the II specification that the derivationOrigin needs to match a specific regular expression ^https:\/\/[\w-]+(\.raw)?\.(ic0\.app|icp0\.io)$. This poses a challenge for local testing. How can I effectively test Internet Identity with alternative frontend origins locally under this constraint?

To address some of these challenges, I’ve taken several measures:

  1. Local server with domain: I’ve implemented a local server that adopts a specific domain structure using the ${principal}.icp0.io pattern. This domain is configured locally via the /etc/hosts file to map to, ensuring that requests to this domain are routed to the local server.
  2. HTTPS protocol : To match the regular expression requirements of derivationOrigin and to simulate a production-like environment, the server operates on the HTTPS protocol using self-signed certificates.
  3. Serving static files: The server is configured to serve static files from the .well-known/ii-alternative-origins path, which simulates the expected behavior of Internet Identity when it checks for alternative frontend origins.

While this has proven effective in local testing, I’d like to confirm:

  • Is this a valid approach for local testing?
  • Are there any recommended best practices, workarounds, or alternative methods to achieve this?

Thank you in advance!


Hi @vldmkr

Yes, this testing approach sounds reasonable.

For testing the alternative origins feature of II itself, we have a dockerized environment that lets us use the required domains. But modifying the hosts file works too. :+1:


Thank you for your quick and informative reply. I’ve reviewed the Docker setup and the nginx proxy server configuration you provided, and by excluding Selenium from this environment, I found it very close to what I’m looking for. :handshake:

1 Like

Can someone please elaborate on how to use the Docker environment to test ii-alternative-origins locally?

My asset canister is running in a local replica dfx v0.15.0 at http://bkyz2-fmaaa-aaaaa-qaaaq-cai.localhost:8080/. I am trying to use my vite server as an alternative origin.

The .well-known/ii-alternative-origins in the asset canister is set to https://localhost:5173/ (I serve over https with a vite server)
CORS header for ii-alternative-origins is served with wildcard *

After dfx nns install II is served from http://qhbym-qaaaa-aaaaa-aaafq-cai.localhost:8080/

How can I use https://bkyz2-fmaaa-aaaaa-qaaaq-cai.ic0.app (eventual production url for my canister) in agen-js/auth-client as the derivationOrigin?

(I ran the Selenium desktop test from the II repo using Docker, so that works)

Hi @Samer

Have a look at the docker-compose.yml file. The domain names need to listed as aliases there (e.g. nice-name.com in the II test environment).

That way, you will be able to use the domains as the URL for the browser within the Selenium Docker container.

Is it possible to roll out a II dev build that loosens up the security requirements for the derivation origin?

The docker environment with nginx works well for forwarding requests to predefined CANISTER_ID.icp0.io

My app spawns user canisters at docker runtime and I need to forward wildcard pattern *.icp0.io, which needs additional docker containers for custom DNS and what not. (Docker does not support wildcard aliasses in docker compose)

A dev flavor of II could make the II frontend accept http on any domain instead of the currently required pattern. (which is only https and icp0.io / ic0.app domains)

See regex for derivation origin in ii frontend.


Hi @Samer

You can also override DNS resolution in chrome directly. See here.

We have recently replaced the docker based system with that in order to have a lighter weight infrastructure (see this PR).

TLDR: You should be able to forward the request with wildcard pattern to the appropriate canister using the chrome --host-resolver-rules option.

1 Like