Konfiguracja ticket store i magazynu kluczy Data Protection
📅 2026-11-18 1.15.12.2 👤 dbo ⏳ 8 min.
Spis treści
- Wprowadzenie
- Domyślny ticket store SQL Server
- Magazyn kluczy Data Protection — parametry konfiguracyjne
- Magazyn kluczy Data Protection — system plików
- Magazyn kluczy Data Protection — Redis
- Dostępne źródła certyfikatów
- Uwagi dotyczące wdrożenia z obrazów Docker
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
InMemorysesje 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"
}
}
}
}
}
-
DirectoryPathmoż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.Keyjest niepusty i unikatowy dla środowiska; - certyfikat lub plik PFX jest zamontowany jako
secretalbovolume, 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.