Skip to main content

Integrating Immutable Passport

Estimate time to complete: 15 minutes

A key component of your game integration is to make sure you can onboard users successfully. We’ve created Immutable Passport as the product which provides you with authentication and a web3 wallet out of the box. This tutorial is to set up both the authentication and the wallet component to your game.

onboard usersonboard users

Task 1: Install and initialise Passport

Recall your project that you set up in the Immutable Hub from the previous step. Click on this project and go to "Passport" in the left-hand menu.

Once you've set up, you'll be given a list of endpoints and keys for both website and native app projects.

Setup Passport

From here, you can create default Passport clients or add a client.

Once you have created a Passport client, you will be given a list of endpoints and keys for both website and native app projects.

Setup Passport

Next, we'll need to initialise the Passport client.

Passport - how it works

The Passport constructor accepts a PassportModuleConfiguration object, which has the following interface. Your key variables here are below. Details on other variables can be found in this article.

  • clientId - comes from your Client ID from the Immutable Hub that you just set up
  • logoutRedirectUri - must match one of the Logout URLs in the Immutable Hub that you just set up
  • redirectUri - must match one of the Redirect URLs in the Immutable Hub that you just set up
interface PassportModuleConfiguration {
baseConfig: ImmutableConfiguration;
clientId: string;
logoutRedirectUri?: string; // defaults to first logout redirect URI specified in the Immutable Hub
logoutMode?: 'redirect' | 'silent'; // defaults to 'redirect'
redirectUri: string;
scope?: string;
audience?: string;
}

An instance of an ImmutableConfiguration, which defines shared configuration across all the Immutable modules, such as the environment. This can be initialised as follows:

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

const PUBLISHABLE_KEY = 'YOUR_PUBLISHABLE_KEY'; // Replace with your Publishable Key from the Immutable Hub

const baseConfig = {
environment: config.Environment.PRODUCTION,
publishableKey: PUBLISHABLE_KEY,
};

Putting it altogether, you can copy and paste the following code block to initialise Passport. Pay attention to these variables:

  • clientId - comes from your Client ID from the Immutable Hub that you just set up
  • logoutRedirectUri - must match one of the Logout URLs in the Immutable Hub that you just set up
  • redirectUri - must match one of the Redirect URLs in the Immutable Hub that you just set up
import { config, passport } from '@imtbl/sdk';

const passportInstance = new passport.Passport({
baseConfig: {
environment: config.Environment.SANDBOX, // or Environment.PRODUCTION
publishableKey: '<YOUR_PUBLISHABLE_KEY>', // replace with your publishable API key from Hub
},
clientId: '<YOUR_CLIENT_ID>', // replace with your client ID from Hub
redirectUri: 'https://localhost:3000/redirect', // replace with one of your redirect URIs from Hub
logoutRedirectUri: 'https://localhost:3000/logout', // replace with one of your logout URIs from Hub
audience: 'platform_api',
scope: 'openid offline_access email transact',
popupOverlayOptions: {
disableGenericPopupOverlay: false, // Set to true to disable the generic pop-up overlay
disableBlockedPopupOverlay: false, // Set to true to disable the blocked pop-up overlay
}
});

Task 2: Authenticate users with Passport

This step should take you 5 minutes.

2.1. Initialise the provider

💡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.

Use the eth_requestAccounts method to login users directly with EIP-1193 provider.

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

See the full range of supported RPC methods.

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

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.

2.2. Trigger the login process

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

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' });
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 successfully authenticates, then the user will be redirected to the Redirect URI that was set in the OIDC Configuration.

2.3. Configure the login callback

At this point, the route that handles requests to the Redirect URI will need to call the loginCallback method on page load. Your specific implementation will vary based on your application's architecture, but a vanilla Javascript implementation may look as follows:

window.addEventListener('load', function () {
passport.loginCallback();
});

The loginCallback method will then process the response from the Immutable's auth domain, store the authenticated user in session storage and close the pop-up. Once the authentication flow is complete, the Promise returned from requestAccounts will also resolve with a single-item array containing the user's address.

You might find these articles useful, but you don't need to set this up now.

Task 3: Implement "Sign-in with Immutable" button

We provide default assets for your front-end in order to give your players access to Immutable Passport. Implemented either the dark or light mode option below. You can right click to download the appropriate SVG file.

When to useIn dark mode situationsIn light mode situations
Default sign up and sign in
experiences
In smaller spaces less
than 300px width, you
can use the logo lockup
in button only however
button should be
proceded with the words
"Sign in with"
Sign in with
Sign in with

Additional customisation can be found in this article should you need to do so.