Windows Authentication Setup

Windows Authentication (also called Integrated Windows Authentication or IWA) allows users to log in to RAMP automatically using their Windows domain credentials. Benefits include:

• Seamless SSO — Users are automatically logged in when they access RAMP
• No login prompts — Authentication happens transparently
• Centralized management — Users managed through Active Directory
• Kerberos security — Strong authentication without transmitting passwords

Best For: Internal corporate environments, Windows-based infrastructure, domain-joined machines, IIS-hosted deployments.

Prerequisites

Before you begin, ensure you have:

• Windows Server with Active Directory Domain Services
• IIS (Internet Information Services) installed
• Domain-joined servers for RAMP API hosting
• Service account with Active Directory read permissions
• .NET 10 Runtime installed on the server
• Client machines that are domain-joined

Architecture Overview

+--------------+    Windows Auth     +--------------+
|   Browser    | ------------------> |   RAMP API   |
| (Domain PC)  |  (NTLM/Kerberos)   |   on IIS     |
+--------------+                     +--------------+
                                           |
                                           | LDAP (Optional)
                                           v
                                     +--------------+
                                     |   Active     |
                                     |  Directory   |
                                     +--------------+

---

Quick Start

1. Create Service Account in Active Directory

   Create a dedicated service account for RAMP to run under:

   # PowerShell on Domain Controller
   New-ADUser -Name "RAMP Service" `
              -SamAccountName "ramp-service" `
              -UserPrincipalName "ramp-service@yourdomain.com" `
              -AccountPassword (ConvertTo-SecureString "ComplexPassword123!" -AsPlainText -Force) `
              -Enabled $true `
              -PasswordNeverExpires $true `
              -Description "RAMP Application Service Account"
   
   # Add to Domain Users (minimum required)
   Add-ADGroupMember -Identity "Domain Users" -Members "ramp-service"

   Caution

   Store the service account password securely. You’ll need it for IIS configuration.

2. Configure IIS for Windows Authentication

   Install Windows Authentication Feature

   # Run as Administrator
   Install-WindowsFeature Web-Windows-Auth

   Alternatively, use Server Manager:

   1. Open Server Manager -> Manage -> Add Roles and Features
   2. Navigate to: Web Server (IIS) -> Web Server -> Security
   3. Check Windows Authentication
   4. Click Install

   Create Application Pool

   1. Open IIS Manager (inetmgr)
   2. Navigate to Application Pools -> Add Application Pool
   3. Settings:
      • Name: RAMP
      • .NET CLR Version: No Managed Code (for .NET 10)
      • Managed Pipeline Mode: Integrated
      • Click OK
   4. Right-click the RAMP application pool -> Advanced Settings
   5. Under Process Model -> Identity: Click […]
   6. Select Custom account -> Set…
   7. Enter service account credentials:
      • User name: YOURDOMAIN\ramp-service
      • Password: [service account password]
      • Click OK

   Create or Configure Website

   1. Right-click Sites -> Add Website (or select existing site)
   2. Settings:
      • Site name: RAMP
      • Application pool: Select RAMP pool created above
      • Physical path: C:\inetpub\wwwroot\RAMP (or your deployment path)
      • Binding: https on port 443 with SSL certificate
   3. Click OK

   Enable Windows Authentication

   1. Select your RAMP website in IIS
   2. Double-click Authentication feature
   3. Disable Anonymous Authentication (right-click -> Disable)
   4. Enable Windows Authentication (right-click -> Enable)
   5. Right-click Windows Authentication -> Providers…
   6. Ensure providers are in this order (most secure first):
      • Negotiate (Kerberos)
      • NTLM
   7. Right-click Windows Authentication -> Advanced Settings…
   8. Enable Kernel-mode authentication: Checked
   9. Click OK

3. Configure RAMP Backend

   Update appsettings.json in your RAMP API deployment folder:

   {
     "Authentication": {
       "Providers": {
         "Windows": {
           "Enabled": true,
           "AutoProvision": true,
           "Domain": "YOURDOMAIN.COM"
         }
       }
     },
     "Jwt": {
       "Secret": "YourSecretKeyAtLeast32CharactersLong!",
       "Issuer": "RAMP.API",
       "Audience": "RAMP.Web",
       "AccessTokenExpirationMinutes": 480
     },
     "ConnectionStrings": {
       "DefaultConnection": "Server=sql-server;Database=RAMP;Integrated Security=true;TrustServerCertificate=true"
     }
   }

   Configuration Explained:

   • Enabled: true — Activates Windows authentication provider
   • AutoProvision: true — Automatically creates RAMP user accounts on first login
   • Domain — Your Active Directory domain name

   Caution

   Store Jwt:Secret securely using User Secrets (development) or Azure Key Vault / environment variables (production).

4. Deploy RAMP to IIS

   Publish the Application

   cd src/RAMP.API
   dotnet publish -c Release -o C:\Publish\RAMP

   Copy Files to Server

   Transfer the published files to your IIS server:

   • Source: C:\Publish\RAMP\*
   • Destination: C:\inetpub\wwwroot\RAMP\ (or your configured path)

   Set Folder Permissions

   # Grant service account access to application folder
   icacls "C:\inetpub\wwwroot\RAMP" /grant "YOURDOMAIN\ramp-service:(OI)(CI)F" /T

5. Configure Frontend

   Update .env.production in your RAMP frontend deployment:

   # Disable OIDC (use Windows Auth instead)
   VITE_OIDC_ENABLED=false
   
   # API endpoint (use HTTPS in production)
   VITE_API_BASE_URL=https://ramp.yourdomain.com/api
   
   # Enable credential passing for Windows Auth
   VITE_USE_CREDENTIALS=true

   Note

   The frontend must send credentials with API requests. This is already configured in RAMP’s API client (axios.defaults.withCredentials = true).

6. Configure Kerberos (Recommended)

   For enhanced security, configure Kerberos authentication:

   Create Service Principal Names (SPNs)

   # On Domain Controller or with AD admin rights
   setspn -S HTTP/ramp.yourdomain.com YOURDOMAIN\ramp-service
   setspn -S HTTP/ramp YOURDOMAIN\ramp-service
   
   # Verify SPNs were created
   setspn -L YOURDOMAIN\ramp-service

   Expected Output:

   Registered ServicePrincipalNames for CN=RAMP Service,CN=Users,DC=yourdomain,DC=com:
           HTTP/ramp.yourdomain.com
           HTTP/ramp

   Configure Client Browsers

   For automatic authentication to work, add RAMP to the Local Intranet zone:

   Internet Explorer / Edge:

   1. Internet Options -> Security -> Local intranet -> Sites -> Advanced
   2. Add: https://ramp.yourdomain.com
   3. Ensure “Require server verification (https:) for all sites in this zone” is checked

   Chrome (uses Windows settings):

   • Inherits IE/Edge Local Intranet zone settings

   Firefox:

   1. Navigate to about:config
   2. Set network.negotiate-auth.trusted-uris to https://ramp.yourdomain.com

7. Test the Configuration

   Test from Domain-Joined Machine

   1. Open browser on a domain-joined client computer
   2. Navigate to: https://ramp.yourdomain.com
   3. Expected: You are automatically logged in (no login prompt)
   4. Verify: Your domain username appears in the UI (e.g., “YOURDOMAIN\john.doe”)

   Check Authentication Method

   In browser developer tools:

   1. Open Network tab
   2. Access RAMP
   3. Find the first API request (e.g., /_api/auth/me)
   4. Check Request Headers for:
      • Authorization: Negotiate ... (Kerberos) — Best
      • Authorization: NTLM ... (NTLM) — Acceptable

---

Troubleshooting

Login Prompt Appears (Automatic Auth Not Working)

Problem: Browser shows login prompt instead of automatic authentication.

Solutions:

1. Verify client is domain-joined:

   # On client machine
   systeminfo | findstr /B /C:"Domain"

   Should show your domain, not “WORKGROUP”

2. Add site to Local Intranet zone (see Step 6)

3. Check IE Security Settings:

   • Internet Options -> Advanced
   • Scroll to Security section
   • Ensure “Enable Integrated Windows Authentication” is checked

4. Verify IIS Windows Auth is enabled (see Step 2)

401 Unauthorized Error

Problem: User gets “401 Unauthorized” after attempting authentication.

Solutions:

1. Check service account has AD permissions:

   # Verify account is active
   Get-ADUser -Identity "ramp-service" -Properties Enabled, PasswordNeverExpires

2. Verify IIS application pool identity:

   • IIS Manager -> Application Pools -> RAMP -> Advanced Settings
   • Process Model -> Identity should be YOURDOMAIN\ramp-service

3. Check IIS logs:

   • Location: C:\inetpub\logs\LogFiles\W3SVC1\
   • Look for 401 errors with sub-status codes:
     • 401.1 — Access denied (wrong credentials)
     • 401.2 — Access denied due to server configuration
     • 401.3 — ACL on resource

4. Test service account login:

   • Try logging into the server with the service account credentials
   • Verify it has access to the RAMP folder

User Authenticated But Has No Roles

Problem: User logs in successfully but cannot access any features.

Solutions:

1. Verify user was auto-provisioned:

   • Log in as administrator
   • Navigate to Admin -> Users
   • Search for the user’s domain username

2. Assign roles manually:

   • Find the user -> Assign Roles
   • Add appropriate application roles (e.g., User, Coordinator)

3. Configure Bootstrap Administrators:

   • See Bootstrap Administrators Guide
   • Add users to auto-assign admin roles on first login

Kerberos Not Working (Falling Back to NTLM)

Problem: Authentication works but uses NTLM instead of Kerberos.

Solutions:

1. Verify SPNs are registered correctly:

   setspn -L YOURDOMAIN\ramp-service

   Should show HTTP/ramp.yourdomain.com and HTTP/ramp

2. Check for duplicate SPNs:

   setspn -X

   Duplicates cause Kerberos to fail. Remove duplicates if found.

3. Verify DNS resolution:

   nslookup ramp.yourdomain.com

   Should resolve to correct server IP

4. Check client is requesting Kerberos:

   • Use klist command on client machine
   • Should see ticket for HTTP/ramp.yourdomain.com

5. Enable Kerberos logging:

   # On client machine (run as Administrator)
   reg add "HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters" /v LogLevel /t REG_DWORD /d 1 /f

   Check Event Viewer -> Windows Logs -> System for Kerberos events

---

Security Best Practices

Production Checklist

• Use HTTPS — Install valid SSL certificate
• Dedicated service account — Don’t use personal or shared accounts
• Strong service account password — 20+ characters, rotated regularly
• Least privilege — Service account has read-only AD access
• Kerberos over NTLM — Configure SPNs for Kerberos
• Disable Anonymous Auth — Only Windows Auth should be enabled
• Enable audit logging — Track failed authentication attempts
• Network security — Firewall rules, AD traffic encryption
• Regular updates — Apply Windows and IIS security patches

Service Account Security

Do:

• Use a dedicated service account (not a user account)
• Set “Password never expires” (but rotate manually on schedule)
• Grant only required AD permissions (typically read-only)
• Use strong, unique password (20+ characters)
• Store password in secure vault (Azure Key Vault, etc.)

Don’t:

• Use an administrator account
• Use a personal user account
• Share the account with other applications
• Grant unnecessary AD permissions
• Store password in plaintext configuration files

---

Advanced Configuration

Optional: LDAP Integration for User Search

If you want to enable directory search functionality in RAMP (e.g., searching for users to assign roles), configure LDAP:

{
  "Authentication": {
    "Providers": {
      "Windows": {
        "Enabled": true,
        "AutoProvision": true,
        "Domain": "YOURDOMAIN.COM",
        "Ldap": {
          "Server": "ldap://dc.yourdomain.com:389",
          "SearchBase": "DC=yourdomain,DC=com",
          "ServiceAccount": {
            "Username": "YOURDOMAIN\\ramp-service",
            "Password": "[stored securely]"
          }
        }
      }
    }
  }
}

See LDAP Setup Guide for more details on LDAP configuration.

Optional: Cross-Forest Active Directory

For users in multiple AD forests:

{
  "Authentication": {
    "Providers": {
      "Windows": {
        "Enabled": true,
        "Domains": [
          {
            "Name": "CONTOSO.COM",
            "Ldap": {
              "Server": "ldap://dc1.contoso.com",
              "SearchBase": "DC=contoso,DC=com"
            }
          },
          {
            "Name": "SUBSIDIARY.COM",
            "Ldap": {
              "Server": "ldap://dc1.subsidiary.com",
              "SearchBase": "DC=subsidiary,DC=com"
            }
          }
        ]
      }
    }
  }
}

Note

This requires forest trusts between Active Directory forests.

---

User Provisioning

Automatic User Creation

When a domain user accesses RAMP for the first time:

1. IIS authenticates the user via Windows Authentication
2. User’s identity is passed to RAMP (e.g., YOURDOMAIN\john.doe)
3. RAMP checks if user exists with IdentityProvider = "Windows"
4. If not, RAMP creates a new user account:
   • Username: YOURDOMAIN\john.doe
   • Email: Derived from username (or from LDAP if configured)
   • Display Name: Same as username (or from LDAP if configured)
   • IdentityProvider: Windows
5. User is now logged in but has no roles by default
6. Administrator must assign roles manually (or use Bootstrap Administrators)

---

Alternative: Deploying on Kestrel (Docker/Linux)

Windows Authentication typically requires IIS on Windows Server. However, for Docker deployments:

Tip

Use LDAP Authentication instead, which works cross-platform.

If you must use Windows Auth with Kestrel:

• Deploy on Windows Server (not Linux)
• Configure Kestrel to use Windows Auth (advanced setup)

---

Next Steps

After configuring Windows Authentication:

• Bootstrap Administrators Guide — Auto-assign roles
• MFA Setup — Optionally add MFA for sensitive operations
• Authentication Overview — Compare all authentication providers

---

Related topics

Authentication Overview Compare all authentication methods and choose the right one

ADFS Authentication Setup Configure RAMP with Active Directory Federation Services for federated SSO