Uwierzytelnianie

Uwierzytelnianie zamienia głównego Client w klienta uwierzytelnionego. Klient główny wybiera środowisko KSeF, a metoda uwierzytelnienia wybiera kontekst, w którym działa aplikacja.

Zmienne środowiskowe

Te nazwy są używane w przykładach i przez profile ksef2-cli:

Zmienna	Znaczenie
`KSEF2_ENV`	`test`, `demo` albo `production` w przykładach SDK.
`KSEF2_NIP`	NIP podatnika/kontekstu używany przy uwierzytelnianiu.
`KSEF2_TOKEN`	Token KSeF dla uwierzytelniania tokenem.
`KSEF2_PROFILE`	Nazwa profilu wybierana przez `ksef2-cli` i uwierzytelnianie profilami w SDK.
`KSEF2_CONFIG`	Opcjonalna ścieżka do pliku konfiguracji profili CLI.
`KSEF2_KEY_PASSWORD`	Opcjonalne hasło zaszyfrowanego klucza PEM.
`KSEF2_P12_PASSWORD`	Opcjonalne hasło archiwum PKCS#12/PFX.

export KSEF2_ENV=test
export KSEF2_NIP=5261040828
export KSEF2_TOKEN=podmien-na-prawdziwy-token-ksef

SDK czyta KSEF2_PROFILE i KSEF2_CONFIG, gdy używasz client.authentication.with_profile(). Przy bezpośrednim uwierzytelnianiu tokenem albo certyfikatem trzymaj granicę konfiguracji jawną w aplikacji:

import os

from ksef2 import Client, Environment

environment_name = os.environ.get("KSEF2_ENV", "test").upper()
client = Client(Environment[environment_name])

Wybierz metodę

Użyj tokenu KSeF, gdy aplikacja ma już ważny token dla danego kontekstu. Token działa w TEST, DEMO i PRODUCTION.

import os

auth = client.authentication.with_token(
    ksef_token=os.environ["KSEF2_TOKEN"],
    nip=os.environ["KSEF2_NIP"],
    context_type="nip",
)

Certyfikat generowany przez SDK jest przeznaczony do lokalnego developmentu i działa tylko z Environment.TEST.

import os

auth = client.authentication.with_test_certificate(
    nip=os.environ["KSEF2_NIP"],
)

Użyj plików PEM, gdy certyfikat i klucz prywatny są zapisane oddzielnie.

import os

from ksef2.core.xades import load_certificate_from_pem, load_private_key_from_pem

password = os.environ.get("KSEF2_KEY_PASSWORD")
cert = load_certificate_from_pem("company.pem")
private_key = load_private_key_from_pem(
    "company.key",
    password=password.encode() if password else None,
)

auth = client.authentication.with_xades(
    nip=os.environ["KSEF2_NIP"],
    cert=cert,
    private_key=private_key,
)

Użyj archiwum PKCS#12/PFX, gdy certyfikat i klucz prywatny są w jednym pliku.

import os

from ksef2.core.xades import load_certificate_and_key_from_p12

password = os.environ.get("KSEF2_P12_PASSWORD")
cert, private_key = load_certificate_and_key_from_p12(
    "company.p12",
    password=password.encode() if password else None,
)

auth = client.authentication.with_xades(
    nip=os.environ["KSEF2_NIP"],
    cert=cert,
    private_key=private_key,
)

Profile kompatybilne z CLI

ksef2-cli ma już obsługę lokalnych profili. Profil przechowuje niesekretne ustawienia: środowisko, NIP, metodę uwierzytelnienia, ścieżki certyfikatów i nazwę zmiennej środowiskowej z sekretem.

ksef2 profile create test-company \
  --env test \
  --nip 5261040828 \
  --test-cert

ksef2 profile create prod-token \
  --env production \
  --nip "$KSEF2_NIP" \
  --token-env KSEF2_TOKEN

Wybierz profil dla komend CLI:

export KSEF2_PROFILE=prod-token
ksef2 profile current

Użyj tego samego pliku profili w kodzie SDK:

from ksef2 import Client, Environment
from ksef2.profiles import Profile, ProfileStore, TokenProfileAuth

store = ProfileStore.default()
store.save(
    "prod-token",
    Profile(
        environment=Environment.PRODUCTION,
        nip="5261040828",
        auth=TokenProfileAuth(token_env="KSEF2_TOKEN"),
    ),
    activate=True,
    overwrite=True,
)

client = Client(Environment.PRODUCTION)
auth = client.authentication.with_profile()

# Albo jawnie wybrany profil.
auth = client.authentication.with_profile("prod-token")

Środowisko klienta głównego musi zgadzać się ze środowiskiem wybranego profilu. Przekaż config_path="...", gdy plik profili nie znajduje się w domyślnej lokalizacji ~/.config/ksef2-cli/config.toml.

Zalecany przepływ

Umieść sekrety w zmiennych środowiskowych.

Użyj KSEF2_TOKEN, KSEF2_KEY_PASSWORD albo KSEF2_P12_PASSWORD.
Trzymaj niesekretne ustawienia w jednym miejscu.

Dla w pełni własnych konfiguracji użyj konfiguracji aplikacji. Jeśli to samo środowisko obsługujesz też z terminala, skorzystaj z profili ksef2-cli.
Utwórz klienta głównego dla środowiska.

Użyj Client(Environment.TEST), Client(Environment.DEMO) albo Client(Environment.PRODUCTION).
Uwierzytelnij się raz i przekaż klienta do przepływów.

Klient uwierzytelniony przechowuje tokeny dostępu i udostępnia gałęzie przepływów.

Błędy

Błędy sklasyfikowane przez SDK łap przez KSeFException. Błędy transportu HTTP łap osobno.

import httpx

from ksef2 import KSeFException

try:
    auth = client.authentication.with_test_certificate(nip="5261040828")
except KSeFException as exc:
    print(exc)
except httpx.HTTPError as exc:
    print(f"Transport failed: {exc}")