Metody uwierzytelniania

Uwierzytelnianie zamienia głównego Client albo AsyncClient w klienta uwierzytelnionego dla jednego kontekstu KSeF. Klient główny wybiera środowisko i posiada zasoby transportu. Metoda uwierzytelniania potwierdza, kto może działać w wybranym kontekście.

KSeF rozdziela dwa pojęcia, które łatwo pomylić:

Po udanym uwierzytelnieniu SDK zwraca AuthenticatedClient. Ten klient przechowuje access i refresh tokeny KSeF oraz udostępnia chronione gałęzie: sesje, faktury, tokeny, uprawnienia, certyfikaty, limity i historię sesji.

Client(Environment.TEST)
  -> client.authentication
    -> with_token(), with_xades(), with_test_certificate() albo with_profile()
      -> AuthenticatedClient dla jednego kontekstu KSeF
        -> sesje online, sesje batch, faktury
        -> tokeny, uprawnienia, certyfikaty, limity

Metody KSeF i pomocniki SDK

Na poziomie API KSeF uwierzytelnianie ma dwie główne rodziny:

SDK dodaje dwie warstwy wygody:

Wybierz metodę

Zobacz też:

• Skonfiguruj uwierzytelnianie: Użyj wybranej metody w uruchamialnym kodzie SDK ze zmiennymi środowiskowymi i granicami sekretów.
• Użyj profili: Współdziel lokalne ustawienia zgodne z CLI między przepływami terminalowymi i SDK.

Podmiot i kontekst przy XAdES

Przy uwierzytelnianiu XAdES SDK buduje i podpisuje żądanie XML dla kontekstu NIP przekazanego do with_xades(). KSeF odczytuje podmiot uwierzytelniający z certyfikatu użytego do podpisu: na przykład pieczęci firmowej, certyfikatu osobistego z NIP-em albo PESEL-em, certyfikatu KSeF do uwierzytelniania lub certyfikatu dopuszczonego przez uprawnienia na odcisk palca.

To znaczy, że nip jest kontekstem logowania, a nie zawsze identyfikatorem wbudowanym w certyfikat podpisujący. Osoba może uwierzytelnić się w kontekście firmy, jeśli KSeF widzi aktywne uprawnienia tej osoby albo certyfikatu.

Access tokeny odświeżają się same

Access tokeny KSeF są krótkotrwałe. Klient uwierzytelniony trzyma więc refresh token obok access tokenu i odnawia access token bez udziału Twojego kodu: krótko przed access_token_valid_until oraz raz po odpowiedzi 401, ponawiając nieudany request jednokrotnie. Współbieżne requesty współdzielą jedno odświeżenie.

Dotyczy to każdego sposobu uzyskania klienta uwierzytelnionego: metod logowania with_* oraz client.authentication.resume(state), które przyjmuje obiekt stanu albo jego ciąg JSON. Stan z wygasłym access tokenem działa, dopóki jego refresh token jest ważny. Uchwyty sesji wznowione przez state= używają tego samego klienta, więc też się odświeżają. auth.resume_state() i auth.auth_tokens zwracają bieżące tokeny, więc po długo trwającej pracy zapisz stan ponownie.

Gdy refresh token wygasł albo został odrzucony, klient rzuca KSeFAuthenticationExpiredError, podklasę KSeFAuthError. Aby kontynuować, uwierzytelnij się ponownie. Aby odświeżać tokeny samodzielnie, przekaż TransportConfig(auto_refresh_tokens=False). Dokładne reguły opisuje referencja operacji.

Profile są lokalną konfiguracją uwierzytelniania

with_profile() nie jest osobnym typem credentiala. To warstwa konfiguracji nad tymi samymi metodami uwierzytelniania:

Profil przechowuje niesekretne ustawienia, takie jak środowisko, NIP, typ uwierzytelniania, ścieżki certyfikatów, ustawienia pollingu i nazwę zmiennej środowiskowej zawierającej sekret. Nie powinien przechowywać wartości tokenów, haseł kluczy prywatnych ani haseł PKCS#12.

Kolejność wyboru profilu jest taka sama w SDK i CLI:

1. Jawna nazwa profilu przekazana do with_profile("name").
2. KSEF2_PROFILE.
3. active_profile w lokalnej konfiguracji profili.

Środowisko klienta głównego musi zgadzać się ze środowiskiem wybranego profilu. Profil test używaj z Client(Environment.TEST), profil demo z Client(Environment.DEMO), a profil production z Client(Environment.PRODUCTION).

Cykl uwierzytelniania

1. Klient główny pobiera challenge z wybranego środowiska KSeF.

2. Wybrana metoda potwierdza tożsamość dla żądanego kontekstu.

   Uwierzytelnianie tokenem szyfruje token KSeF razem ze znacznikiem czasu z challenge. Uwierzytelnianie XAdES podpisuje XML challenge. Certyfikat TEST najpierw generuje materiał certyfikatu TEST. Profil odczytuje jedną z tych ścieżek z lokalnej konfiguracji.

3. KSeF rozpoczyna asynchroniczną operację uwierzytelniania.

   SDK trzyma tymczasowy token operacji i numer referencyjny wewnętrznie, gdy odpytuje status.

4. SDK zamienia zakończoną operację na access i refresh tokeny.

5. Zwrócony AuthenticatedClient używa tych tokenów w chronionych operacjach SDK.

Klient asynchroniczny ma te same nazwy metod na AsyncClient; wywołuj je z await. Wybór między tokenem, certyfikatem TEST, XAdES i profilem pozostaje taki sam.

Co chronić

Trzymaj sekrety w zmiennych środowiskowych, menedżerach sekretów albo bezpiecznym magazynie aplikacji. Pliki profili ograniczaj do niesekretnych domyślnych ustawień i nazw zmiennych środowiskowych, które zawierają sekrety.

Uwierzytelnienie nie jest autoryzacją

Uwierzytelnienie potwierdza tożsamość dla kontekstu. Uprawnienia nadal określają, które operacje ta tożsamość może wykonać. Credential może uwierzytelnić się poprawnie, a potem nie mieć prawa do wysyłki faktur, metadanych, zarządzania tokenami albo nadawania uprawnień.

Powiązane strony

• Uwierzytelnij się: Skonfiguruj zmienne środowiskowe, token, XAdES, certyfikaty TEST i profile.
• Użyj profili: Współdziel lokalną konfigurację ksef2-cli z uwierzytelnianiem SDK i ProfileStore.
• Low-level uwierzytelnianie: Wykonaj operację uwierzytelniania ręcznie, gdy inny system podpisuje XML albo obsługuje wymianę tokenów.
• Uwierzytelnianie w CLI: Użyj tych samych metod uwierzytelniania z profilami w ksef2-cli.
• Tokeny i uprawnienia: Zobacz, jak credentiale uwierzytelniające łączą się z chronionymi uprawnieniami.
• XAdES: Zrozum podpis XML używany przy uwierzytelnianiu certyfikatem.