Skip to main content

MFE Integration Guide

This guide provides a comprehensive overview of the contract between the Citadel Shell Application and any hosted Micro-Frontend (MFE). Adhering to this contract ensures that your MFE will integrate seamlessly with the shell's core services, such as authentication and runtime configuration.

The integration contract consists of three main parts:

  1. The Props Contract: Data and functions passed from the shell to your MFE.
  2. The Routing Contract: How you declare your MFE's routes in the shell's configuration.
  3. The Programmatic API: How your MFE can trigger actions in the shell.

1. The Props Contract​

When the shell loads your MFE component, it passes a rich set of props to give your application the context it needs to render correctly. Your MFE component should be designed to receive these props.

Props Interface​

interface MfeProps {
  // Authentication State
  isAuthenticated: boolean;
  isLoading: boolean;
  error: Error | null;
  user: User | null; // User object from oidc-client-ts

  // Shell Configuration
  config: AppConfig; // The shell's entire runtime config.json

  // Authentication Functions
  login: () => void;
  logout: (args?: SignoutRedirectArgs) => Promise<boolean>;
}

Key Props Explained​

  • isAuthenticated (boolean): true if the user has a valid session. Your MFE should use this to conditionally render protected content.
  • user (object): The decoded user profile from the OIDC ID token. Contains claims like name, email, sub, etc.
  • config (object): The entire runtime config.json object loaded by the shell. This allows your MFE to access shared configuration without making a separate request.
  • logout (function): A function to initiate the user logout process.

2. The Routing Contract​

You register your MFE's routes in the shell's config.json file. The shell's MfeLoader uses this configuration to determine which MFE component to load for a given URL.

Example routes Configuration​

"routes": [
  {
    "path": "/admin",
    "mfe": "adminPortalUi",
    "component": "AdminModule"
  },
  {
    "path": "/reports/*",
    "mfe": "reportingUi",
    "component": "ReportsPage",
    "data": {
      "chrome": "none"
    }
  }
]

Hiding the Shell Chrome​

As shown in the /reports/* example above, you can instruct the shell to hide its minimal UI chrome (the user/logout widget) by adding a data object to your route configuration with the property chrome: 'none'.

This is useful for MFEs that want to provide their own complete UI, including top-level navigation and user menus.

3. The Programmatic API (postMessage)​

For MFEs that need to trigger actions in the shell (especially "chrome-less" MFEs), a postMessage-based API is provided. This ensures a secure, decoupled communication channel.

Triggering Logout​

To programmatically log a user out from your MFE, send a message to the parent window (the shell).

Example:

// Inside a button's onClick handler in your MFE
const handleLogout = () => {
  const message = {
    type: 'citadel:logout',
    // You can optionally pass OIDC signout arguments
    payload: {
      // Example: override the default post-logout redirect
      post_logout_redirect_uri: 'https://my-app.com/goodbye'
    }
  };
  // The targetOrigin should be the shell's origin for security
  window.parent.postMessage(message, 'http://localhost:5000');
};

The shell listens for messages of type citadel:logout and will initiate the logout flow.

Security Note​

The shell will only accept messages from origins that are explicitly listed in the allowedOrigins array in its config.json.

4. Handling Login and Logout Flows​

  • Triggering Login: The recommended way to trigger a login is to navigate to the /login route. Your MFE can do this with a simple link (<a href="/login">) or programmatically.
  • Deep Linking: To redirect a user back to a specific page after login, append a redirect_uri query parameter to the login URL.
    • Example: navigate('/login?redirect_uri=/products/123/edit')
  • Handling Logout: When a user logs out (either via the shell chrome or the postMessage API), the isAuthenticated prop passed to your MFE will change to false. Your MFE should react to this prop change to update its UI accordingly (e.g., show a "You have been logged out" message, disable controls).