MiscellaneousAuth Options

Working with accounts vs delegations

Users will connect to your dApp by providing one of the following:

  1. An account object or
  2. A delegation object

The differences can be summarized in the table below:

Auth optionWallet addressWallet approval pop-up for executing calls to your canistersWallet approval pop-up for executing calls to other canisters
AccountGlobalYesYes
Account DelegationGlobalNoYes
Relying Party DelegationUnique to dApp URLNoNo

Account objects are wallet addresses with standard web3 interactivity, namely that every call will require explicit user approval to execute.

Delegations are accounts with the authority to execute transactions on the user’s behalf, resulting in the removal of wallet approval pop-ups. A simple example is “Alice delegates to you the ability to execute calls to smart contract canisters A, B, and C on her behalf”.

The example above is what’s called an “Account Delegation” where Alice connects with her wallet address and gives your dApp permission to execute calls as herself only to a whitelist of smart contract canisters as per ICRC-28. Calls made to smart contract canisters outside the whitelist will result in a wallet approval pop-up for that user.

If you wish to remove all wallet pop-ups, you may request a delegation without a whitelist. This global permission allows you to execute any smart contract canister call on behalf of the user, but since you could theoretically execute sensitive transactions without explicit user permission (i.e. transfer assets), wallets will generate delegations with a wallet address unique to your application’s URL, hence the name for this type of delegation: “Relying Party Delegation”. This means you will not know Alice is the one authenticating, since the wallet address for this delegation will be unique to your dApp’s URL and never be seen again across the rest of the ICP ecosystem.

Accounts

Consider requesting a user’s account when building dApps that:

  • Look up account balance/data, and
  • Are meant to give users the highest degree of security and autonomy
AdvantagesDisadvantages
Simple integrationWallet prompts can be confusing for new Web3 users
Enables interoperability of data and assets across ecosystemWould require a user signature to authenticate ownership of address
Familiar Web3 experience

Usage

Add the authType={IdentityKitAuthType.ACCOUNTS} prop.

const App = () => {
  return (
    <IdentityKitProvider authType={IdentityKitAuthType.ACCOUNTS} {...etc}>
      <YourApp />
    </IdentityKitProvider>
  )
}

Account Delegations

Consider requesting a user’s Account Delegation when building dApps that:

  • Look up account balance/data, and
  • Remove wallet approval pop-ups when making calls to smart contract canisters under your dApp’s control (i.e. for chat and other social applications that save profile data)
AdvantagesDisadvantages
No wallet approval pop-ups for canisters under your controlSlightly more integration effort
Enables interoperability of data and assets across ecosystem
Familiar Web3 experience

Usage

Add the authType={IdentityKitAuthType.DELEGATION} prop and add the targets=[""] to signerClientOptions prop with a list of canister IDs and follow the guide to remove wallet approval pop-ups.

const App = () => {
  return (
    <IdentityKitProvider authType={IdentityKitAuthType.DELEGATION} signerClientOptions={{targets=[""]}} {...etc}>
      <YourApp />
    </IdentityKitProvider>
  );
};

Relying Party Delegations

Consider requesting a user’s relying party delegation when building dApps that:

  • Are meant to give users isolated profiles from other dApps on the network
AdvantagesDisadvantages
No wallet pop-upsUsers are isolated from the rest of the ecosystem by default
More effort to make data interoperable across ecosystem

Usage

Add the authType={IdentityKitAuthType.DELEGATION} prop.

const App = () => {
  return (
    <IdentityKitProvider authType={IdentityKitAuthType.DELEGATION} {...etc}>
      <YourApp />
    </IdentityKitProvider>
  )
}