HTTP: prijava

Vsi postopki prijave v prehod z njihovimi pravili in odgovori, samopostrežba za lastne ključe in pravilnik prijave z 2FA (dvostopenjskim preverjanjem identitete). Model v ozadju pojasnjuje Prijava in posredovanje identitete.

Poleg ključa storitve se lahko klicatelj prijavi s svojim računom Windows prek HTTP Negotiate (Kerberos ali, kjer Kerberos ni na voljo, NTLM). To je namenjeno osebam: Access prek gonilnika ODBC ter Excel ali Power BI se prijavijo kot uporabnik, ki jih izvaja. Nikjer ni shranjen ključ ali geslo, revizijska sled pa navaja osebo namesto imena ključa.

"Security": {
  "AuthMode": "ApiKey, Windows",
  "ApiKeys": [ { "Client": "fachanwendung", "Key": "env:FACHANWENDUNG_SCHLUESSEL" } ],
  "WindowsAccounts": [
    { "Account": "FIRMA\\Fachdaten-Leser",  "Client": "fachdaten-lesen" },
    { "Account": "FIRMA\\Fachdaten-Pflege", "Client": "fachdaten-pflege" },
    { "Account": "S-1-5-32-545",            "Client": "auskunft" }
  ],
  "Clients": [
    { "Id": "fachanwendung",    "Databases": [ "fachdaten" ], "Resources": [ "*" ],     "Verbs": [ "*" ] },
    { "Id": "fachdaten-lesen",  "Databases": [ "fachdaten" ], "Resources": [ "views" ], "Verbs": [ "GET" ], "ReadOnly": true },
    { "Id": "fachdaten-pflege", "Databases": [ "fachdaten" ], "Resources": [ "*" ],     "Verbs": [ "*" ] },
    { "Id": "auskunft",         "Databases": [ "fachdaten" ], "Resources": [ "views" ], "Verbs": [ "GET" ], "ReadOnly": true }
  ]
}

Na zahtevo brez prijave prehod odgovori z 401 in WWW-Authenticate: Negotiate; šele nato se odjemalec prijavi z računom Windows. Vsaka nova povezava se zato začne z zahtevo brez prijave, ki je zapisana v revizijski sledi kot anonym … UNAUTHENTICATED (401). To je prvi korak postopka, ne napaka. Nato prijava velja za celotno povezavo.

Kerberos zahteva SPN HTTP/<ime-računalnika> za račun, pod katerim teče prehod; če ga ni, Windows preide na NTLM.

Uporabniki, ki so se v SQL Server doslej prijavljali z imenom in geslom, se z isto prijavo prijavijo v prehod: prek HTTP Basic, torej z imenom in geslom v glavi Authorization. Prehod gesla ne preverja sam in ga ne shrani. Z imenom in geslom odpre povezavo s strežnikom naslovljenega aliasa, odloči pa SQL Server, kot pri neposredni povezavi. Vsi stavki zahteve se nato izvajajo prek povezav te prijave: dovoljenja, privzete vrednosti stolpcev in sprožilci vidijo samo to prijavo, tudi ORIGINAL_LOGIN().

"Databases": [
  { "Name": "fachdaten", "Provider": "sqlserver", "ConnectionString": "…",
    "AllowSqlLogins": true }
],
"Security": {
  "AuthMode": "ApiKey, Windows, SqlLogin",
  "SqlLogins": [
    { "Login": "*",       "Client": "fachdaten-lesen"  },
    { "Login": "pflege1", "Client": "fachdaten-pflege" }
  ],
  "TrustedProxies": [ "10.0.0.5" ]
}

Osebni ključ pripada osebi, ne programu. Ne potrebuje domene, gesla SQL ali dodatne infrastrukture, zato deluje povsod, kjer je prehod dosegljiv. Osebe in ključi so v skrbniški shrambi; postopek jo potrebuje in ga vklopite s PersonalKey:

"Security": { "AuthMode": "ApiKey, PersonalKey" },
"Store": { "Path": "store/gateway.db", "MasterKey": "env:WKL_GW_MASTER_KEY", "MaxKeyLifetimeDays": 365 }

Ključ gre v isto glavo kot ključ storitve (X-Api-Key, glejte ApiKeyHeader). Vsak odjemalec, ki zna poslati ključ storitve (gonilnik ODBC z APIKEY/APIKEYENV, skript, orodje za poročila), brez sprememb pošlje tudi osebnega. Ključa loči predpona. Osebni ključ velja tudi kot geslo HTTP Basic (ime se ne preverja; priporočeno je pkuser, glejte spodaj): Excel in Power BI takšne podatke za prijavo (način prijave „Basic“) shranita v lastno upravljanje poverilnic, glavo pa bi bilo treba zapisati v poizvedbo in s tem v vsak delovni zvezek. Oblika ključa ga loči od gesla prijave SQL Server.

<a id=„uporabnisko-ime-pkuser“></a>Uporabniško ime pkuser (dogovor). Kdor osebni ključ vpiše kot geslo, kot uporabniško ime navede pkuser (personal key user). To ni obvezno: prehod ključ prepozna po njegovi obliki (wkl_…), ne po imenu, in sprejme vsako ime. Enotno ime ima kljub temu prednosti:

• V upravljanju poverilnic Excela, Power BI in sistema Windows je na prvi pogled vidno, da gre za osebni ključ in ne za prijavo SQL Server.
• Po telefonu zadošča „uporabniško ime pkuser, geslo vaš ključ“, brez pojasnjevanja, katero ime je mišljeno.
• Nihče ne vpiše imena iz drugega sistema in ga nato ne zamenja za del dostopa.

V SQL Serverju ne ustvarite prijave pkuser: geslo brez oblike ključa prehod preveri kot prijavo SQL Server s tem imenom.

„Zadnja uporaba“ se zbira in zapiše vsakih 60 sekund ter ob zaustavitvi, ne pri vsaki zahtevi: vsako pisanje v datoteko bi prehod spodbudilo k ponovnemu branju. Ob sesutju se izgubi največ ena minuta statistike, nikoli pa pooblastilo. Pisanj, ki ne spremenijo obratovalnih podatkov (uporaba, ključi, osebe), prehod ne obravnava kot nove različice in jih ne sporoči.

Upravljanje oseb in ključev – prek skrbniškega vmesnika ali na računalniku prehoda z ukazi save-person, issue-key, revoke-key in list-keys; izvedejo se s konfiguracijo in okoljem prehoda, tudi medtem ko prehod teče. Klic, možnosti in izhodne kode so opisani v Ukazi na strežniku: osebe in ključi. Ti ukazi ne pišejo v dnevnik sprememb (kdor jih izvede, ima tako ali tako dostop do datoteke); ukazi za odklepanje init-admin, reset-totp in remove-sign-in-rule pa vanj pišejo, z izvajalcem „Konsole (Rechner, Konto)“ (konzola (računalnik, račun)).

Ključ je mogoče izdati tako, da miruje, dokler ga skrbništvo ne omogoči za določen čas, na primer ključ samo za branje brez 2FA, ki ga oseba v Power BI shrani za predstavitve upravi. Ključ ostane pri vseh omogočitvah isti, zato Power BI ni treba znova nastavljati. Zunaj omogočenega časa ne omogoča nobenega dostopa, tudi če je ostal v poročilu, na prenosniku ali v e-pošti.

Omogoči ga lahko samo skrbništvo, ne oseba sama; oboje je zapisano z izvajalcem in koncem v dnevniku sprememb. Najdaljša veljavnost ključa (MaxKeyLifetimeDays) še naprej velja: po njej je potreben nov ključ.

Oseba, ki se lahko prijavi na drug način (s svojim računom Windows ali svojo prijavo SQL Server), si osebne ključe izda sama, na primer za Excel na prenosniku, in jih tudi zaklene. Skrbništvo mora samopostrežbo le enkrat omogočiti.

„WklGatewayClient – razred VBA za podatkovni prehod“ (dokumentacija aplikacije za upravljanje) za to ponuja OwnKeys, IssueOwnKey in RevokeOwnKey.

Pravilnik prijave določa, kateri postopek prijave za kateri del prehoda iz katerih omrežij ali držav potrebuje 2FA ali je zavrnjen, na primer „osebni ključi iz omrežja podjetja brez kode, od zunaj samo s TOTP“, „prijave SQL Server nikoli od zunaj“ ali „dostop do podatkov samo iz Nemčije“. Shranjen je v skrbniški shrambi in ga urejate prek množic SignInRules, SignInRuleItems, SignInRuleExceptions, SignInRuleExceptionItems in Settings skrbniškega vmesnika; brez shrambe so mogoče le zavrnitve (Gateway:Security:SignInRules v konfiguracijski datoteki).

Za posamezne osebe ali skupine. Pravilo je mogoče omejiti na osebe ali skupine Windows ali pa jih iz njega izvzeti, na primer „od zunaj nihče, razen Franka Mustermanna“: { Scope: Data, Effect: Deny, ExceptFrom: [10.0.0.0/8], ExceptPersons: [Frank Mustermann] }. Osebo prehod prepozna po njenem osebnem ključu, njenem lastnem računu Windows ali njeni prijavi SQL Server; skupino le pri prijavi z računom Windows. Klicatelj, ki ni dodeljen nobeni osebi (ključ storitve), ne spada pod nobeno takšno pravilo in pod nobeno izjemo. Kaj pravilo pomeni za osebo, prikaže explain-sign-in skrbniškega vmesnika.

Po državi. Državo zahteve prehod prebere iz geolokacijske zbirke dnevnika prijav: v pomnilniku, brez dostopa do omrežja in samo, če kakšno pravilo navaja države. Zahteva nima države, če geolokacijska zbirka ni naložena, če pride s tega računalnika, iz lastnega omrežja (`Gateway:SignInLog:Networks`) ali iz zasebnega omrežja ali če zbirka naslova ne pozna. Takšna neznana država je v obsegu vsakega pravila: „dostop do podatkov samo iz Nemčije“ jo zavrne. Lastna omrežja zato izvzemite z njihovimi naslovi, ne z državo:

{ "Scope": "Data", "Effect": "Deny", "Label": "samo Nemčija",
  "ExceptCountries": [ "DE" ], "ExceptFrom": [ "10.0.0.0/8" ] }

Pomembno: Država, izpeljana iz naslova, je ocena, ne dokaz. VPN, posredniški strežnik ali mobilno omrežje lahko izvor premakne v drugo državo, geolokacijske zbirke pa se pri posameznih omrežjih motijo. Pravila po državi so dodatna plast poleg ključev, omrežij in 2FA; nobenega od njih ne nadomeščajo.

Pravilo lahko sprašuje tudi po operaterju omrežja, iz katerega pride zahteva, po programu in po uri. Te tri značilnosti niso enako zanesljive:

Neznan operater ali manjkajoč program je kot neznana država v obsegu pravila in ne izpolni nobene značilnosti izjeme. Program, ki ga odjemalec le navaja, je zato primeren za omejevanje („skrbništvo samo iz WinHTTP“ zavrne brskalnik). Kot edina značilnost izjeme pa oprosti vsakogar, ki pošlje to besedilo; v izjemi ga zato povežite z osebami, omrežji ali koncem veljavnosti.

Časovno okno zapišete kot [dnevi] [hh:mm-hh:mm]:

• Dnevi Mon, Tue, Wed, Thu, Fri, Sat, Sun kot seznam (Sat,Sun) ali razpon (Mon-Fri, tudi Fri-Mon); brez dni velja vsak dan.
• Ure z izključnim koncem; 24:00 je konec dneva; brez ur velja ves dan.
• Okno čez polnoč (Mon-Fri 22:00-06:00) pripada dnevu, ko se začne: od petka ob 22.00 do sobote ob 6.00 je v njem, ponedeljek ob 3.00 ni.

„Prijava SQL Server samo od ponedeljka do petka, od 6.00 do 20.00“:

{ "Method": "SqlLogin", "Effect": "Deny", "Label": "SQL samo v delovnem času",
  "ExceptHours": [ "Mon-Fri 06:00-20:00" ] }

„Iz omrežij drugih operaterjev samo z 2FA, iz obrata 3 nikoli“:

{ "Scope": "Data", "Effect": "RequireTotp", "Label": "koda iz tujih omrežij",
  "ExceptOperators": [ "AS3320" ], "ExceptFrom": [ "Obrat 3" ] }

Lastna in zasebna omrežja nimajo operaterja omrežja. Brez ExceptFrom bi pravilo kodo zahtevalo tudi v obratu.

Dogodek prijave v Signals navaja ocenjenega operaterja omrežja (operator), program (client) in pod trust za vsak signal, kako zanesljiv je (observed, claimed, verified).

Časovno omejene izjeme. Seznami ExceptPersons, ExceptCountries in ExceptFrom izvzemajo vsak zase in trajno: ExceptPersons: [Frank Mustermann] Franka oprosti v vsaki državi. Izjema v Exceptions pa oprosti le, če hkrati veljajo vse njene značilnosti, na primer „Frank Mustermann s Tajske do

2. novembra„:

{ "Scope": "Data", "Effect": "Deny", "Label": "samo Nemčija",
  "ExceptCountries": [ "DE" ], "ExceptFrom": [ "10.0.0.0/8" ],
  "Exceptions": [ { "Persons": [ "Frank Mustermann" ], "Countries": [ "TH" ],
                    "Until": "2026-11-02T00:00:00Z", "Label": "dopust" } ] }

• Vsaj ena značilnost ali konec. Izjema brez obojega bi trajno oprostila vsakogar; preverjanje ob zagonu in skrbniški vmesnik jo zavrneta.
• Neznano nikoli ne oprosti. Neznana država, neznan izvor, neznan operater omrežja, manjkajoč program ali klicatelj, ki ni dodeljen nobeni osebi, ne izpolni nobene značilnosti, ki to preverja. Brez geolokacijske zbirke izjema po državi torej ne velja, namesto da bi odprla pravilo.
• Konec velja takoj. Prehod ga ob vsaki zahtevi primerja s svojo uro; sprememba za to ni potrebna. Ko konec opazi, ga enkrat zapiše v dnevnik sprememb (Entity exception-lapsed, izvajalec Dienst (Ablauf), prejšnje stanje: pravilo, opomba in konec). Potekla izjema ostane, dokler je ne odstranite.

Previdno pri ustvarjanju zavrnitve. Pravilo velja, takoj ko je shranjeno. Kdor zavrnitev za vse obsege najprej ustvari brez izjem in značilnosti doda pozneje, se v tistem trenutku sam zaklene. Zavrnitve zato ustvarjajte s save-sign-in-rule skrbniškega vmesnika, ki pravilo in izjeme shrani v eni spremembi; če se je to zgodilo, pomaga remove-sign-in-rule na strežniku.

Šteje vsako ustrezno pravilo, zavrnitev ima prednost pred vsem drugim; vrstni red nima pomena. Izjema: izmenjavo kode in nastavitev 2FA (/auth/v1/totp, /auth/v1/enrol) prehod presoja samo po pravilih z obsegom All; zavrnitev samo za Data ali Admin tam ne prepreči nobenega poskusa. Prijavo SQL Server pa SQL Server preveri, preden pravilnik presodi: iz zavrnjenega izvora napačno geslo odgovori z 401, pravilno pa s 403; napadalec torej izve, ali je geslo pravilno, omeji ga le meja neuspelih poskusov. Če ne velja nobeno pravilo, odločajo le pravice. Pravilnik se ne uporablja v razvojnem okolju brez prijave; pravilnik, ki je zaklenil skrbništvo, popravijo ukazi na strežniku. Nova shramba vsebuje pravilo „skrbništvo samo z 2FA“ (Scope: Admin, Effect: RequireTotp); kot vsako drugo ga je mogoče spremeniti ali izbrisati. Ne glede na to fiksna spodnja meja Gateway:Store:RequireAdminTotp (privzeto true) zahteva 2FA za skrbništvo in samopostrežbo, pri vsakem postopku prijave in z vsakega izvora; tudi ključ s TotpExempt je ne odpravi. Izklopiti jo je mogoče samo v konfiguracijski datoteki. Preverjanje ob zagonu zavrne RequireTotp za ključe storitve, saj program ni oseba in nima 2FA; namesto tega zapišite Deny.

2FA s kodami TOTP. Časovno odvisne kode po RFC 6238 (6 mest, 30 sekund), kot jih ustvari vsaka aplikacija Authenticator. 2FA pripada osebi: osebni ključ jo navede; račun Windows in prijava SQL Server jo najdeta prek njenega lastnega računa (WindowsAccount) oziroma njene lastne prijave (SqlLogin); primerja se samo ime prijave, brez razlikovanja velikih in malih črk, prek vseh aliasov in strežnikov, zato tako odprta seja ne velja le za alias, na katerem je bila koda izmenjana. Skupina ni oseba; prijava, ki se ne ujema z nobeno osebo ali se ujema z dvema, prejme 403, če je zahtevan 2FA. Nastavi ga skrbništvo (enroll-totp), najbolje z enkratno povezavo: stran prikaže naslov otpauth:// kot kodo QR in poleg nje ključ za ročni vnos. Skrivnost je zapečatena v shrambi (z lastnim namenom, ob zamenjavi glavnega ključa jo reseal-store na novo šifrira).

Nastavitev ob prvi prijavi. Če oseba 2FA še ni nastavila, pravilnik pa 2FA zahteva, lahko oseba nastavitev nekaj časa opravi sama, z osnovno prijavo (prvi faktor), ki do tedaj velja samo za to:

POST /auth/v1/enrol[/{alias}]   osnovna prijava kot pri izmenjavi kode
Telo: { }                       200: { "person", "secret", "uri", "qrPng", "openUntil" }
Telo: { "code": "123456" }      201: kot pri izmenjavi - nastavitev 2FA končana, seja odprta

• Kdaj. V roku totp_enrol_hours (množica Settings, sicer Gateway:Security:TotpEnrolHours, privzeto 24, največ 168, 0 izklopi nastavitev ob prijavi) po izdaji ključa, s katerim pride zahteva; za osebo brez ključa (račun Windows) do časa, ki sta ga na strežniku nastavila init-admin ali reset-totp.
• Zakaj rok. Dokler oseba ne nastavi 2FA, jo predstavlja ključ sam. Kdor ga v tem času prestreže, bi lahko nanj vezal svojo aplikacijo Authenticator. Rok ta čas ohranja kratek; ključ, ki je čakal predolgo, je treba izdati znova.
• Enkrat. Potrditev konča rok in je zapisana v dnevniku sprememb; osebi z nastavljenim 2FA se nastavitev ne ponudi več. Če ga je kdo drug nastavil prej, zakoniti imetnik to opazi prav po tem. Nov 2FA tedaj nastavi skrbništvo.
• Dva koraka. Brez kode prehod ustvari podatke za izračun kod in odgovori z naslovom, ključem za ročni vnos in kodo QR kot PNG; zapečateni se shranijo šele s prvo ustrezno kodo. Nov klic brez kode nadomesti ustvarjene podatke.
• Na vsako drugo zahtevo osebe prehod do tedaj odgovori z 401 in WWW-Authenticate: Wkl-Totp realm="Wkl.Data.Gateway", enrol="/auth/v1/enrol". Aplikacija za upravljanje tedaj prikaže kartico za nastavitev; razred VBA WklGatewayClient sporoči gwErrEnrolmentRequired in ponudi BeginTotpEnrolment/ConfirmTotpEnrolment.

Koda v zameno za sejo. Koda velja 30 sekund; gonilnik, ki tabelo bere po straneh, je ne more zahtevati pri vsaki zahtevi. Koda se zato enkrat zamenja za sejo, ki se nato v glavi X-Wkl-Session pošlje z vsako zahtevo:

POST /auth/v1/totp            osnovna prijava: osebni ključ ali račun Windows
POST /auth/v1/totp/{alias}    osnovna prijava: prijava SQL Server (Basic), preverjena na tem aliasu
Telo: { "code": "123456" }                   po želji z "role": "vertrieb"
201:   { "session": "…", "id": "t…", "person": "…", "header": "X-Wkl-Session", "expiresAt": "…" }

Če telo navaja role, je seja vezana na to identiteto podatkovne zbirke: zahteva brez lastne izbire teče pod njo. Izbira se preveri pri vsaki zahtevi, ne pri izmenjavi.

• Seja ni prijava. Vsaka zahteva še naprej vsebuje osnovno prijavo; seja velja le za osebo, postopek in (pri ključu) ključ, s katerim je bila odprta. Ukraden žeton sam ne omogoča dostopa. Zato se uporablja lastna glava namesto Authorization: Bearer, saj ta pri Windows in Basic že prenaša osnovno prijavo.
• Trajanje totp_session_hours (množica Settings, sicer Gateway:Security:TotpSessionHours), privzeto 10 ur, od 1 do 168.
• Konec: potek; Revoked v SessionTokens; zaklepanje ključa; izklop osebe; nova nastavitev ali odstranitev njenega 2FA. Preveri se pri vsaki zahtevi.
• Koda velja enkrat (njen časovni korak mora biti poznejši od nazadnje sprejetega) in en korak (30 sekund) pred uro prehoda ali za njo; ta toleranca je fiksna in je ni mogoče nastaviti. Pet napačnih kod na osebo oziroma dvajset na izvor v 15 minutah vodi do 429. Števci so v pomnilniku: ponovni zagon jih ponastavi, kdor pa pozna ime, lahko osebo z napačnimi poskusi za nekaj časa zaklene.
• Izmenjava je mogoča samo prek zaščitene povezave (HTTPS, zaupanja vreden posredniški strežnik s https, isti računalnik).

Odjemalci brez pogovornega okna (Power BI, Excel, skripti) ne morejo zahtevati kode. Zanje obstajajo ključi s TotpExempt: izvzeti so iz zahteve po 2FA, ne pa iz zavrnitve, in so dovoljeni samo kot ključi samo za branje. S pravicami, ki osebo omejijo na odobrene poglede, in po želji z vezavo na omrežje je to ozko omejen dostop za poročila.

Novo pravilo – predvsem zavrnitev – najprej preizkusite z Mode = Report. Pravilo se tedaj pri vsaki prijavi ovrednoti, kot da bi bilo uveljavljeno, vendar ničesar ne spremeni: kdor bi bil brez njega sprejet, ostane sprejet. Dogodek prijave ga v Rules navede z "mode": "report"; SignInRuleReports za vsako pravilo in različico prešteje, koliko prijav bi zadelo, od koliko oseb in izvorov in katere bi oprostila izjema (glejte Skrbništvo). explain-sign-in ga prikaže ločeno pod tried.

Če je rezultat ustrezen, pravilo uveljavite z ukazom save-sign-in-rule in "mode": "Enforce"; od tedaj velja. Preklop je zapisan v dnevniku sprememb in spremeni različico pravila, tako da je dogodke iz preizkusa mogoče ločiti od dogodkov iz rednega delovanja. Spodnja meja skrbništva (RequireAdminTotp) ni pravilo in je ni mogoče preizkusiti.

• Prijava in posredovanje identitete
• Konfiguracija: Security
• Stopnjevanje dostopa glede na lokacijo