Install and initialise

Install and initialise

Before you can begin using Passport, you must install the XpansionChain SDK and initialise the Passport Client. The SDK Passport Module enables games & third-party applications to leverage XpansionChain authentication and wallet functionalities.

Pre-requisites​

• An application registered in the XpansionChain Developer Hub

1. Installing the XpansionChain SDK​

First, add the NPM package as a dependency to your application:

npm install @imtbl/sdk --save
# or
yarn add @imtbl/sdk

2. Initialising Passport​

Next, we'll need to initialise the Passport client. The Passport constructor accepts a PassportModuleConfiguration object, which has the following interface:

interface PassportModuleConfiguration {
  baseConfig: XpansionChainConfiguration;
  clientId: string;
  logoutRedirectUri: string;
  logoutMode?: 'redirect' | 'silent'; // defaults to 'redirect'
  redirectUri: string;
  scope?: string;
  audience?: string;
}

2.1 baseConfig​

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

import { XpansionChainConfiguration, Environment } from '@imtbl/sdk';

const baseConfig = new XpansionChainConfiguration({
  environment: Environment.PRODUCTION,
});

INFO

Note: The environment argument can be one of the following:

Environment Configuration	Description
Environment.SANDBOX	The default test network (currently, it is Goërli)
Environment.PRODUCTION	The Ethereum mainnet network

2.2 clientId​

The unique identifier of the application that was registered in the XpansionChain Developer Hub

2.3 redirectUri​

The URI of your application that users will be redirected to after successfully authenticating. This value must match one of the Callback URLs that have been set against your client in the XpansionChain Developer Hub

2.4 logoutRedirectUri​

The URI of your application that users will be redirected to after successfully logging out. This value must match one of the Logour URL's that have been set against your client in the XpansionChainDeveloper Hub

2.5 audience​

A string containing the audience(s) that the issued token is intended for, with each audience being separated by a space. Passport currently supports the following audiences:

• platform_api: The identifier for the XpansionChain protocol APIs

INFO

Note: The platform_api audience is required in order to interact with the XpansionChain protocol.

2.6 scope​

A string containing the scope(s) that specify what access privileges are being requested, with each scope being separated by a space. The following custom scopes are supported:

• transact: Allows the authenticating application to interact with the users Passport wallet.

In addition to the above, the following standard OIDC scopes are strongly recommended:

• openid: Informs the Authorization Server that the client is making an OpenID connect request.

• offline_access: Requests that an OAuth 2.0 Refresh Token be issued. The Refresh Token is used by Passport during registration to initialise the user's wallet.

• email: Requests that the client gains access to the users email address.

INFO

Note: The transact, openid & offline_access scopes are all currently required to correctly interact with Passport.

2.7 Example initialisation​

import { Environment, XpansionChainConfiguration, Passport } from '@imtbl/sdk';

const passport = new Passport({
  baseConfig: new XpansionChainConfiguration({
    environment: Environment.PRODUCTION,
  }),
  clientId: '<YOUR_CLIENT_ID>',
  redirectUri: 'https://example.com',
  logoutRedirectUri: 'https://example.com/logout',
  audience: 'platform_api',
  scope: 'openid offline_access email transact'
});

Note that the Passport constructor may throw the following error:

Error Code	Cause	Resolution
INVALID_CONFIGURATION	The Environment Configuration or OIDC Configuration is incorrect	Verify that you are passing an Environment Configuration and OIDC Configuration, and that all the mandatory properties have been set

3. Next steps​

You have now successfully installed and initialised the Passport module. Next up you will integrate the login flow into your application.