spa-entra-id/README.md

Single Page Application with Azure Entra ID authentication using MSAL

# SPA with Azure Entra ID Authentication

A modern Single Page Application (SPA) built with TypeScript and Vite that implements Azure Entra ID authentication using the Microsoft Authentication Library (MSAL).

## Features

- 🔐 Azure Entra ID authentication with MSAL
- 🎨 Modern, responsive UI design
- 📱 TypeScript for type safety
- 🚀 Fast development with Vite
- 👤 Microsoft Graph API integration for user profiles
- 🔄 Automatic token refresh handling
- 📦 Available as an npx package for easy deployment

## Quick Start with npx

You can run this application directly with npx (once published):

```bash
npx spa-entra-id
```

This will:
- Automatically build the application if needed
- Start the server on https://localhost:5001
- Open your browser (if configured)

## Development Setup

### Prerequisites

Before running this application, you need to:

1. **Create an Azure App Registration:**
   - Go to [Azure Portal](https://portal.azure.com)
   - Navigate to "Azure Active Directory" > "App registrations"
   - Click "New registration"
   - Set the redirect URI to: `https://localhost:5001/auth.html`
   - Note down the Application (client) ID and Directory (tenant) ID

2. **Configure API permissions:**
   - In your app registration, go to "API permissions"
   - Add Microsoft Graph > Delegated permissions > User.Read

### Local Development

1. **Clone and install dependencies:**
   ```bash
   git clone <repository-url>
   cd spa-entra-id
   npm install
   ```

2. **Configure authentication:**
   - Open `src/config.ts`
   - Replace `YOUR_CLIENT_ID` with your Application (client) ID
   - Replace `YOUR_TENANT_ID` with your Directory (tenant) ID

3. **Start the development server:**
   ```bash
   npm run dev
   ```

4. **Access the application:**
   - Open your browser to `https://localhost:5001`
   - The application will prompt you to sign in with your Azure credentials

## Publishing as NPX Package

To publish this as an npx package:

1. **Build the application:**
   ```bash
   npm run build
   ```

2. **Update package.json:**
   - Set a unique name for your package
   - Update the version number
   - Add your author information

3. **Publish to npm:**
   ```bash
   npm publish
   ```

4. **Users can then run:**
   ```bash
   npx your-package-name
   ```

## Available Scripts

- `npm run dev` - Start development server on port 5001
- `npm run build` - Build the application for production
- `npm run preview` - Preview the built application
- `npx spa-entra-id` - Run the built application (when published)

## Project Structure

```
src/
├── config.ts          # MSAL configuration and settings
├── authService.ts     # Authentication service class
├── uiManager.ts       # UI management and state handling
├── main.ts           # Main application entry point
└── auth.ts           # Authentication callback handler

auth.html             # Authentication redirect URI page
index.html           # Main application page
vite.config.ts       # Vite configuration
```

## Configuration

The application is configured to use:
- **Port**: 5001
- **Redirect URI**: `https://localhost:5001/auth.html`
- **Authentication Method**: Popup flow
- **Token Storage**: Session storage
- **Graph API Endpoint**: User profile (`/me`)

## Security Considerations

- All authentication tokens are stored in session storage
- The application implements proper CSRF protection through MSAL
- Tokens are automatically refreshed when needed
- Proper error handling for authentication failures

## Development

To customize the application:

1. **Modify authentication scopes** in `src/config.ts`
2. **Add new Graph API calls** in `src/authService.ts`
3. **Update UI components** in `src/uiManager.ts`
4. **Configure additional settings** in `vite.config.ts`

## Build for Production

```bash
npm run build
```

The built files will be in the `dist/` directory.

## Troubleshooting

- **Authentication fails**: Check your client ID and tenant ID in config.ts
- **Redirect issues**: Ensure the redirect URI matches exactly in Azure and your config
- **HTTPS issues**: Make sure you're accessing the app via HTTPS in production
- **Token issues**: Clear browser storage and try signing in again

## License

MIT