Printer icon

Konfiguracja ticket store i magazynu kluczy Data Protection

📅 2026-11-18 sygnet.svg 1.15.12.2 👤 dbo ⏳ 8 min.

Spis treści

Wprowadzenie

Od wersji 1.15.12.2 w nAxiom można skonfigurować magazyn biletów uwierzytelniających (ticket store) oraz magazyn kluczy Data Protection. Konfiguracja obu magazynów znajduje się w konfiguracji serwisu Auth. W instalacji klasycznej jest zapisywana w pliku appsettings.json, a w środowisku kontenerowym może być nadpisana w pliku appsettings-custom.json lub za pomocą zmiennych środowiskowych. Po zmianie konfiguracji należy zrestartować serwis Auth. W środowisku wieloinstancyjnym wszystkie instancje Auth muszą korzystać z tego samego magazynu biletów i tego samego magazynu kluczy Data Protection.

Domyślny ticket store SQL Server

Konfiguracja domyślna:

{
  "AppConfiguration": {
    "AuthenticationTicketStore": {
      "Provider": "SqlServer",
      "Cleanup": {
        "Enabled": true,
        "IntervalMinutes": 15,
        "BatchSize": 1000,
        "MaxBatchesPerRun": 100
      }
    }
  }
}
  • bilety są przechowywane w tabeli AuthenticationTickets w schemacie auth (domyślnie; schemat może być skonfigurowany);
  • bilety wygasłe są okresowo usuwane;
  • podczas aktualizacji wersji instalator wykonuje migrację bazy Auth tworzącą tę tabelę;
  • magazyn SQL Server może być współdzielony przez repliki Auth;
  • przy zmianie na InMemory sesje nie przetrwają restartu i nie będą współdzielone przez repliki.

Magazyn kluczy Data Protection — parametry konfiguracyjne

Parametr Dostępne wartości / zakres Domyślnie
Enabled true, false; false pozostawia domyślne zachowanie frameworka false
ApplicationName Niepusty identyfikator aplikacji; wymagany przy Enabled: true Pusty; ustawiany przez instalator
KeyLifetimeDays Liczba całkowita 7–36500 90
Storage.Provider FileSystem, Redis FileSystem
Storage.FileSystem.DirectoryPath Niepusta ścieżka względna lub bezwzględna; wymagana dla FileSystem Pusta
Storage.Redis.Key Niepusta nazwa klucza Redis; wymagana dla Redis Pusta
Protection.Mode None, Dpapi, Certificate None
Protection.Dpapi.Scope CurrentUser, LocalMachine; tylko Windows LocalMachine
Protection.Certificates.Active Obiekt certyfikatu; wymagany dla Certificate null
Protection.Certificates.Previous Tablica certyfikatów używanych do odszyfrowania wcześniejszych kluczy; nie może być null []

Magazyn kluczy Data Protection — system plików

Przykład dla pojedynczego wdrożenia:

{
  "AppConfiguration": {
    "DataProtection": {
      "Enabled": true,
      "ApplicationName": "naxiom.production.auth",
      "KeyLifetimeDays": 90,
      "Storage": {
        "Provider": "FileSystem",
        "FileSystem": {
          "DirectoryPath": "DataProtectionKeys"
        }
      },
      "Protection": {
        "Mode": "Dpapi",
        "Dpapi": {
          "Scope": "LocalMachine"
        }
      }
    }
  }
}
  • DirectoryPath może być względna — jest rozwiązywana względem katalogu aplikacji Auth;
  • konto procesu Auth musi mieć prawo odczytu i zapisu;
  • katalog musi być objęty backupem;
  • przy wielu instancjach katalog musi być współdzielony;
  • DPAPI działa tylko w systemie Windows.

Możliwe jest wyłączenie szyfrowania kluczy podczas przechowywania:

"Protection": {
  "Mode": "None"
}

Nie jest to zalecane jako wariant produkcyjny.

Magazyn kluczy Data Protection — Redis

Przykład:

{
  "AppConfiguration": {
    "RedisConfiguration": {
      "Server": "redis.example.local",
      "Port": 6379,
      "User": "",
      "Password": "",
      "Ssl": true,
      "DefaultDatabase": 0
    },
    "DataProtection": {
      "Enabled": true,
      "ApplicationName": "naxiom.production.auth",
      "KeyLifetimeDays": 90,
      "Storage": {
        "Provider": "Redis",
        "Redis": {
          "Key": "naxiom:production:auth:data-protection"
        }
      },
      "Protection": {
        "Mode": "Certificate",
        "Certificates": {
          "Active": {
            "Source": "Pfx",
            "Path": "/certificates/auth-dp.pfx",
            "Password": "..."
          },
          "Previous": []
        }
      }
    }
  }
}

Hasło do certyfikatu można przekazać jako zmienną środowiskową odpowiadającą ścieżce konfiguracji, np. NAX_AppConfiguration__DataProtection__Protection__Certificates__Active__Password.

Dostępne źródła certyfikatów

Certyfikaty chroniące klucze mogą pochodzić z następujących źródeł:

  • WindowsStore — magazyn certyfikatów systemu Windows (Windows Certificate Store);
  • Pfx — plik PFX (PKCS#12) z certyfikatem i kluczem prywatnym;
  • Pem — plik PEM z certyfikatem i kluczem prywatnym (w formacie PKCS#8).

Certyfikat musi zawierać dostępny klucz prywatny RSA o długości co najmniej 2048 bitów. Przy rotacji certyfikatu bieżący certyfikat trafia do Active, a poprzedni należy tymczasowo pozostawić w Previous, aby możliwe było odszyfrowanie starszych kluczy.

Przykład konfiguracji z sekcją Previous:

"Certificates": {
  "Active": {
    "Source": "Pfx",
    "Path": "/certificates/auth-dp-current.pfx",
    "Password": "<hasło>"
  },
  "Previous": [
    {
      "Source": "Pfx",
      "Path": "/certificates/auth-dp-previous.pfx",
      "Password": "<hasło>"
    }
  ]
}

Uwagi dotyczące wdrożenia z obrazów Docker

Plik appsettings-custom.json jest poprawnym mechanizmem nadpisywania konfiguracji w kontenerze. Jest ładowany po plikach bazowych i zmiennych środowiskowych, więc jego wartości mają pierwszeństwo.

Można w nim skonfigurować:

"AppConfiguration": {
  "DataProtection": { ... },
  "AuthenticationTicketStore": { ... },
  "RedisConfiguration": { ... }
}

Należy jednak mieć na uwadze poniższe uwagi.

Data Protection z FileSystem

Sam plik appsettings-custom.json nie wystarczy. Katalog DataProtectionKeys musi być:

  • zamontowany jako trwały wolumen;
  • współdzielony przez repliki, jeśli działa ich więcej;
  • dostępny z prawami odczytu i zapisu dla procesu Auth.

Bez wolumenu klucze zostaną utracone po usunięciu lub odtworzeniu kontenera.

Data Protection z Redis

appsettings-custom.json może wystarczyć od strony plików konfiguracyjnych, pod warunkiem że:

  • Redis jest osiągalny z kontenera;
  • Redis ma trwałość danych odpowiednią dla danego wdrożenia;
  • poprawnie skonfigurowano RedisConfiguration;
  • Storage.Redis.Key jest niepusty i unikatowy dla środowiska;
  • certyfikat lub plik PFX jest zamontowany jako secret albo volume, jeśli używana jest ochrona certyfikatem.

Ticket store SQL Server

W pliku appsettings-custom.json można zmienić dostawcę, np. na InMemory. Zmiana konfiguracji nie zastępuje migracji wymaganej przez domyślny magazyn SQL Server. Migrację bazy Auth wykonuje instalator podczas aktualizacji nAxiom.

Sekrety

Technicznie można umieścić hasło Redis, hasło PFX lub inne sekrety w appsettings-custom.json, ale dla wdrożeń kontenerowych lepiej używać:

  • secretów Kubernetes/OpenShift;
  • zmiennych środowiskowych z bezpiecznego magazynu;
  • montowanych plików secretów.

Trzeba przy tym uwzględnić, że w obecnym mechanizmie konfiguracji appsettings-custom.json jest ładowany po zmiennych środowiskowych, więc wartości z tego pliku nadpisują wartości środowiskowe.