Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v16 or higher)
  • SQL Server (Microsoft SQL Server or Azure SQL Database)
  • Azure AD tenant with an app registration
  • Git for cloning the repository

​
Get Started

Follow these steps to get the backend API running on your local machine.
1

Clone the repository

Clone the project repository to your local machine:
git clone <repository-url>
cd portal-selfservice-backend
2

Install dependencies

Install all required npm packages:
npm install
The project uses the following key dependencies:
  • Express (v5.1.0) - Web framework
  • mssql (v12.0.0) - SQL Server driver
  • Sequelize (v6.37.7) - ORM for database operations
  • Socket.io (v4.8.3) - Real-time notifications
  • express-oauth2-jwt-bearer (v1.7.1) - Azure AD authentication
3

Configure environment variables

Create a .env file in the root directory with the following configuration:
# Database Configuration
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_SERVER=your_server.database.windows.net
DB_DATABASE=your_database_name
DB_PORT=1433

# Azure AD Configuration
AZURE_ISSUER_BASE_URL=https://login.microsoftonline.com/your-tenant-id/v2.0
AZURE_AUDIENCE=api://your-app-id

# Server Configuration
PORT=3000
FRONTEND_URL=http://localhost:5173
Replace the placeholder values with your actual credentials. Never commit the .env file to version control.
4

Configure Azure AD

Set up your Azure AD app registration:
  1. Go to the Azure Portal
  2. Navigate to Azure Active Directory > App registrations
  3. Create a new registration or use an existing one
  4. Configure the following:
    • Application ID URI: Set this as your AZURE_AUDIENCE (e.g., api://your-app-id)
    • Supported account types: Choose based on your requirements
    • API permissions: Configure as needed for your organization
  5. Copy the Tenant ID and Application ID for your .env file
The API uses express-oauth2-jwt-bearer to validate JWT tokens from Azure AD. Tokens must include the correct audience and issuer claims.
5

Start the server

Run the development server:
npm run dev
Or start in production mode:
npm start
You should see:
Conexión a SQL Server establecida.
Servidor escuchando en http://localhost:3000
6

Test the API

Verify the server is running by checking the health endpoint:
curl http://localhost:3000/health
Expected response:
{
  "status": "UP",
  "message": "Express Server Running"
}

​
Make Your First Authenticated Request

Once you have an Azure AD access token, you can make authenticated requests: 
curl -X GET http://localhost:3000/api/solicitudes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Replace YOUR_ACCESS_TOKEN with a valid JWT token from Azure AD. The token must have the correct audience (AZURE_AUDIENCE) configured in your .env file.

​
API Documentation

The API includes interactive Swagger documentation. Once the server is running, visit: 
http://localhost:3000/docs
This provides a complete reference of all available endpoints with request/response schemas.

​
Development Mode

For development, use nodemon to automatically restart the server on file changes: 
npm run dev

​
Next Steps

Architecture

Learn about the system architecture and design patterns

API Reference

Explore all available endpoints and their documentation

Authentication

Deep dive into Azure AD authentication flow

Real-time Events

Learn how Socket.io powers real-time notifications

​
Troubleshooting

Ensure your SQL Server is accessible and credentials are correct. Check:
  • Database server is running
  • Firewall rules allow connections
  • trustServerCertificate: true is set in the config (src/config/db.config.js:10)
If you receive 401 errors:
  • Verify your Azure AD configuration
  • Ensure the token has the correct audience claim
  • Check that AZURE_ISSUER_BASE_URL matches your tenant
  • Confirm the user exists in the database with matching azure_oid
Update CORS configuration in src/app.js:12-17 to allow your frontend origin.

Build docs developers (and LLMs) love

Get started for freeTalk to us