MATIH Platform is in active MVP development. Documentation reflects current implementation status.
15. Workbench Architecture
Control Plane UI
Authentication Pages

Authentication Pages

The Authentication Pages provide the login, registration, multi-factor authentication, and password reset interfaces for the Control Plane UI. These pages integrate with the IAM Service for credential validation, token management, and session lifecycle.


Pages

PageRoutePurpose
Login/auth/loginEmail/password authentication
Register/auth/registerNew user registration (invite-only)
MFA/auth/mfaMulti-factor authentication challenge
Password Reset/auth/reset-passwordRequest and confirm password reset
SSO Callback/auth/sso/callbackOAuth2/OIDC SSO redirect handler

Login Flow

The login page supports multiple authentication methods:

interface LoginRequest {
  email: string;
  password: string;
  remember_me?: boolean;
}
 
interface LoginResponse {
  access_token: string;
  refresh_token: string;
  user: {
    id: string;
    email: string;
    name: string;
    roles: string[];
    tenant_id: string;
  };
  mfa_required: boolean;
}

Authentication Methods

MethodConfigurationDescription
Email/PasswordDefaultStandard credential authentication
SSO (OIDC)Per-tenantEnterprise SSO via OpenID Connect
SSO (SAML)Per-tenantEnterprise SSO via SAML 2.0
API KeyService accountsNon-interactive service authentication

MFA Support

When MFA is enabled for a user, the login flow redirects to the MFA challenge page:

MFA MethodDescription
TOTPTime-based one-time password (Google Authenticator, Authy)
SMSOne-time code sent via SMS
EmailOne-time code sent via email
Recovery codesPre-generated backup codes

Token Management

Tokens are managed through the shared API client:

// Token storage in HTTP-only cookies (not localStorage)
const setTokens = (access: string, refresh: string) => {
  document.cookie = `access_token=${access}; Secure; SameSite=Strict; Path=/`;
  document.cookie = `refresh_token=${refresh}; Secure; SameSite=Strict; Path=/`;
};
 
// Automatic token refresh
apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401) {
      const newTokens = await refreshToken();
      return apiClient.request(error.config);
    }
    throw error;
  }
);

Registration

Registration is invite-only in multi-tenant mode. An administrator sends an invitation which generates a time-limited registration link:

interface RegistrationRequest {
  email: string;
  password: string;
  name: string;
  invitation_code: string;
}

Password Reset

The password reset flow uses a two-step process:

  1. Request: User submits email address, receives reset link
  2. Confirm: User clicks link, sets new password with the reset token

Security Considerations

FeatureImplementation
CSRF protectionSameSite cookies + CSRF token header
Brute force protectionRate limiting on login attempts (5 per minute)
Password policyMinimum 12 characters, complexity requirements
Session timeoutConfigurable idle timeout (default 30 minutes)
Secure storageTokens in HTTP-only cookies, never localStorage