Enable user login

Enable user login

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.

Pre-requisites​

• Have the Passport module installed and initialised

1. Trigger the login process​

Users will need to log in and accept any scopes that your application has requested before any interactions with their wallet can take place. The login flow is triggered by calling the connectIMX function on the Passport instance:

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

Note that the connectImx 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
WALLET_CONNECTION_ERROR	Passport failed to initialise the Passport wallet	Check your network connection
REFRESH_TOKEN_ERROR	Passport failed to obtain a refresh token	Check your network connection
USER_REGISTRATION_ERROR	Passport failed to register the user with the IMX protocol	Check your network connection

Once the connectIMX function 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. 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 IMX SSO, store the authenticated user in session storage and close the SSO pop-up. At this point, the Promise returned from connectIMX will also resolve with a PassportImxProvder instance, which exposes the majority of the functionality that can be performed for a logged-in user.

3. Maintaining the login status​

If the user refreshes the page, the login status may be lost. To prevent this, you can use the connectImxSilent function to keep the status. The purpose of connectImxSilent is to perform a silent login by verifying the user's login status through their local session and utilizing the refresh token to obtain new accessToken and idToken credentials.

const provider: IMXProvider | null = await passport.connectImxSilent();

The provider will be null if the user is not logged in, or if the refresh token is invalid.

Please note that both the Access Token and the ID Token will expire after 24 and 10 hours respectively. The connectImxSilent method can also handle cases where the token has expired.