Authentication

Prima supports three authentication methods. The authentication method is determined automatically based on which configuration sections are present and fully configured.

Supported Authentication Methods

Authentication Priority

When multiple authentication methods are configured, Prima uses this priority order:

1. Okta - If OktaConfiguration is fully configured
2. LDAP - If LdapConfiguration has AuthenticationType: "Ldap" and is fully configured
3. Prima - Default fallback (built-in database authentication)

JWT Token Configuration

JWT tokens are used for API authentication regardless of which authentication method is active.

{
  "JwtTokenSettings": {
    "Secret": "your-secret-key-here-minimum-32-characters",
    "RefreshTokenTTL": 2
  }
}

LDAP / Active Directory Configuration

Configure LDAP authentication to integrate with your organization's Active Directory.

{
  "LdapConfiguration": {
    "AuthenticationType": "Ldap",
    "Host": "ad.company.com",
    "Port": 636,
    "Domain": "company.com",
    "UserStore": "OU=Employees,DC=company,DC=com",
    "Protocol": "LDAPS",
    "AuthType": "Negotiate",
    "Version": 3,
    "TimeOut": "00:01:00",
    "LdapRetryInterval": 1500
  }
}

Required Properties

Optional Properties

Okta Configuration

Configure Okta for cloud-based identity management using OAuth 2.0.

{
  "OktaConfiguration": {
    "Domain": "mycompany.okta.com",
    "ClientId": "0oab1234567890ABC",
    "ClientSecret": "X7aB_cD-eFg_HiJk_lMnOpQrStUvWxYz123456789",
    "AuthorizationServerId": "default",
    "TokenValidationCacheDuration": "00:05:00",
    "ValidateAudience": true,
    "ValidateIssuer": true
  }
}

Required Properties

Optional Properties

Setting Up the Okta Application (Okta Admin Console)

These steps are performed in the Okta Admin Console by your Okta administrator. Prima validates user credentials directly against Okta's token endpoint using the OAuth 2.0 Resource Owner Password grant — users sign in on Prima's own login screen, and Prima verifies the password with Okta behind the scenes. No browser redirect to Okta is involved.

1. In the Okta Admin Console, go to Applications > Applications and click Create App Integration.
2. Select OIDC - OpenID Connect as the sign-in method.
3. Select Web Application as the application type. Prima authenticates as a confidential client and needs both a client ID and a client secret, which this type provides.
4. Give the application a name (for example, Prima).
5. Leave the Sign-in redirect URIs field at its default value (e.g. http://localhost/callback). Because Prima never redirects the user's browser to Okta, redirect URIs are not used — Okta simply requires a value in this field. Do not check the Allow wildcard * in sign-in URI redirect box.
6. Under Assignments, choose which users or groups may use Prima. Users who are not assigned to the application will fail to authenticate.
7. Save the application, then open its General tab and click Edit in the General Settings section.
8. Under Grant type, check Resource Owner Password (it may be listed under Advanced). This step is required — without it, every Prima login will fail even when the credentials are correct.
9. Copy the Client ID and Client Secret from the Client Credentials section and enter them, along with your Okta domain, in the OktaConfiguration section of appsettings.json as shown above.

Cookie Authentication

Configure session cookies for web UI authentication.

{
  "CookieAuthentication": {
    "ExpireTimeSpan": "01:30:00",
    "SlidingExpiration": true
  },
  "CookiePolicyOptions": {
    "Secure": "Always",
    "HttpOnly": "Always",
    "MinimumSameSitePolicy": "Lax"
  }
}

Configuration Examples

Example 1: LDAP with Active Directory

{
  "LdapConfiguration": {
    "AuthenticationType": "Ldap",
    "Host": "ad.company.com",
    "Port": 636,
    "Domain": "company.com",
    "UserStore": "OU=Employees,DC=company,DC=com",
    "Protocol": "LDAPS",
    "AuthType": "Negotiate",
    "Version": 3,
    "TimeOut": "00:01:00"
  },
  "JwtTokenSettings": {
    "Secret": "your-production-secret-key-at-least-32-chars",
    "RefreshTokenTTL": 2
  }
}

Example 2: Okta Cloud Authentication

{
  "OktaConfiguration": {
    "Domain": "mycompany.okta.com",
    "ClientId": "0oab1234567890ABC",
    "ClientSecret": "X7aB_cD-eFg_HiJk_lMnOpQrStUvWxYz123456789",
    "AuthorizationServerId": "default"
  },
  "JwtTokenSettings": {
    "Secret": "your-production-secret-key-at-least-32-chars",
    "RefreshTokenTTL": 2
  }
}

Example 3: Prima Default (Built-in Database)

{
  "LdapConfiguration": {
    "AuthenticationType": "Prima"
  },
  "JwtTokenSettings": {
    "Secret": "your-production-secret-key-at-least-32-chars",
    "RefreshTokenTTL": 2
  }
}

Image Storage

Configure where Prima stores digital images including cassette images, slide images, specimen photos, and scanned documents. Prima supports four storage modes: File (local/network paths), S3 (Amazon S3 or compatible services), Azure Blob (Microsoft Azure Blob Storage), and Advanced (different storage per image type).

Storage Modes Overview

Only one storage mode can be active at a time. Configure one of the following in appsettings.json:

File Storage Mode

The simplest configuration stores all images in subdirectories under a single root path.

{
  "ImageStorage": {
    "File": {
      "RootDirectory": "C:\\ProgramData\\Prima\\Storage"
    }
  }
}

Prima automatically creates subdirectories for each image type:

• CassetteImages/ - Photos of cassettes
• SlideImages/ - Whole slide images
• SpecimenImages/ - Specimen gross photos
• Documents/ - Scanned documents and attachments

S3 Storage Mode

Store all images in an Amazon S3 bucket or S3-compatible service (Digital Ocean Spaces, MinIO, etc.).

Step 1: Define Credential Profiles

First, create one or more credential profiles that can be referenced by storage configurations:

{
  "StorageCredentialProfiles": [
    {
      "Name": "aws-production",
      "AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
      "SecretAccessKey": "${secrets:env:AWS_SECRET_KEY}",
      "Region": "us-east-1",
      "Endpoint": null
    },
    {
      "Name": "digitalocean-spaces",
      "AccessKeyId": "DO00EXAMPLE123",
      "SecretAccessKey": "${secrets:env:DO_SPACES_SECRET}",
      "Region": "nyc3",
      "Endpoint": "https://nyc3.digitaloceanspaces.com"
    }
  ]
}

Step 2: Configure S3 Storage

{
  "ImageStorage": {
    "S3": {
      "CredentialProfile": "aws-production",
      "BucketName": "prima-images",
      "Prefix": "prod/"
    }
  }
}

S3 Settings (Optional)

Configure retry behavior and timeouts for S3 and Azure Blob operations:

{
  "S3Settings": {
    "TimeoutSeconds": 30,
    "MaxRetryAttempts": 3,
    "RetryDelayMilliseconds": 500
  }
}

Azure Blob Storage Mode

Store all images in a Microsoft Azure Blob Storage container.

{
  "ImageStorage": {
    "AzureBlob": {
      "ConnectionString": "${secrets:env:AZURE_STORAGE_CONNECTION_STRING}",
      "ContainerName": "prima-images",
      "Prefix": "prod/"
    }
  }
}

Advanced Storage Mode

Configure different storage locations for each image type. This is useful for hybrid scenarios, such as keeping high-volume slide images in cloud storage while keeping documents on a local network share.

{
  "ImageStorage": {
    "Advanced": {
      "CassetteImage": {
        "Type": "File",
        "Path": "C:\\Storage\\Cassettes"
      },
      "SlideImage": {
        "Type": "S3",
        "CredentialProfile": "aws-production",
        "BucketName": "prima-slides",
        "Prefix": ""
      },
      "SpecimenImage": {
        "Type": "AzureBlob",
        "ConnectionString": "${secrets:env:AZURE_STORAGE_CONNECTION_STRING}",
        "ContainerName": "prima-specimens",
        "Prefix": ""
      },
      "ScannedDocument": {
        "Type": "File",
        "Path": "\\\\server\\share\\Documents"
      }
    }
  }
}

Each image type can be configured as File, S3, or AzureBlob:

File Target

{ "Type": "File", "Path": "C:\\path\\to\\storage" }

S3 Target

{ "Type": "S3", "CredentialProfile": "name", "BucketName": "bucket", "Prefix": "optional/" }

Azure Blob Target

{ "Type": "AzureBlob", "ConnectionString": "...", "ContainerName": "container", "Prefix": "optional/" }

Secret Resolution

To avoid storing sensitive credentials in plain text, use secret resolution syntax for the SecretAccessKey field. Prima supports multiple secret providers:

Configuring Secret Providers

If using Azure Key Vault or AWS Secrets Manager, configure the provider connection:

{
  "SecretProviders": {
    "AzureKeyVault": {
      "VaultUri": "https://my-vault.vault.azure.net/"
    },
    "AwsSecretsManager": {
      "Region": "us-east-1"
    }
  }
}

Complete Configuration Example

Here's a complete example using S3 storage with environment variable secrets:

{
  "StorageCredentialProfiles": [
    {
      "Name": "production-s3",
      "AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
      "SecretAccessKey": "${secrets:env:PRIMA_S3_SECRET_KEY}",
      "Region": "us-east-1",
      "Endpoint": null
    }
  ],
  "ImageStorage": {
    "S3": {
      "CredentialProfile": "production-s3",
      "BucketName": "my-prima-images",
      "Prefix": "production/"
    }
  },
  "S3Settings": {
    "TimeoutSeconds": 30,
    "MaxRetryAttempts": 3,
    "RetryDelayMilliseconds": 500
  }
}

S3-Compatible Services

Prima works with any S3-compatible storage service. Set the Endpoint property to the service's S3 API URL:

Web Server (Kestrel)

Configure the ASP.NET Core Kestrel web server that hosts Prima's web interface and API.

Server Settings

Database Connection

Configure the connection to your SQL Server database.

Connection Settings