RAMP Native Authentication

RAMP Native Authentication uses RAMP’s built-in user database with username/password login. This is the default authentication method and is ideal for:

• Small to medium teams (< 50 users)
• Getting started with RAMP quickly
• Organizations without existing identity providers
• Scenarios requiring built-in Multi-Factor Authentication (MFA)

Features

• Username/password authentication
• Built-in Multi-Factor Authentication (TOTP)
• Email-based password reset
• Account lockout protection
• Password complexity requirements
• Bootstrap administrator configuration

Prerequisites

• RAMP backend and frontend deployed
• SMTP server access (for password reset emails) — Optional but recommended
• Database connection configured

---

Step 1: Configure JWT Settings

JWT (JSON Web Tokens) are used for session management in RAMP.

Edit appsettings.json

{
  "Jwt": {
    "Secret": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
    "Issuer": "RAMP.API",
    "Audience": "RAMP.Web",
    "AccessTokenExpirationMinutes": 480,
    "RefreshTokenExpirationDays": 30
  }
}

Configuration Reference

Setting	Description	Recommended Value
Secret	Encryption key for JWT tokens (minimum 32 characters)	Random 64+ character string
Issuer	Identifies who issued the token	RAMP.API
Audience	Identifies who can use the token	RAMP.Web
AccessTokenExpirationMinutes	How long access tokens are valid	480 (8 hours)
RefreshTokenExpirationDays	How long refresh tokens are valid	30 (30 days)

Generate a Secure Secret

Linux/Mac

openssl rand -base64 64

Windows PowerShell

[Convert]::ToBase64String((1..64 | ForEach-Object {Get-Random -Maximum 256}))

Caution

Store the JWT secret securely:

• Development: Use ASP.NET Core User Secrets
• Production: Use Azure Key Vault, AWS Secrets Manager, or environment variables

---

Step 2: Configure Bootstrap Administrator (Recommended)

Bootstrap administrators are created automatically on first startup. This ensures you can log in immediately after deployment.

Edit appsettings.json

{
  "Bootstrap": {
    "Administrators": [
      {
        "IdentityProvider": "RAMP",
        "Username": "admin",
        "Email": "admin@yourcompany.com",
        "Password": "Passw0rd"
      }
    ]
  }
}

Configuration Notes

• IdentityProvider: Must be "RAMP" for native authentication
• Username: Choose a username for the administrator
• Email: Valid email address (required for password reset)
• Password: Must meet password requirements (see below)

Danger

Change the password immediately after first login!

Password Requirements

• Minimum 8 characters
• At least 1 digit
• At least 1 lowercase letter
• At least 1 uppercase letter
• At least 1 non-alphanumeric character (!@#$%^&*)

Multiple Bootstrap Admins

You can configure multiple administrators:

{
  "Bootstrap": {
    "Administrators": [
      {
        "IdentityProvider": "RAMP",
        "Username": "admin",
        "Email": "admin@yourcompany.com",
        "Password": "Passw0rd"
      },
      {
        "IdentityProvider": "RAMP",
        "Username": "sysadmin",
        "Email": "sysadmin@yourcompany.com",
        "Password": "SysAdmin@456"
      }
    ]
  }
}

---

Step 3: Configure Email (Optional but Recommended)

Email is required for password reset functionality. See Email Setup Guide for detailed SMTP configuration.

Quick SMTP Configuration

Add to appsettings.json:

{
  "Smtp": {
    "Host": "smtp.gmail.com",
    "Port": 587,
    "EnableSsl": true,
    "Username": "noreply@yourcompany.com",
    "Password": "your-smtp-password",
    "FromAddress": "noreply@yourcompany.com",
    "FromName": "RAMP System"
  }
}

Caution

Store SMTP password in User Secrets or Key Vault, not in appsettings.json.

---

Step 4: Start RAMP

Start Backend

cd src/RAMP.API
dotnet run

Start Frontend

cd src/RAMP.Web
npm run dev

Verify Startup

1. Navigate to http://localhost:5173 (or your configured URL)
2. You should see the RAMP login page
3. Log in with your bootstrap administrator credentials

---

Step 5: First Login and Security Setup

Change Bootstrap Password

1. Log in with bootstrap credentials
2. Navigate to Settings -> Profile
3. Click Change Password
4. Enter current password and new secure password
5. Click Save

Enable Multi-Factor Authentication (Optional)

For maximum security, enable MFA for your administrator account:

1. Navigate to Settings -> Security
2. Click Enable MFA
3. Scan the QR code with an authenticator app:
   • Google Authenticator
   • Microsoft Authenticator
   • Authy
4. Enter the 6-digit code to verify
5. Save your 10 backup codes in a secure location

MFA Setup Guide Detailed MFA enrollment and management instructions

---

Step 6: Create Additional Users

Option 1: Via Web Interface

1. Log in as Administrator
2. Navigate to Admin -> Users
3. Click Create User
4. Fill in user details:
   • Identity Provider: RAMP
   • Username
   • Email
   • Password (will be hashed)
5. Assign roles (e.g., User, SystemManager)
6. Click Create

Option 2: Invite Users (with Email)

1. Navigate to Admin -> Users
2. Click Invite User
3. Enter email address
4. Select roles
5. User receives email with temporary password
6. User must change password on first login

---

Complete Configuration Example

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=RAMP;User Id=ramp;Password=yourpassword;TrustServerCertificate=true"
  },
  "Jwt": {
    "Secret": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
    "Issuer": "RAMP.API",
    "Audience": "RAMP.Web",
    "AccessTokenExpirationMinutes": 480,
    "RefreshTokenExpirationDays": 30
  },
  "Smtp": {
    "Host": "smtp.gmail.com",
    "Port": 587,
    "EnableSsl": true,
    "Username": "noreply@yourcompany.com",
    "Password": "your-smtp-password",
    "FromAddress": "noreply@yourcompany.com",
    "FromName": "RAMP System"
  },
  "Bootstrap": {
    "Administrators": [
      {
        "IdentityProvider": "RAMP",
        "Username": "admin",
        "Email": "admin@yourcompany.com",
        "Password": "Passw0rd"
      }
    ]
  }
}

Secure Secrets Storage

User Secrets (Dev)

cd src/RAMP.API
dotnet user-secrets set "Jwt:Secret" "YourDevSecretKey123456789012345678901234567890"
dotnet user-secrets set "Smtp:Password" "your-smtp-password"
dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Server=localhost;Database=RAMP_Dev;Integrated Security=true"

Azure Key Vault (Prod)

{
  "AzureKeyVault": {
    "Enabled": true,
    "VaultUri": "https://your-ramp-vault.vault.azure.net/"
  }
}

Store these secrets in Key Vault:

• Jwt--Secret
• Smtp--Password
• ConnectionStrings--DefaultConnection

---

Security Features

Account Lockout

• Failed Attempts: 5 failed login attempts trigger lockout
• Lockout Duration: 5 minutes
• Reset: Lockout automatically clears after duration
• Admin Override: Administrators can unlock accounts via Admin -> Users

Password Requirements

Enforced by ASP.NET Core Identity:

• Minimum length: 8 characters
• Requires digit: Yes
• Requires lowercase: Yes
• Requires uppercase: Yes
• Requires non-alphanumeric: Yes
• Allow new users: Yes

Session Management

• Access Token: 8 hours (default)
• Refresh Token: 30 days (default)
• Auto-refresh: Frontend automatically refreshes tokens
• Logout: Revokes refresh token

---

Troubleshooting

Cannot log in with bootstrap administrator

Check 1: Verify password meets requirements

• Minimum 8 characters
• Contains uppercase, lowercase, digit, and special character

Check 2: Check application startup logs

"Bootstrap administrator created: admin"

Check 3: Verify database connection

SELECT * FROM Users WHERE Username = 'admin';

”Invalid credentials” error

Check 1: Verify username and password are correct

• Usernames are case-sensitive
• Ensure no extra spaces

Check 2: Check if account is locked

• Navigate to Admin -> Users -> Find user
• Check “Is Locked Out” status
• Click “Unlock Account” if needed

Check 3: Verify JWT configuration

• Ensure Jwt:Secret is set and at least 32 characters
• Check backend logs for JWT errors

Password reset email not sent

Check 1: Verify SMTP configuration

• Test SMTP credentials with a mail client
• Check firewall allows outbound SMTP connections
• Verify Smtp:EnableSsl matches your SMTP server

Check 2: Check application logs for email errors

Check 3: Verify user has email address

SELECT Email FROM Users WHERE Username = 'username';

Token expired errors

Check 1: Verify system time is correct

• JWT validation is time-sensitive
• Ensure server and client clocks are synchronized

Check 2: Increase token expiration

{
  "Jwt": {
    "AccessTokenExpirationMinutes": 960
  }
}

Check 3: Clear browser storage

• Open browser developer tools
• Clear localStorage and sessionStorage
• Refresh page and log in again

---

Next Steps

• MFA Setup Guide — Enable multi-factor authentication
• Email Setup Guide — Configure SMTP for password resets
• Bootstrap Administrators — Advanced bootstrap configuration