Login and registration

The following guide applies if you're using Passport's identity and wallet system together in your game.

To use Passport in wallet only mode (e.g. if you're a marketplace), see our guide on connecting to Passport.

1. Add the login callback to your application

The first step to enabling user identity in Passport is adding a route to your application that calls the loginCallback method. This method is responsible for processing the response from the IMX SSO, storing the authenticated user in local storage, and closing the SSO pop-up. Your specific implementation will vary based on your application's architecture, but a vanilla Javascript implementation may look as follows:

window.addEventListener('load', function() {
  const passportInstance = new passport.Passport({
    ...
  });

  passportInstance.loginCallback();
});

Once you have added the route, the authentication process can be triggered by initialising the provider and login in.

2. Initialise the provider and login users

💡Passport provider implements EIP-1193 standard

Passport's zkEVM provider implements the Ethereum EIP-1193 standard, which means that you can use the same logic to interact with a user's Passport wallet as you would with any other Ethereum wallet.

As it implements the EIP-1193 standard, you can create a Passport provider and call a range of RPC methods on it directly. Alternatively, you can use the Passport provider in an Ethers.js provider.

Passport (EIP-1193)

Create the Passport provider:

const passportProvider = passport.connectEvm();

Once a provider is created, you can call various methods on it via the request function (which is protocol-agnostic), for example:

const accounts = await provider.request({ method: "eth_requestAccounts" });

See the full range of supported RPC methods.

Ethers.js

Passport is also compatible with existing Ethereum libraries and products.

For example, you may want to use the Passport provider when creating a new provider with Ethers.js, which abstracts the complexity of interacting directly with an EIP-1193 provider. Note that you will still need to call provider.request({ method: "eth_requestAccounts" }) before transacting or signing messages.

import { ethers } from 'ethers';

const passportProvider = passport.connectEvm();

const provider = new ethers.providers.Web3Provider(passportProvider);

const accounts = await provider.request({ method: "eth_requestAccounts" });

and then use the provider as you would any other Ethereum provider:

const signer = provider.getSigner();

The login flow is triggered by calling the requestAccounts RPC on the Passport provider:

Passport (EIP-1193)

If you are using an EIP-1193 provider directly, then you can call the requestAccounts method directly:

const provider = passport.connectEvm();
const accounts = await provider.request({ method: "eth_requestAccounts" });

Ethers.js

import { ethers } from 'ethers';

const passportProvider = passport.connectEvm();
const provider = new ethers.providers.Web3Provider(passportProvider);
const accounts = await provider.send("eth_requestAccounts", []);

Once the requestAccounts RPC method has been called, the Passport module will begin the authentication process if the user is not already logged in. If the user successfully authenticates, then their wallet will be initialised, and the Promise returned by eth_requestAccounts will resolve with an array containing the user's wallet address.

info

Note: When the requestAccounts method is called, an iFrame will be appended to the DOM, which is responsible for securing the user's wallet. Consumers will need to ensure that it is not removed from the DOM by any external process.

For example, if you are using NextJS's Client-side Rendering, it is recommended that requestAccounts is not called before Client-side Rendering has finished. This can be achieved by wrapping the requestAccounts call with a useEffect hook.

3. Authenticating users without wallet

Splitting Authentication and Wallet Creation is Not Recommended.

Whilst possible, we do not recommend you implement authentication only, by doing so you cannot take advantage of web3 mechanics for gameplay and rewarding your users.

Passport is a full web3 solution provisioning users with both identity and wallet needed to play web3 games. Without the wallet component, players won't be able to buy and hold in-game assets on your game. Also, if you want to do pre-registration for your game with coin airdrops or have the ability for players to transact on 3rd party marketplaces, they will need Passport wallets. Passport requires users to be logged-in during wallet creation. This can either be done at login and signup or at some other chosen step you may design into your game. Wallets cannot be created while users are offline.

If you must offer Passport to your users without a wallet follow the instructions below. But remember, if you need wallets for your players later on, you will need to update your code to initialise the provider and tell users to log back in on your application.

Here is how you login uses without wallets. Once you have added the route from section 1, the authentication process can be triggered by calling the optional login method on the Passport instance:

import { passport } from '@imtbl/sdk';

const profile: passport.UserProfile | null = await passportInstance.login();

Note that the login method may throw the following errors:

Error Code	Cause	Resolution
AUTHENTICATION_ERROR	Passport failed to connect to the identity service	Check your network connection and verify that your OIDC Configuration is correct
REFRESH_TOKEN_ERROR	Passport failed to obtain a refresh token	Check your network connection

The login method is considered optional, as the eth_requestAccounts RPC method will also trigger the authentication process if no user is currently logged in.