Skip to main content

iFrame Integration Login / Authorization Guide

· One min read
Dimitri Chernykh
Dimitri Chernykh
Software Engineer

Login / Authorization Guide

In this guide, we'll explore how to implement a login/authorization flow for your application integrated with x-bees, focusing on both web and mobile platforms.

Overview​

When integrating your application with x-bees, especially when using Single Sign-On (SSO) providers, it's crucial to handle authentication flows that may involve redirects or opening authorization popups. The complexity increases on mobile devices due to platform-specific constraints.

Authentication Flow for Web​

Flow Diagram​

Flow Overview​

  1. Initial State (/)
  • The app initializes and determines that the user is not authorized.
  • Redirects to the sign-in welcome page (/sign-in).
  1. Sign-In Page (/sign-in)
  • Displays a welcome page with a Sign In button.
  • Clicking the button starts the login flow:
    • Opens a new browser window or popup to initiate SSO.
    • Current page transitions to Awaiting Authorization (/sign-in-awaiting).
  1. Awaiting Authorization (/sign-in-awaiting)
  • Displays a loader and an explanation message.
  • Listens for authorization completion via storage events (e.g., localStorage changes).
  1. SSO Flow (In New Window/Popup)
  • Initiate SSO provider's authentication process.
  • User authenticates with the SSO provider.
  • SSO provider redirects back to your app's callback URL with authorization data.
  1. Completing Authorization
  • The main app (on /sign-in-awaiting) receives the authorization token via storage event.
  • Your app parses the authorization data (e.g., tokens).
  • Save the authorization token (e.g., in localStorage).
  • Notify other app instances (e.g., via storage events or broadcast mechanisms).
  • Call Client.getInstance().isAuthorized() to notify x-bees of successful authentication.
  • x-bees closes the authorization dialog upon receiving the event.
  • The app transitions to the authorized state, and the user can proceed to use the app.
  • During the lifetime if application understands that user lost authorization and flow must start again - call Client.getInstance().isNotAuthorized() to notify x-bees.

Sequence Diagram​

Authentication Flow for Mobile​

Flow Diagram​

Flow Overview​

  1. Initial State (/)
  • The app initializes and determines that the user is not authorized.
  • Redirects to the sign-in welcome page (/sign-in).
  1. Sign-In Page (/sign-in)
  • Display a welcome message and Login page;
    for SSO on mobile, it's recommended to automatically start the login flow without user interaction.
  • Initiates the login flow by redirecting to the mobile device's browser:
    • Uses window.location.replace(url) to open the app URL with an authorization parameter (e.g., ?authorize=true).
    • Current page transitions to Awaiting Authorization (/sign-in-awaiting).
  1. Awaiting Authorization (/sign-in-awaiting)
  • Displays a loader and an explanation message.
  • Listens for authorization completion via onRedirectQuery event.
  1. Authorization Flow in Mobile Browser
  • The app recognizes the authorize=true parameter and opens Sign-In Page
  • Displays a sign-in page with a Sign In button.
  • Clicking the button starts the SSO authentication process.
  • User authenticates with the SSO provider.
  • SSO provider redirects back to your app's callback URL with authorization data.
  1. Returning to x-bees Mobile App
  • After obtaining the authorization token, the app redirects back to the x-bees mobile application using a deep link, passing the token as a query parameter:
    • Example deep link: com.wildix.rnc://integrations?code={code}
  • The x-bees mobile app receives the deep link and extracts the authorization data.
  • Sends a message to the iframe dialog with the provided arguments (e.g., the token).
  1. Completing Authorization
  • The main app (on /sign-in-awaiting) listens for the onRedirectQuery event to receive the authorization data.
  • Your app parses the authorization data (e.g., tokens).
  • Save the authorization token (e.g., in localStorage).
  • Notify other app instances (e.g., via storage events or broadcast mechanisms).
  • Calls Client.getInstance().isAuthorized() to notify x-bees of successful authentication.
  • x-bees closes the authorization dialog upon receiving the event.
  • The app transitions to the authorized state, and the user can proceed to use the app.
  • During the lifetime if application understands that user lost authorization and flow must start again - call Client.getInstance().isNotAuthorized() to notify x-bees.

Sequence Diagram​

Mobile-Specific Considerations​

  • Automatic Flow Initiation: On mobile, it's recommended to start the login flow automatically upon reaching the sign-in page to reduce user friction.
  • Mobile Browser Redirection: Since mobile apps may have limitations opening new windows or popups, use window.location.href to redirect to the device's default browser.
  • Deep Linking: After authentication, use deep link to return to the x-bees app, passing necessary data via query parameters.
  • Event Handling: Use the onRedirectQuery event listener provided by x-bees to receive data from the deep link.

Additional Tips​

  • Security Considerations: Always handle tokens securely. Avoid exposing sensitive data in URLs or logs.
  • Event Handling: Ensure that event listeners like storage events (on web) and onRedirectQuery (on mobile) are properly set up before the events are expected to occur.
  • Error Handling: Implement robust error handling to manage cases where authentication fails or is interrupted.
  • User Feedback: Provide clear messages to the user during each step, especially during waiting periods.