papers/lux-id-did-specification/sections/04-iam-architecture.tex

\section{IAM Architecture}


\subsection{System Overview}

Lux ID is built on a modular architecture supporting multiple authentication protocols:

\begin{figure}[h]
\centering
\begin{verbatim}
+-------------------------------------------------------------+
|                     Lux ID Frontend                         |
|  (React 19 + TypeScript + Radix UI + Black Theme)          |
+-----------------------+-------------------------------------+
                        |
+-----------------------+-------------------------------------+
|                   API Gateway (Beego)                       |
|  - Request routing                                          |
|  - Authentication middleware                                |
|  - Rate limiting & CSRF protection                          |
+-----------------------+-------------------------------------+
                        |
        +---------------+---------------+
        |               |               |
+-------v------+ +------v--------+ +---v----------+
| OAuth/OIDC   | |  SAML/CAS     | | WebAuthn/MFA |
| Controllers  | |  Controllers  | | Controllers  |
+-------+------+ +------+--------+ +---+----------+
        |               |               |
        +---------------+---------------+
                        |
+-----------------------v-------------------------------------+
|                     Business Logic Layer                    |
|  - User Management                                          |
|  - Token Generation/Validation                              |
|  - Permission Enforcement (Casbin RBAC)                     |
|  - Verification (Email, Phone, WebAuthn)                    |
|  - Wallet Authentication (MetaMask, WalletConnect)          |
+-----------------------+-------------------------------------+
                        |
        +---------------+---------------+
        |               |               |
+-------v------+ +------v--------+ +---v----------+
|   MySQL/     | |   Redis       | | Blockchain   |
|  PostgreSQL  | |   (Sessions)  | | (Lux C-Chain)|
+--------------+ +---------------+ +--------------+
\end{verbatim}
\caption{Lux ID System Architecture}
\end{figure}

\subsection{Core Components}

\subsubsection{Backend (Go/Beego)}

\begin{itemize}
  \item \textbf{Controllers}: Handle HTTP requests for each protocol
  \item \textbf{Objects}: Business logic for users, applications, tokens
  \item \textbf{Authenticators}: Protocol-specific authentication (OAuth, SAML, WebAuthn)
  \item \textbf{IDP Integrations}: Social logins (Google, GitHub, MetaMask)
  \item \textbf{RBAC Engine}: Casbin-based permission enforcement
\end{itemize}

\subsubsection{Frontend (React + TypeScript)}

\begin{itemize}
  \item Modern single-page application (SPA)
  \item Black theme optimized for Lux branding (\#FFD700 gold accents)
  \item Responsive design for mobile and desktop
  \item Real-time session management
\end{itemize}

\subsubsection{Data Layer}

\begin{itemize}
  \item \textbf{SQL Database}: User profiles, organizations, applications, permissions
  \item \textbf{Redis}: Session storage, rate limiting counters, temporary tokens
  \item \textbf{Blockchain}: DID registry, credential attestations (optional)
\end{itemize}

\subsection{Multi-Protocol Support}

\subsubsection{OAuth 2.0 \& OpenID Connect}

Full implementation of OAuth 2.0 \cite{rfc6749} and OIDC \cite{oidc} flows:

\begin{itemize}
  \item Authorization Code Flow (with PKCE)
  \item Implicit Flow
  \item Client Credentials Flow
  \item Resource Owner Password Credentials Flow
  \item Device Authorization Flow
\end{itemize}

\textbf{Supported Endpoints}:
\begin{lstlisting}[language=bash]
GET  /authorize               # Authorization endpoint
POST /token                   # Token endpoint
GET  /userinfo                # UserInfo endpoint
GET  /.well-known/openid-configuration  # Discovery
GET  /.well-known/jwks.json   # JSON Web Key Set
\end{lstlisting}

\subsubsection{SAML 2.0}

Supports both Identity Provider (IdP) and Service Provider (SP) roles:

\begin{itemize}
  \item Single Sign-On (SSO)
  \item Single Logout (SLO)
  \item Attribute statements (custom claims)
  \item POST and Redirect bindings
\end{itemize}

\subsubsection{LDAP \& RADIUS}

Enterprise integration via:
\begin{itemize}
  \item LDAP server for directory queries
  \item LDAP sync for importing users from Active Directory
  \item RADIUS server for VPN/Wi-Fi authentication
\end{itemize}

\subsubsection{WebAuthn \& FIDO2}

Hardware security key support via WebAuthn \cite{webauthn}:
\begin{itemize}
  \item Registration flow: Challenge -> Credential Creation -> Storage
  \item Authentication flow: Challenge -> Assertion -> Verification
  \item Resident keys for passwordless login
  \item User verification (biometric or PIN)
\end{itemize}

\subsubsection{Web3 Wallet Authentication}

Native blockchain authentication:
\begin{itemize}
  \item \textbf{MetaMask}: Ethereum-compatible wallet via EIP-1193
  \item \textbf{WalletConnect}: Mobile wallet protocol
  \item \textbf{Web3Onboard}: Multi-wallet aggregator
  \item \textbf{Challenge-Response}: Sign nonce to prove ownership
\end{itemize}

\textbf{Authentication Flow}:
\begin{algorithm}
\caption{Web3 Wallet Authentication}
\begin{algorithmic}[1]
\State \textbf{Client}: Request login with wallet address
\State \textbf{Server}: Generate nonce, store in session
\State \textbf{Server}: Return challenge message with nonce
\State \textbf{Client}: Sign challenge with wallet's private key
\State \textbf{Client}: Submit signature to server
\State \textbf{Server}: Recover signer address from signature
\State \textbf{Server}: Verify address matches claimed identity
\State \textbf{Server}: Issue JWT access token
\end{algorithmic}
\end{algorithm}