본문으로 건너뛰기

Setup

1. Create a Passport Client​

You will need to create and configure a passport client for each application type (e.g. a mobile app, a website) where you intend to use Passport. If you haven't already setup a project in Immutable Hub, login and add a new project from the dashboard.

When you add a project you will need to name it and choose whether your project will run on Immutable zkEVM or Immutable X. You then need to choose whether your project will run on Testnet or Mainnet and name the environment.

Once your project and environment are setup, navigate to its Passport Configuration page and add a new client. You will need choose the Application Type (Native or Web), then add your Application Name, a Redirect URL and a Logout URL to save the client.

Configuring your Passport client

There are a few crucial details that must be provided when adding a client:

PropertyDescription
Application TypeThe type of your application. Available types: Website / Native (e.g. Mobile App, Desktop Game)
Application NameThe name you wish to use to identify your application inside Passport.
Redirect URLsThe URL that your users will be redirected to once the authentication is complete. This is also where your application process the authentication response.
Logout URLsThe URL that your users will be redirected to upon logging out of your application.
Web Origins URLsThe URLs that are allowed to request authorisation. This field is available when you select the Native application type.

For example, if you're developing a wesbite locally, your Redirect and Logout URLs may be something like; http://localhost:3000/redirect and http://localhost:3000/logout respectively.

2. Configure Passport​

Install Immutable's JS/TS SDK
Prerequisite: Node Version 20 or later
Immutable's Typescript SDK requires **Node v20** (Active LTS version) or **higher**. Node v20 can be installed via `nvm`.

To install nvm follow these instructions. Once installed, run:

nvm install --lts

Immutable's Web SDK is written in TypeScript and we recommend using a TypeScript framework, preferrably React, to build your web application.

In the terminal, navigate to the root directory of your web application and install the following dependencies using your preferred package manager.

npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node

To enable code splitting (importing only the SDK modules you need) there are additional prerequisites.

Next, we'll need to initialise the Passport client inside your application as follows:

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
  }
});
노트

Examples on how to integrate Passport with common web frameworks and 3rd party libraries are available here.

More detail on each of the fields:

FieldDescription
publishableKeyPublishable Keys are used to identify your integration for tracking and analytics purposes. You can find it by logging into Immutable Hub, choosing your Project and Environment then navigating to the API Keys page.
clientIdClient IDs are used to identify your the passport client you wish to use in this integration. You can find it by logging into Immutable Hub, choosing your Project and Environment then navigating to Passport Configuration page.
redirectUriThe URI of your application that users will be redirected to after successfully authenticating. This value must match one of the Redirect URLs that have been set in your Immutable Hub's Passport Configuration for the Passport client you are wanting to integrate. If no value is specified, then Passport will default to the redirect logout mode.
logoutRedirectUriThe URI of your application that users will be redirected to after successfully logging out. This value must match one of the Logout URLs that have been set in your Immutable Hub's Passport Configuration for the Passport client you are wanting to integrate. If no value is specified, then Passport will default to your Passport client's first logout redirect URI.
audienceThe platform_api audience is required for all Passport clients.
scopeThe transact, openid & offline_access scopes are all currently required for all Passport clients. Request the email scope to access the user's email. Learn about scopes here.
popupOverlayOptionsOptions for disabling the Passport overlays that appear when the Passport transaction confirmation pop-up is requested. The overlays are designed to help the user focus the pop-up or open the pop-up when Passport detects the pop-up was blocked. There are two Passport pop-up overlays, a generic overlay that is always shown when the pop-up opens and an overlay that appears when the pop-up has been blocked. Each overlay has a separate option to disable depending on whether you want to show both overlays, only the blocked overlay or disable the blocked overlay to implement a custom solution for handling blocked pop-ups.

Troubleshooting​

Error CodeCauseResolution
INVALID_CONFIGURATIONThe environment configuration or OIDC Configuration is incorrectVerify that you are passing an environment configuration and OIDC configuration, and that all the mandatory properties have been set

3. Use Passport​

Passport is now setup in your application, you are now ready to explore:

  1. Passport identity where you will walk you through the different authentication methods Passport supports
  2. Passport wallet where you will learn how to interact with the Passport wallet