Log in users

This page guides you through integrating the login functionality of Passport into your application.

Users are required to log in before the consuming application is able to interact with the user's wallet, or call any user specific functionality.

📋Prerequisites

Have the Passport module installed and initialised

1. Trigger the login process

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.

Ensure that the route you add matches the redirectUri specified in your Passport configuration (e.g., redirectUri: 'http://localhost:3000/redirect').

💡Ensure the hostnames for the login and callback URLs are the same

The hostname for the page initiating the login and the hostname specified in the callback URL must be the same. This is required due to browser security restrictions on localStorage, which Passport uses to manage authentication state. Using different hostnames will result in a "No matching state found in storage" error and prevent login completion.

Your specific implementation will vary based on your application's architecture. In the route defined by redirectUri, run the following code:

Login callbackView on GitHub

passportInstance.loginCallback()

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

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

2. Instantiating the provider

In order to interact with IMX, we'll need to call the connectImx method to instantiate an IMXProvider instance:

const provider: IMXProvider = await passportInstance.connectImx();

The connectImx method will trigger the user authentication process described above in step one (if the user is not already logged in), and initialise the user's wallet. The Promise returned by connectImx will then resolve to an IMXProvider instance.

info

Note: When the connectImx function 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 connectImx is not called before Client-side Rendering has finished. This can be achieved by wrapping the connectImx call with a useEffect hook.

2. Maintaining the login status

When a user authenticates with your application, their session is stored in local storage. This allows us to reauthenticate the user and obtain an instance of the IMXProvider without displaying the authentication popup when the browser, window or page is reloaded. This can be accomplished by calling the login method with the useCachedSession flag set to true:

const userProfile: UserProfile = await passportInstance.login({ useCachedSession: true });
if (userProfile) {
  const provider = await passportInstance.connectImx(); 
}

Please note that both the Access Token and the ID Token will expire after 24 and 10 hours respectively. Calling the login method with the useCachedSession flag set to true can also handle cases where the token has expired.

3. Registering the user with IMX

Now that we have an IMXProvider instance, we need to ensure that the user has been registered with Immutable X. This step only needs to be performed once per user and can be accomplished by calling the registerUserOffchain method on the provider:

const isRegistered = await provider.isRegisteredOffchain();
if (!isRegistered) {
  await provider.registerOffchain();
}

To ensure that the user is provided with adequate feedback, it's recommended that your application shows some indication that the user is being registered with Immutable X.

Note that the registerOffchain method may throw the following errors:

Error Code	Cause	Resolution
USER_REGISTRATION_ERROR	Passport failed to register the user with the IMX protocol	Check your network connection