NFID Docs - Using a Custom Domain

Using a Custom Domain

Anonymous delegations generate new identifiers for each user account <> domain pair. Follow these instructions if you want to ensure the same identifiers are generated across multiple of your domains (i.e. canister domain and human-readable domain):

Ensure you have

agent-js, auth-client, authentication, candid, identity, and principal >= v0.12.1

Ensure your canister

Implements the https_request query call like this (opens in a new tab)

Set the CORS response header

Access-Control-Allow-Origin (opens in a new tab) to allow the NFID origin https://nfid.one

Add alternativeOrigins JSON file

To the https://<canister_id>.ic0.app/.well-known/ii-alternative-origins

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "II Alternative Origins Principal Derivation Origins",
  "description": "An object containing the alternative frontend origins of the given canister, which are allowed to use a canonical canister URL (https://<canister_id>.ic0.app or https://<canister_id>.raw.ic0.app) for principal derivation.",
  "type": "object",
  "properties": {
    "alternativeOrigins": {
      "description": "List of allowed alternative frontend origins",
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 0,
      "uniqueItems": true
    }
  },
  "required": ["alternativeOrigins"]
}

Example:

{
  "alternativeOrigins": ["https://alternative-1.com", "https://www.nice-frontend-name.org"]
}

Add NFID configuration parameters

Add the derivationOrigin key and your frontend's canister URL as the value to the NFID configuration parameters when calling getDelegation

import { Identity } from "@dfinity/agent";
 
const delegationIdentity: Identity = await nfid.getDelegation({
  targets: ["YOUR_CANISTER_ID_1", "YOUR_CANISTER_ID_2", "ETC"], // optional ICRC-28 implementation, but required to support universal NFID Wallet auth
  derivationOrigin, "https://<canister_id>.ic0.app" // optional in case you're running on a custom domain
});

To prevent misuse of this feature, the number of alternative origins must not be greater than 10.

If you use another application as your derivation origin, make sure you trust it completely.

View the Internet Identity specification (opens in a new tab) for more information.

Working with the NFID Wallet Overview