Alternative frontend origins
If your application has reached the stage where you want to change domain names, and you have been authenticating with Internet Identity (II), you will want to make sure that your users can seamlessly keep the same principals they have already been using. To support this functionality, you can configure your application for alternative frontend origins using this guide.
You may need this guide if you are doing any of the following:
- Moving from
<canister-id>.icp0.ioto a custom domain.
- Asking users to login at
- Supporting users using
- Configuring multiple apps in your organization to use the same principals.
Currently, a maximum of 10 alternative origins can be listed.
II will only follow this specification when the origin configuring these alternatives is hosted on a canister using certified assets.
For more information, see the Internet Identity specification.
Configuring alternative origins
For this example, you will have two domains, A and B. A will be the canonical origin, and B will be the alternative domain. To help illustrate this model, consider this website, which is hosted both at https://internetcomputer.org and https://hwvjt-wqaaa-aaaam-qadra-cai.icp0.io.
In this example, A would be the canister ID, or https://hwvjt-wqaaa-aaaam-qadra-cai.icp0.io.
B would be the alternative origin, or https://internetcomputer.org.
For origin A, you will need to provide a file that tells Internet Identity that B is a valid origin. You'll be placing the config files in
src/assets directory of your frontend canister. If your frontend canister is currently configured to deploy assets from a
dist folder, make sure to update the
sources for your canister to include both:
src/assets, create a
.well-known folder, and add a file named
The file needs to exactly be named
ii-alternative-origins, with no file extension. The content inside will be formatted as JSON, but the file should not end with
Inside of the file, list your alternative origin for B. It will look something like this:
Make sure that you remove any trailing slash or query parameters from the origin
Now, your project should look something like this:
│ ├── assets
│ │ ├── .well-known
│ │ │ └── ii-alternative-origins
Configuring your frontend canister
Because the dot syntax in
.well-known ordinarily will be treated as "hidden" by the file system, the frontend canister will need to be configured to upload your document. To configure the frontend canister, create a new file,
.ic-assets.json needs to be placed inside a directory listed in
sources for your canister, so you can use
src/assets again. Your new list of files should look like this:
│ ├── project_frontend
│ │ ├── src
│ │ │ ├── .ic-assets.json
│ │ │ ├── .well-known
│ │ │ │ └── ii-alternative-origins
Then, configure the
.well-known directory to be included, with:
This includes a general rule to not ignore the
.well-known directory, and rules to deliver the
ii-alternative-origins with access control and content-type headers.
Then, all you need to do is deploy your canister. When you attempt to authenticate from origin B from then on, you will get back the same principal you get while using A.