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.
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'
).
Your specific implementation will vary based on your application's architecture. In the route defined by redirectUri, run the following code:
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.
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 |