SP Integration Guide - OnPrem

Setting Up a SharePoint On-Prem for InspectRAG's Keycloak Integration and Event Receivers

1. Introduction

This integration guide provides a step-by-step approach to setting up a SharePoint On-Prem site integrated with Keycloak LDAP for user authentication (for InspectRAG environment) and event receivers to handle file uploads, updates, and notifications. It ensures secure access by linking Active Directory roles with SharePoint and automates event handling through event receivers.

The integration is four-step workflow, as explained below:

2. Prerequisites

SharePoint On-Premises installed and configured.
Administrative access to the SharePoint server.
Active Directory set up with appropriate users and groups.
Keycloak server configured with LDAP integration.
Visual Studio for building event receivers (if creating custom logic).
SharePoint Management Shell installed for deploying solutions.
Public URL (if using webhooks) accessible from the SharePoint server.

3. Step-1: Setting Up a SharePoint On-Prem Site

Access SharePoint Central Administration:
- Log in to the SharePoint server and open Central Administration.
- Navigate to Application Management.
Create a New Site Collection:
- Select Create Site Collections under Manage Web Applications.
- Choose the appropriate Web Application.
Provide Site Details:
- Title: Enter a unique name for the site collection.
- Template: Choose a template (e.g., Team Site).
- Primary Administrator: Assign a site owner.
- Time Zone: Select the appropriate time zone.
Finalize the Setup:
- Click OK to create the site collection.
- Wait for the site collection to be provisioned.

4. Step-2: Configuring Keycloak for Authentication with LDAP and Active Directory

Connect Keycloak to Active Directory via LDAP:
- Access the Keycloak Admin Console and go to User Federation.
- Add a new LDAP provider and enter the following:
  - LDAP URL: Your Active Directory server URL.
  - Bind DN: The user with access to LDAP queries.
  - User DN: The base path in Active Directory (e.g., OU=Users,DC=example,DC=com).
Sync Users and Groups:
- Enable synchronization to import users and groups from Active Directory.
- Set the sync to periodic if you want it to run automatically.
Map Active Directory Roles to Keycloak Groups:
- Configure Group-to-Role Mapping under the LDAP settings.
- Ensure roles and permissions from Active Directory are synchronized to Keycloak.
Configure SharePoint to Use Keycloak for Authentication:
- Set up Keycloak as a trusted identity provider in SharePoint using SAML or OAuth.
- Ensure users logging in via Keycloak have roles mapped to SharePoint permissions.

5. Step-3: Deploying Event Receivers to SharePoint On-Prem

What Are Event Receivers?
- Event receivers in SharePoint allow automated handling of events like file uploads, updates, or deletions.
Deploying an Event Receiver:
- Create your event receiver in Visual Studio or use an existing one.
- Package the event receiver into a WSP (Windows SharePoint Solution) file.
Upload and Deploy the WSP to SharePoint:
- Use SharePoint Central Administration or SharePoint Management Shell to upload and deploy the solution.
- Ensure the event receiver is deployed at the site collection level or list level based on your requirement.
Activate the Event Receiver:
- Navigate to the Site Settings of your site collection.
- Activate the feature linked to the event receiver.

6. Step-5: Deploying InspectRAG SharePoint Solution Package (WSP)

6.1 WSP Deployment Script

InspectRAG provides a SharePoint solution package (.wsp) that includes event receivers and webhook functionality. Use the following PowerShell script to deploy the solution to your SharePoint On-Premises environment.

6.2 Prerequisites for WSP Deployment

SharePoint Management Shell installed and running as Administrator
Farm Administrator permissions on SharePoint
WSP file downloaded from InspectRAG release package

PowerShell execution policy set to allow script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

6.3 Deployment PowerShell Script

Create a PowerShell script file (e.g., Deploy-InspectRAG-SharePoint.ps1) with the following content:

# ===================================================================
# InspectRAG SharePoint On-Prem Deployment Script
# ===================================================================

# === CONFIGURATION ===
# Update these values to match your environment
$wspName = "SharePointProject4.wsp"
$wspPath = "C:\Temp\InspectRAG\$wspName"  # Update to your WSP file location
$siteUrl = "http://your-sharepoint-server/"  # Update to your SharePoint site URL
$featureName = "SharePointProject4_Feature1"  # InspectRAG feature name
$appPoolName = "SharePoint - 80"  # Update to match your app pool name

Write-Host "🚀 Starting InspectRAG SharePoint Solution Deployment..." -ForegroundColor Green
Write-Host "WSP File: $wspPath" -ForegroundColor Yellow
Write-Host "Target Site: $siteUrl" -ForegroundColor Yellow
Write-Host "Feature: $featureName" -ForegroundColor Yellow

# === STEP 1: Verify WSP file exists ===
if (-not (Test-Path $wspPath)) {
    Write-Error "❌ WSP file not found at: $wspPath"
    Write-Host "Please download the InspectRAG SharePoint solution from the release package."
    exit 1
}

# === STEP 2: Recycle IIS App Pool (optional, matches Visual Studio behavior) ===
Write-Host "`n🔄 Recycling IIS Application Pool..." -ForegroundColor Cyan
Try {
    Restart-WebAppPool -Name $appPoolName -ErrorAction SilentlyContinue
    Write-Host "✅ App pool recycled successfully."
} Catch {
    Write-Warning "⚠️ Could not recycle app pool '$appPoolName'. Continuing with deployment..."
}

# === STEP 3: Deactivate Feature (if already activated) ===
Write-Host "`n🔽 Deactivating existing feature..." -ForegroundColor Cyan
Try {
    Disable-SPFeature -Identity $featureName -Url $siteUrl -Confirm:$false -ErrorAction SilentlyContinue
    Write-Host "✅ Feature deactivated successfully."
} Catch {
    Write-Host "ℹ️ Feature not previously activated or already disabled."
}

# === STEP 4: Uninstall existing solution if deployed ===
Write-Host "`n📦 Checking for existing solution deployment..." -ForegroundColor Cyan
$existingSolution = Get-SPSolution | Where-Object { $_.Name -eq $wspName }
if ($existingSolution -and $existingSolution.Deployed) {
    Write-Host "🗑️ Uninstalling existing solution..." -ForegroundColor Yellow
    Uninstall-SPSolution -Identity $wspName -Confirm:$false -Force

    # Wait for uninstallation to complete
    do {
        Start-Sleep -Seconds 2
        $solution = Get-SPSolution | Where-Object { $_.Name -eq $wspName }
        Write-Host "⏳ Waiting for solution to uninstall..." -ForegroundColor Yellow
    } while ($solution.Deployed)

    Write-Host "✅ Solution uninstalled successfully."
}

# === STEP 5: Remove the solution if it exists ===
Write-Host "`n🗑️ Removing existing solution..." -ForegroundColor Cyan
if (Get-SPSolution | Where-Object { $_.Name -eq $wspName }) {
    Remove-SPSolution -Identity $wspName -Confirm:$false
    Start-Sleep -Seconds 5
    Write-Host "✅ Solution removed successfully."
}

# === STEP 6: Add the solution (.wsp) ===
Write-Host "`n📥 Adding new solution..." -ForegroundColor Cyan
Try {
    Add-SPSolution -LiteralPath $wspPath
    Write-Host "✅ Solution added successfully."
} Catch {
    Write-Error "❌ Failed to add solution: $_"
    exit 1
}

# === STEP 7: Install the solution (farm scoped with GAC deployment) ===
Write-Host "`n⚙️ Installing solution..." -ForegroundColor Cyan
Try {
    Install-SPSolution -Identity $wspName -GACDeployment -Force

    # Wait for installation to complete
    do {
        Start-Sleep -Seconds 3
        $solution = Get-SPSolution | Where-Object { $_.Name -eq $wspName }
        Write-Host "⏳ Waiting for solution to install..." -ForegroundColor Yellow
    } while (-not $solution.Deployed)

    Write-Host "✅ Solution installed successfully."
} Catch {
    Write-Error "❌ Failed to install solution: $_"
    exit 1
}

# === STEP 8: Activate the feature on your target site ===
Write-Host "`n🔌 Activating InspectRAG feature..." -ForegroundColor Cyan
Try {
    Enable-SPFeature -Identity $featureName -Url $siteUrl -Force
    Write-Host "✅ Feature activated successfully."
} Catch {
    Write-Error "❌ Failed to activate feature: $_"
    Write-Host "You can manually activate the feature later using:"
    Write-Host "Enable-SPFeature -Identity '$featureName' -Url '$siteUrl' -Force" -ForegroundColor Yellow
}

Write-Host "`n🎉 ====================================================================" -ForegroundColor Green
Write-Host "✅ InspectRAG SharePoint deployment complete!" -ForegroundColor Green
Write-Host "✅ Feature '$featureName' is now activated on $siteUrl" -ForegroundColor Green
Write-Host "🎉 ====================================================================" -ForegroundColor Green

# === STEP 9: Verify deployment ===
Write-Host "`n🔍 Deployment Verification:" -ForegroundColor Cyan
$solution = Get-SPSolution | Where-Object { $_.Name -eq $wspName }
if ($solution.Deployed) {
    Write-Host "✅ Solution Status: Deployed" -ForegroundColor Green
} else {
    Write-Host "❌ Solution Status: Not Deployed" -ForegroundColor Red
}

$feature = Get-SPFeature | Where-Object { $_.DisplayName -like "*InspectRAG*" }
if ($feature) {
    Write-Host "✅ Feature Status: Available" -ForegroundColor Green
} else {
    Write-Host "❌ Feature Status: Not Found" -ForegroundColor Red
}

Write-Host "`n📋 Next Steps:" -ForegroundColor Cyan
Write-Host "1. Configure webhook endpoints in InspectRAG" -ForegroundColor White
Write-Host "2. Test file upload events in SharePoint" -ForegroundColor White
Write-Host "3. Verify event receivers are triggering correctly" -ForegroundColor White

6.4 How to Use the Deployment Script

Download the InspectRAG SharePoint WSP file from the release package

Update the configuration variables in the script:

$wspPath = "C:\Path\To\Your\InspectRAG-SharePoint.wsp"
$siteUrl = "http://your-sharepoint-server/"
$appPoolName = "SharePoint - 80"  # Your app pool name

Run the script as Administrator:

# Open SharePoint Management Shell as Administrator
.\Deploy-InspectRAG-SharePoint.ps1

6.5 Manual Feature Activation (Alternative)

If the automated script fails, you can manually activate the feature:

# Activate feature manually
Enable-SPFeature -Identity "InspectRAG_EventReceiver_Feature" -Url "http://your-sharepoint-server/" -Force

# Verify feature activation
Get-SPFeature -Site "http://your-sharepoint-server/" | Where-Object { $_.DisplayName -like "*InspectRAG*" }

6.6 Troubleshooting WSP Deployment

Permission Issues:

# Ensure you're running as Farm Administrator
Get-SPFarm | Select-Object CurrentUserIsAdministrator

Solution Conflicts:

# List all solutions
Get-SPSolution | Format-Table Name, Deployed, ContainsGlobalAssembly

Feature Activation Issues:

# Check feature status
Get-SPFeature | Where-Object { $_.DisplayName -like "*InspectRAG*" } | Format-List

Event Log Verification:
Check Windows Event Viewer → Applications and Services Logs → SharePoint Products
Look for InspectRAG-related entries

6.7 Uninstalling InspectRAG Solution

To remove the InspectRAG solution:

# Deactivate feature
Disable-SPFeature -Identity "InspectRAG_EventReceiver_Feature" -Url "http://your-sharepoint-server/" -Confirm:$false

# Uninstall solution
Uninstall-SPSolution -Identity "InspectRAG-SharePoint.wsp" -Confirm:$false

# Remove solution
Remove-SPSolution -Identity "InspectRAG-SharePoint.wsp" -Confirm:$false

6.8 Configure InspectRAG API Endpoint in SharePoint Property Bag

After successfully deploying the WSP solution, you need to configure the InspectRAG API endpoint URL in SharePoint's property bag. This allows the event receivers to communicate with your InspectRAG instance.

6.8.1 PowerShell Configuration Script

Use the following PowerShell script to configure the API endpoint:

# Add SharePoint PowerShell snapin
Add-PSSnapin Microsoft.SharePoint.PowerShell

# Get the SharePoint web object (update URL to match your SharePoint site)
$web = Get-SPWeb "http://your-sharepoint-server:port/"

# Set the InspectRAG API URL in the property bag
# IMPORTANT: Update this URL to match your InspectRAG instance
$web.Properties["API_URL"] = "http://your-inspectrag-server:5000/api/SharePointWebhook/documentChange"

# Update the properties and dispose the web object
$web.Properties.Update()
$web.Dispose()

Write-Host "✅ InspectRAG API URL configured successfully in SharePoint property bag" -ForegroundColor Green

6.8.2 Configuration Steps

Update the SharePoint URL:
Replace http://your-sharepoint-server:port/ with your actual SharePoint site URL
Example: http://win-lqk93iqe108:8080/
Update the InspectRAG API URL:
Replace http://your-inspectrag-server:5000 with your actual InspectRAG instance URL
The endpoint /api/SharePointWebhook/documentChange is the webhook receiver for SharePoint events
Example: http://10.0.0.100:5000/api/SharePointWebhook/documentChange

Run the script:

# Open SharePoint Management Shell as Administrator
.\Configure-InspectRAG-API-Endpoint.ps1

6.8.3 Verify Configuration

To verify that the API URL has been set correctly:

# Add SharePoint PowerShell snapin
Add-PSSnapin Microsoft.SharePoint.PowerShell

# Get the SharePoint web object
$web = Get-SPWeb "http://your-sharepoint-server:port/"

# Display the configured API URL
Write-Host "Configured API URL: " $web.Properties["API_URL"]

# Dispose the web object
$web.Dispose()

6.8.4 Example Configuration

Here's a complete example with real values:

# Add SharePoint PowerShell snapin
Add-PSSnapin Microsoft.SharePoint.PowerShell

# Configure for a specific SharePoint site
$web = Get-SPWeb "http://your-site-url/"

# Set InspectRAG API endpoint (update IP/hostname to match your environment)
$web.Properties["API_URL"] = "http://your-rag-api:8002/api/SharePointWebhook/documentChange"

# Apply changes
$web.Properties.Update()
$web.Dispose()

Write-Host "✅ InspectRAG webhook endpoint configured for SharePoint site" -ForegroundColor Green

6.8.5 Important Notes

Network Connectivity: Ensure your SharePoint server can reach the InspectRAG instance on the specified URL
Firewall Rules: Open necessary ports for communication between SharePoint and InspectRAG
HTTPS Support: For production environments, consider using HTTPS endpoints
Multiple Sites: Run this script for each SharePoint site collection that needs InspectRAG integration

6.8.6 Troubleshooting Property Bag Configuration

Check if property was set:

$web = Get-SPWeb "http://your-sharepoint-server:port/"
$web.Properties.Keys | Where-Object { $_ -eq "API_URL" }

List all custom properties:

$web = Get-SPWeb "http://your-sharepoint-server:port/"
$web.Properties | Format-Table

Remove the property (if needed):

$web = Get-SPWeb "http://your-sharepoint-server:port/"
$web.Properties.Remove("API_URL")
$web.Properties.Update()
$web.Dispose()

7. Step-6: Setting Up Webhooks using Event Receivers

How Webhooks Work with Event Receivers:
- When a file is added or updated in SharePoint, the event receiver triggers an action.
- Use the event receiver to send notifications to external systems or process files further.
Configuring the Event Receiver for File Uploads:
- Ensure the event receiver is attached to the Document Library where files are uploaded.
- The event receiver can log details or trigger further workflows (like sending notifications).
Handling Change Notifications:
- Use event receivers to monitor changes in files.
- The event receiver can send alerts or trigger API calls to update external systems (e.g., Keycloak).
Integrate with Keycloak Using Webhooks:
- If a user uploads a restricted file, the event receiver can validate if the user's roles from Keycloak allow the action.

8. Kerberos Authentication Setup and Initialization

8.1 Prerequisites for Kerberos Authentication

Before configuring Kerberos for SharePoint On-Prem integration with InspectRAG, ensure you have:

Active Directory domain controller accessible
Service account with appropriate permissions for SharePoint authentication
DNS resolution properly configured for your SharePoint server
Network connectivity between InspectRAG containers and SharePoint server

8.2 Create Kerberos Configuration File (krb5.conf)

Create the krb5.conf file:
```
sudo nano /etc/krb5.conf
```
Configure the krb5.conf file with your domain settings:
```
                   
```
href="#__codelineno-17-1">[libdefaults] default_realm = YOUR-DOMAIN.COM dns_lookup_realm = false dns_lookup_kdc = false ticket_lifetime = 24h renew_lifetime = 7d forwardable = true rdns = false [realms] YOUR-DOMAIN.COM = { kdc = your-domain-controller.your-domain.com admin_server = your-domain-controller.your-domain.com default_domain = your-domain.com } [domain_realm] .your-domain.com = YOUR-DOMAIN.COM your-domain.com = YOUR-DOMAIN.COM .sharepoint-server.your-domain.com = YOUR-DOMAIN.COM
Set appropriate permissions:
```
sudo chmod 644 /etc/krb5.conf
```

8.3 Configure Environment Variables

Set the following environment variables in your .env file or Docker environment:

# Kerberos Configuration
KRB5_CONFIG_PATH=/etc/krb5.conf
KERBEROS_PRINCIPAL=[email protected]
KERBEROS_PASSWORD=your-service-account-password
KERBEROS_TICKET_LIFETIME=100
KRB5_TICKET_FILE=/tmp/krb5cc_default

# SharePoint On-Prem Configuration
SHAREPOINT_ENABLED=true
SHAREPOINT_HOSTNAME=your-sharepoint-server.your-domain.com
SHAREPOINT_SITE_PATH=/sites/your-site-name

8.4 Initialize Kerberos Ticket

Manual ticket initialization (for testing):
```
kinit [email protected]
```
Verify ticket creation:
```
klist
```

Expected output:

Ticket cache: FILE:/tmp/krb5cc_default
Default principal: [email protected]

Valid starting       Expires              Service principal
MM/DD/YY HH:MM:SS  MM/DD/YY HH:MM:SS  krbtgt/[email protected]

8.5 SharePoint Server Configuration for Kerberos

Set Service Principal Names (SPNs):

setspn -S HTTP/your-sharepoint-hostname domain\serviceaccount
setspn -S HTTP/your-sharepoint-hostname.fqdn domain\serviceaccount

Verify SPNs:
```
setspn -L domain\serviceaccount
```
Configure IIS for Kerberos:
Open IIS Manager and select your SharePoint site
Navigate to Authentication → Windows Authentication
Click Providers and ensure Negotiate is listed above NTLM
In Advanced Settings, uncheck Enable Kernel-mode authentication
Enable Kerberos in SharePoint Central Administration:
Navigate to Manage Web Applications
Select your web application → Authentication Providers
Choose the appropriate zone and enable Windows Authentication with Negotiate (Kerberos)

8.6 Docker Configuration for Kerberos

The Docker Compose configuration automatically handles Kerberos ticket management:

# Volume mounts for Kerberos
volumes:
  - ${KRB5_TICKET_FILE:-/tmp/krb5cc_default}:${KRB5_TICKET_FILE:-/tmp/krb5cc_default}:ro
  - /etc/krb5.conf:/etc/krb5.conf:ro

# Environment variables
environment:
  - KRB5CCNAME=FILE:${KRB5_TICKET_FILE:-/tmp/krb5cc_default}

8.7 Automatic Ticket Renewal

InspectRAG automatically handles Kerberos ticket renewal. To manually renew tickets:

# Renew existing ticket
kinit -R

# Or reinitialize with credentials
kinit [email protected]

8.8 Troubleshooting Kerberos Authentication

Check ticket status:
```
klist -e
```
Common issues and solutions:
Clock skew errors: Ensure time synchronization between client and KDC
DNS resolution: Verify FQDN resolution for SharePoint server
SPN duplicates: Check for duplicate SPNs using setspn -X
Firewall: Ensure ports 88 (Kerberos) and 464 (kpasswd) are open
Enable Kerberos debugging:
```
export KRB5_TRACE=/tmp/krb5_trace.log
```

Verify SharePoint accessibility:

curl -k --negotiate -u : https://your-sharepoint-server.your-domain.com

9. Conclusion

This guide covered the setup of a SharePoint On-Prem site with InspectRAG's Keycloak LDAP integration and event receivers for handling automated file uploads and notifications. With Active Directory roles mapped through Keycloak, users can securely access SharePoint based on their permissions. Event receivers provide the ability to handle file events seamlessly, ensuring real-time processing and secure collaboration.