Integracja nAxiom z OpenBao

Wersja nAxiom 1.15.2.0, data publikacji: 2025-10-10

Przeczytasz w 13 min.

W tym temacie

Uruchomienie serwera OpenBao (Windows)

Uruchomienie serwera OpenBao (Docker)

Konfiguracja serwera OpenBao

Konfiguracja połączenia z OpenBao w TenantsAdminSPA

Definiowanie sekretów

Korzystanie z sekretów w aplikacjach biznesowych nAxiom

Uruchomienie serwera OpenBao (Windows)

Poniżej opisano procedurę uruchomienia serwera OpenBao 2.4.1 w trybie produkcyjnym w środowisku Windows.

Pobierz pakiet instalacyjny i rozpakuj go do wybranego folderu w systemie plików.
W utworzonym folderze uruchom wiersz poleceń i uruchom serwer OpenBao:
- na potrzeby eksperymentów można użyć trybu deweloperskiego, jednak w tym trybie wszelkie ustawienia konfiguracyjne i sekrety dodane do OpenBao są przechowywane w pamięci, a każdy restart serwera lub systemu powoduje ich utratę:
```
bao server -dev
```
- Aby uruchomić serwer OpenBao w trybie produkcyjnym z użyciem szyfrowanych połączeń, przygotuj certyfikaty serwera; w przypadku certyfikatów samopodpisanych ustaw zmienną środowiskową VAULT_SKIP_VERIFY (nie jest to rekomendowane w środowiskach produkcyjnych, ponieważ narusza model zabezpieczeń OpenBao).
- Przygotuj plik z konfiguracją uruchomieniową OpenBao, na przykład:
```
{
"ui": true,
"api_addr": "https://127.0.0.1:8200",
"storage": {
  "file": {
    "path": "C:/openbao/data",
  }
},
"listener": {
  "tcp": {
    "address": "127.0.0.1:8200",
    "tls_cert_file": "C:/openbao/certs/tls.crt",
    "tls_key_file": "C:/openbao/certs/tls.key",
    "tls_disable": false
  }
}
}
```
- Uruchom serwer OpenBao:
```
bao server -config config.json
```

Uruchomienie serwera OpenBao (Docker)

Poniżej opisano procedurę uruchomienia serwera OpenBao 2.4.1 w trybie produkcyjnym w środowisku kontenerów. Założono zapis danych w magazynie typu file na dysku (katalog ./data) oraz komunikację przez TLS (certyfikaty serwera w katalogu ./certs).

Wymagana struktura katalogów w katalogu roboczym:

  ├───certs
  │       server.crt
  │       server.key
  ├───config
  │   │   config.json
  ├───data

Plik docker-compose.yaml:

version: '3.8'

services:
  openbao:
    image: openbao/openbao:latest
    container_name: openbao
    ports:
      - "8200:8200"
    volumes:
      - ./data:/openbao/data
      - ./certs:/openbao/certs
      - ./config:/openbao/config
    command: server -config=/openbao/config/config.json
    restart: unless-stopped

Plik config.json:

{
  "storage": {
 "file": {
   "path": "/openbao/data"
 }
  },
  "listener": {
 "tcp": {
   "address": "0.0.0.0:8200",
   "tls_cert_file": "/openbao/certs/server.crt",
   "tls_key_file": "/openbao/certs/server.key",
   "tls_disable": false
 }
  },
  "ui": true,
  "api_addr": "https://0.0.0.0:8200",
  "disable_mlock": true
}

Uruchom kontener OpenBao poleceniem:
```
docker-compose up -d
```

Konfiguracja serwera OpenBao

Kolejne czynności można wykonać w interfejsie graficznym OpenBao lub w interfejsie CLI.

Zainicjuj sejf; w tej operacji zostaną wygenerowane klucze odpieczętowania i token użytkownika root; domyślnie generowanych jest pięć kluczy, z których trzeba podać 3 (threshold), aby odpieczętować sejf:
```
$ bao operator init \
 -key-shares=3 \
 -key-threshold=2
```
Zanotuj wyświetlone wartości Unseal Key i Root Token.
Odpieczętuj sejf; wpisz poniższe polecenie i podaj wymaganą liczbę kluczy odpieczętowania
```
$ bao operator unseal
```
Utwórz przestrzeń nazw dla bieżącego środowiska nAxiom; tę czynność wygodniej wykonać w interfejsie graficznym OpenBao (http://128.0.0.0:8200, logowanie za pomocą tokena Root Token); z menu po lewej wybierz Access > Namespaces, kliknij przycisk Create Namespace i wpisz nazwę przestrzeni nazw, która będzie używana dla danego środowiska nAxiom. Kliknij przycisk Save.
Kliknij wielokropek z prawej strony utworzonej przestrzeni nazw i wybierz polecenie Switch to namespace. Przełączenie do przestrzeni nazw wymaga ponownego zalogowania.
Kliknij opcję menu Policies, a następnie Create ACL Policy.

Wpisz dowolną nazwę i wklej reguły zasad w wyświetlonym oknie lub włącz przełącznik Upload file i wczytaj plik zasad z rozszerzeniem hcl. Minimalne zasady konieczne do integracji z nAxiom są następujące:

  # Allows mounting, updating, reading, and listing secrets engines in any nested namespace
  # The "+" prefix makes this policy work in nested namespaces like "development/tenant1"
  path "+/sys/mounts/*" {
 capabilities = ["create", "update", "read", "list"]
  }
  # Allows reading and listing all mounted secrets engines in any nested namespace
  # Essential for checking if a mount path is already in use before creating new ones
  path "+/sys/mounts" {
 capabilities = ["read", "list"]
  }
  # Allows mounting, updating, reading, and listing secrets engines in the root namespace
  # Provides fallback capability for operations that don't specify a namespace
  # Required for initial setup and root-level mount operations
  path "sys/mounts/*" {
 capabilities = ["create", "update", "read", "list"]
  }
  # Allows reading and listing all mounted secrets engines in the root namespace
  # Used for root-level mount verification and error checking
  # Complements the nested namespace mount reading capability above
  path "sys/mounts" {
 capabilities = ["read", "list"]
  }
  # Allows creating, updating, reading, and listing namespaces in the root level
  # Enables creation of tenant namespaces
  path "sys/namespaces/*" {
 capabilities = ["create", "update", "read", "list"]
  }
  # Allows full CRUD operations on the tenant-specific KV secrets engine across all namespaces
  # Used for tenant-specific secrets storage (TenantMountPoint = "tenant-secrets")
  # Supports operations in nested namespaces like "development/tenant1/tenant-secrets/*"
  # Enables storing tenant certificates, configurations, and sensitive tenant data
  path "+/tenant-secrets/*" {
 capabilities = ["create", "read", "update", "patch", "delete", "list"]
  }
  # Allows full CRUD operations on the environment-specific KV secrets engine in root namespace
  # Used for environment-level secrets storage (EnvironmentMountPoint = "env-secrets")
  # Supports storing environment configurations like database connections, API keys
  # Applied at the "development" namespace level for shared environment secrets
  path "env-secrets/*" {
 capabilities = ["create", "read", "update", "patch", "delete", "list"]
  }

Wróć do głównego menu utworzonej przestrzeni nazw i wybierz Access > Authentication Methods.
Kliknij Enable new method i wybierz metodę Username & Password.
Kliknij kolejno Next i Enable Method.
Kliknij View method po prawej, a na następnej stronie kliknij Create user.
Wypełnij pola Username, Password i Tokens > Generated Token's Policies (wpisz nazwę zasad utworzonych wcześniej)

Na tym kończy się etap konfiguracji OpenBao na potrzeby integracji z nAxiom. Na serwerze OpenBao jest utworzona przestrzeń nazw, włączona metoda uwierzytelniania za pomocą nazwy użytkownika i hasła oraz zdefiniowane poświadczenia dla tej metody logowania.

Następnie przejdź do aplikacji TenantsAdminSPA i skonfiguruj połączenie z OpenBao, używając utworzonych poświadczeń.

Konfiguracja połączenia z OpenBao w TenantsAdminSPA

Aby móc korzystać z OpenBao w nAxiom, w TenantsAdminSPA, w menu Global Settings przejdź do sekcji Secrets Management System i włącz przełącznik Enable Secrets oraz podać następujące parametry połączenia:

URL: adres URL sejfu (domyślnie http://128.0.0.1:8200),
Username: nazwa użytkownika sejfu,
Password: hasło użytkownika sejfu,
Namespace: przestrzeń nazw, w której będą przechowywane hasła i certyfikaty.

Definiowanie sekretów

Zdefiniuj sekrety, które będą przechowywane w OpenBao. Mogą to być sekrety na poziomie środowiska, dostępne dla wszystkich tenantów, oraz sekrety tenantów.

W TenantsAdminSPA kliknij opcję menu Environment secrets, a następnie przycisk Add new secret. Podaj kolejno:

Code: maksymalnie 100 znaków, małe i wielkie litery alfabetu łacińskiego, cyfry oraz łącznik (-); kod sekretu musi być unikalny.
Name: maksymalnie 255 znaków.
Type: dostępne wartości:
- Secret: sekret typu tekstowego, np. hasło, klucz API, token dostępu; do sekretów tego typu można się odwoływać przy użyciu zmiennych aplikacji .
- File: sekret typu plikowego, np. certyfikat.
Value: pole tekstowe do wprowadzenia sekretu tekstowego lub przycisk Upload file do wczytania sekretu plikowego.

Aby zdefiniować sekrety tenantów wybierz kolejno Tenant secrets > Definitions i zdefiniuj nowy sekret w taki sam sposób, jak sekret środowiska. Następnie wybierz opcję menu Values i zdefiniuj wartosci sekretów dla poszczególnych tenantów.

Korzystanie z sekretów w aplikacjach biznesowych nAxiom

Sekrety typu plikowego (certyfikaty) mogą być używane wyłącznie za pomocą asynchronicznej metody GetSecretFile(secretCode) w akcjach C#:

public async Task<byte[]> GetSecretFile(string code);

Wywołanie metody dla sekretów środowiska:

byte[] file = await TenantsAdmin.Environment.Secrets.GetSecretFile("KodSekretu");

Wywołanie metody dla sekretów tenanta:

byte[] file = await TenantsAdmin.CurrentTenant.Secrets.GetSecretFile("KodSekretu");

Metoda może zgłosić wyjątki o następujących kodach:

ApiErrors.ScriptingModule.InvalidSecretFileFormat: plik zwrócony przez silnik sekretów ma niepoprawny format (inny niż base64).
ApiErrors.ScriptingModule.EmptySecretFile: plik zwrócony przez silnik sekretów jest pusty.
ApiErrors.ScriptingModule.MissingSecretFile: w TenantsAdmin nie ma sekretu o podanym kodzie lub sekret nie jest typu plikowego.

Natomiast sekrety tekstowe są dostępne poprzez zmienne aplikacji. Definiując zmienną aplikacji, która ma zwracać sekret, należy wybrać opcję Referencja do obiektu i wpisać ścieżkę TenantsAdmin.Secrets.[ThisTenant|Environment].<SecretCode>, gdzie SecretCode to kod sekretu.