Uprawnienia kluczy API decydują, co może zepsuć klucz, który wyciekł. W narzędziu do linków bezpiecznym ustawieniem domyślnym jest klucz przypisany do jednej przestrzeni roboczej, ograniczony do najniższej roli wystarczającej do zadania, przechowywany jako hash z pepperem, objęty własnym limitem żądań i ustawiony tak, aby wygasł. Klucz, który tylko tworzy linki, nie ma powodu dotykać webhooków, członków ani rozliczeń i nigdy nie powinien otwierać endpointu administracyjnego. To jest zasada najmniejszych uprawnień, a większość sprowadza się do decyzji podejmowanych w trzydzieści sekund potrzebnych na utworzenie klucza.
Przez ostatni rok czytałem wiele konfiguracji automatyzacji i wzorzec się powtarza: ktoś w piątkowe popołudnie wkleja do n8n własny klucz z pełną władzą, wszystko działa i nikt już o tym nie myśli, dopóki ta osoba nie odejdzie albo eksport przepływu pracy nie wyląduje na wspólnym dysku. Reszta tego wpisu wyjaśnia, jak zakresy i role kluczy API działają w produkcie do krótkich linków, co każda rola naprawdę może zrobić i jak przekazać klucz do narzędzia automatyzacji bez oddawania całej przestrzeni roboczej.
Ten wpis uzupełnia naszą szerszą listę kontrolną bezpieczeństwa skracacza URL, która obejmuje skanowanie, podpisywanie webhooków i logi audytowe w całej platformie. Tutaj przyglądamy się samemu kluczowi.
Co oznaczają uprawnienia kluczy API w narzędziu do linków
API narzędzia do linków dotyka czegoś więcej niż linków. Ten sam token, który tworzy go.example.com/spring-sale, może, zależnie od uprawnień, odczytywać analitykę kliknięć, dodać domenę niestandardową, zaprosić członka albo zarejestrować webhook, który wysyła każde zdarzenie na zewnętrzny serwer. To ostatnie mnie niepokoi. Webhook to stały strumień danych, który osoba tworząca może skierować na dowolny serwer, a nikt w Twoim zespole niekoniecznie zauważy to przez wiele tygodni.
Uprawnienia mają więc trzy osie. Gdzie działa klucz (na którym koncie lub w której przestrzeni roboczej)? Co może tam zrobić (czytać, zapisywać, administrować)? I jak długo oraz jak szybko? Definicja zasady najmniejszych uprawnień według NIST sprowadza się do przyznawania tylko dostępu potrzebnego do zadania, a wszystkie trzy osie są tego częścią. Klucz z prawami tylko do odczytu, który nigdy nie wygasa i nie ma limitu żądań, nadal ma zbyt szerokie uprawnienia w czasie.
Klucze API ograniczone do przestrzeni roboczej: jeden klucz, jedna przestrzeń robocza
W Elido każdy klucz jest tworzony wewnątrz przestrzeni roboczej i tam pozostaje. Wywołaj nim endpointy innej przestrzeni roboczej, a dostaniesz 404, tę samą odpowiedź co dla przestrzeni roboczej, która nie istnieje, więc klucz nie może nawet potwierdzić, że inne przestrzenie robocze są obecne.
To ma większe znaczenie, niż się wydaje. Agencje i większe zespoły często należą do pięciu albo dziesięciu przestrzeni roboczych. Gdyby klucz osobisty dziedziczył wszystko, do czego jego twórca ma dostęp, jeden wyciekły token z jednego projektu klienta otworzyłby każdego klienta. Klucze API ograniczone do przestrzeni roboczej zmniejszają zasięg szkód do jednej przestrzeni roboczej.
Klucz jest też ograniczony do roli wybranej przy tworzeniu i nigdy nie przekracza obecnej roli swojego twórcy. Efektywny dostęp to niższa z tych dwóch wartości. Zdegraduj admina, który utworzył klucz, do editor. Klucz spadnie razem z nim. Uprawnienia niestandardowe przypisane do tego członka też są odrzucane, gdy rola klucza jest tą niższą, ponieważ opisują osobę, a nie klucz.
Klucze API oparte na rolach: co może zrobić każda rola
Klucze Elido używają tych samych czterech ról co ludzie: viewer, editor, admin i owner. Wybierasz jedną podczas tworzenia klucza; jeśli ją pominiesz, klucz domyślnie dostaje editor, co obejmuje typowe zadanie automatyzacji polegające na tworzeniu linków i odczycie analityki, bez żadnego dostępu administracyjnego.
Tak wygląda to w praktyce dla rzeczy, których zwykle dotykają integracje.
| Rola | Linki i kampanie | Analityka | Webhooki | Domeny, członkowie, klucze |
|---|---|---|---|---|
| viewer | Tylko odczyt | Odczyt, eksporty CSV | Lista endpointów | Podgląd domen i członków |
| editor | Tworzenie, edycja, usuwanie, tworzenie masowe | Odczyt, eksporty CSV | Lista endpointów | Podgląd domen i członków |
| admin | Wszystko, co może editor | Plus eksporty danych, zaplanowane raporty | Tworzenie, zmiana, ponowienie | Zarządzanie domenami, członkami, kluczami |
| owner | Wszystko | Wszystko | Wszystko | Wszystko |
Pulpit raportowy, który pobiera liczby kliknięć do narzędzia BI, potrzebuje viewer. Zadanie Google Sheets, które generuje linki kampanii, potrzebuje editor. Prawie nic w codziennej automatyzacji nie potrzebuje admin, a klucz owner traktowałbym jako sygnał ostrzegawczy: owner istnieje dla ludzi, którzy prowadzą przestrzeń roboczą, i nie przychodzi mi do głowy żadne zadanie automatyzacji, które go wymaga.
Warto znać dwa ograniczenia. Tylko admin i owner mogą w ogóle tworzyć, listować lub unieważniać klucze, więc klucz viewer albo editor nie może sam wygenerować sobie silniejszego klucza. I żaden klucz żadnej roli nie dociera do API administracyjnego platformy. To API wprost odrzuca uwierzytelnianie kluczem API statusem 403 i komunikatem "admin access requires an interactive session". Klucz służy do integracji przestrzeni roboczej i tylko to otwiera.
Dlaczego zarządzanie webhookami wymaga klucza admin
To jest rzecz, która zaskakuje ludzi. Odczyt listy endpointów webhooków jest dozwolony dla każdego członka, w tym dla kluczy viewer. Ale utworzenie endpointu, zmiana jego celu albo ponowienie dostarczenia wymaga uprawnienia workspace.edit, które mają tylko admin i owner.
Powodem jest problem stałego strumienia danych z wcześniejszej części. Editor może utworzyć tysiąc linków i to zauważysz. Editor, który mógłby dodać webhook zbierający wszystko i wskazujący na jego własny serwer, od tej chwili po cichu otrzymywałby każde zdarzenie linku. Dlatego zmiany webhooków pozostają przy tych samych osobach, które mogą zmieniać ustawienia przestrzeni roboczej.
W praktyce skonfiguruj webhooki raz, ręcznie, jako admin w panelu. Następnie daj automatyzacji, która je przetwarza, klucz editor albo viewer do jej wywołań API. Jeśli podpinasz webhooki dla zdarzeń linków do Slacka albo CRM, strona odbierająca wcale nie potrzebuje klucza Elido; potrzebuje sekretu podpisu do weryfikacji payloadów.
Chcesz dowodu, zanim cokolwiek podłączysz? Utwórz bezpłatną przestrzeń roboczą, wygeneruj klucz viewer i klucz editor, a potem spróbuj tego samego wywołania zapisu każdym z nich. 403 na kluczu viewer powie Ci więcej niż jakakolwiek tabela.
Jak przechowywane są klucze: pepper, hash i prefiks
Token wygląda jak elido_, po którym następują 52 znaki base32 wygenerowane z 32 losowych bajtów. Całość widzisz dokładnie raz, w odpowiedzi na wywołanie tworzące klucz. Potem po naszej stronie znika na dobre.
Przechowujemy HMAC-SHA256 tokena, kluczowany pepperem po stronie serwera, który znajduje się w konfiguracji aplikacji, a nie w bazie danych. Przy każdym żądaniu przychodzący token Bearer (schemat zdefiniowany w RFC 6750) jest hashowany w ten sam sposób i wyszukiwany po hashu. Skradziony zrzut bazy danych jest listą hashy, których nie da się sprawdzić bez peppera, a usługa produkcyjna odmawia startu bez ustawionego peppera.
Na potrzeby Twoich zapisów przechowujemy pierwsze osiem znaków po elido_ jako prefiks do wyświetlenia. Strona kluczy API pokazuje ten prefiks obok nazwy klucza, roli, daty utworzenia, wygaśnięcia, czasu ostatniego użycia i ostatniego IP, a także łącznej liczby żądań i liczby nieudanych żądań. Gdy klucz pojawi się gdzieś w logu, prefiks mówi, który to klucz, bez potrzeby pokazywania komukolwiek pełnego sekretu.
Limity żądań, wygaśnięcie i rotacja kluczy API
Każdy klucz dostaje własne wiadro tokenów, oddzielne od limitu na przestrzeń roboczą, więc jeden niekontrolowany przepływ pracy nie może zjeść budżetu wszystkiego innego. Admin może nadpisać tempo pojedynczego klucza od 1 do 10 000 żądań na sekundę i jego limit chwilowy od 1 do 20 000 albo wyczyścić nadpisanie, żeby wrócić do wartości domyślnej. Po przekroczeniu limitu klucz dostaje 429 z Retry-After: 1 i X-RateLimit-Scope: api_key, więc logika ponawiania może odróżnić limit klucza od limitu przestrzeni roboczej. Przewodnik po limitach żądań i idempotencji omawia poprawne stosowanie backoffu.
Wygaśnięcie jest opcjonalne i ustawiane przy tworzeniu jako znacznik czasu RFC 3339. Gdy minie, klucz po prostu przestaje pasować. Unieważnienie to jedno DELETE. Też jest idempotentne.
Nie ma jednego przycisku "rotuj" i mi go nie brakuje. Rotacja ma trzy kroki:
- Utwórz nowy klucz z tą samą rolą i świeżą datą wygaśnięcia.
- Podmień go w magazynie poświadczeń narzędzia i potwierdź, że wywołanie się udaje.
- Unieważnij stary klucz, a potem sprawdź na liście, że czas jego ostatniego użycia przestał się zmieniać.
Każdy krok trafia do logu audytowego przestrzeni roboczej: api_key.created z nazwą i rolą, api_key.revoked oraz api_key.rate_limit_set dla nadpisań. Co pięć minut działa też skan w tle i oznacza każdy klucz z ponad 1000 żądań, w którym ponad 30% zakończyło się niepowodzeniem. Flaga trafia do logu audytowego i na klucz. Bez automatycznego unieważnienia. Zabicie klucza to decyzja człowieka, bo seria 404 równie często oznacza zepsuty przepływ pracy, jak atakującego.
Przekazywanie kluczy API zgodnych z zasadą najmniejszych uprawnień do n8n, Make i Zapier
Platformy automatyzacji to miejsca, w których klucze zostają zapomniane. Siedzą w magazynie poświadczeń, są kopiowane do eksportowanych plików JSON przepływów pracy i żyją dłużej niż osoba, która je ustawiła. Pomagają dwa nawyki:
- Jeden klucz na narzędzie i rodzinę przepływów pracy, nazwany od niego ("n8n: arkusze kampanii"). Unieważnienie psuje wtedy dokładnie jedną rzecz, a log audytowy mówi, które narzędzie co zrobiło.
- Editor dla wszystkiego, co tworzy linki, viewer dla wszystkiego, co tylko czyta, oraz data wygaśnięcia na obu.
To tyle, jeśli chodzi o listę; reszta to osąd. Ściągawka OWASP o zarządzaniu sekretami to dobra lektura o trzymaniu tokenów poza logami i eksportami, czyli miejscami, z których klucze automatyzacji zwykle wyciekają.
W przypadku konfiguracji konkretnych narzędzi przewodnik po skracaczu URL w n8n umieszcza klucz w poświadczeniu Header Auth, a porównanie Make vs IFTTT vs n8n vs Zapier omawia, gdzie każda platforma go przechowuje. Zapier łączy się przez ten sam token, zgodnie z instrukcją automatyzacji Zapier. Dla CI albo czegokolwiek, co powinno przetrwać odejście osoby, lepiej pasuje użytkownik maszynowy: konto serwisowe z własną rolą, oddzielone od klucza dowolnego człowieka.
I właśnie to przekazanie jest powodem, dla którego klucz nigdy nie może otwierać endpointów administracyjnych. Gdy token siedzi w narzędziu zewnętrznym, może go użyć każdy z dostępem do edycji przepływów pracy tego narzędzia. Ufasz wszystkim po ich stronie, nie tylko po swojej.
Tokeny z osobnymi zakresami są planowane, nie są dostępne
Role są z założenia szerokie, a czasem zbyt szerokie. Klucz editor, który ma tylko tworzyć linki, może też je usuwać, bo usuwanie jest częścią roli editor. Rozwiązaniem są tokeny z osobnymi zakresami, takimi jak links:write albo analytics:read, przypisanymi bezpośrednio do klucza i nałożonymi jako warstwa na role.
To jest w naszym planie rozwoju i nie zostało jeszcze wydane. Dziś uprawnienia klucza to jego przestrzeń robocza plus rola i nic bardziej szczegółowego. Jeśli teraz potrzebujesz ciaśniejszej kontroli, dwie dźwignie to niższa rola i krótki termin wygaśnięcia, plus osobne klucze dla każdego zadania, żeby zasięg szkód każdego z nich był mały. Szybki start API i referencja API oraz SDK pokazują obecny model kluczy w działającym kodzie, a zespoły, które chcą też kontroli na poziomie tożsamości, mogą przeczytać o SCIM i SSO dla narzędzi marketingowych.
Przeczytaj materiał główny: lista kontrolna bezpieczeństwa skracacza URL obejmuje mechanizmy wokół klucza, od skanowania URL po listy dozwolonych IP.
Powiązane na blogu
Najczęściej zadawane pytania
Czym są uprawnienia kluczy API?
To zestaw działań, które klucz może wykonać wobec API: które zasoby może czytać, które może zmieniać i na którym koncie. W Elido uprawnienia klucza wynikają z przestrzeni roboczej, w której został wydany, oraz z roli wybranej przy tworzeniu, więc ten sam klucz nie może działać w innej przestrzeni roboczej ani powyżej tej roli.
Czym jest zasada najmniejszych uprawnień dla kluczy API?
Oznacza, że każdy klucz dostaje najmniejszy zestaw uprawnień potrzebny do swojego zadania i nic więcej. Pulpit, który tylko odczytuje liczbę kliknięć, dostaje klucz viewer, przepływ pracy tworzący linki dostaje klucz editor, a klucze admin zostają dla rzadkich zadań związanych z webhookami, domenami lub członkami. Wyciekły klucz może wtedy zrobić tylko to, co robiło to jedno zadanie.
Jaka jest różnica między zakresami kluczy API a rolami?
Zakres to wąskie uprawnienie, takie jak links:write, przypisane bezpośrednio do tokena, a rola to nazwany pakiet uprawnień, taki jak editor. Role łatwiej zrozumieć; zakresy są dokładniejsze. Klucze Elido używają dziś ról przestrzeni roboczej, a tokeny z osobnymi zakresami są planowane jako warstwa nad nimi, ale nie są jeszcze dostępne.
Jak często należy rotować klucze API?
Typowe zalecenie to co 30 do 90 dni, a także od razu, gdy odejdzie ktoś, kto widział klucz, gdy klucz pojawi się w logu albo gdy jego ruch wygląda podejrzanie. Ustawienie daty wygaśnięcia przy tworzeniu zmienia ten harmonogram w twardą blokadę zamiast przypomnienia w kalendarzu, które ludzie ignorują.
Czy klucz API może uzyskać dostęp do endpointów administracyjnych?
W Elido nie. API administracyjne platformy akceptuje tylko interaktywną, zalogowaną sesję i odpowiada kluczowi API statusem 403, niezależnie od roli osoby, która go utworzyła. Ustawienia przestrzeni roboczej wymagające praw admin nadal są dostępne, ale tylko dla klucza utworzonego z rolą admin lub owner.
Jak klucze API powinny być przechowywane po stronie dostawcy?
Nigdy jako zwykły tekst. Dostawca powinien przechowywać kluczowany hash tokena i potem pokazywać tylko krótki prefiks, żeby sama kopia bazy danych nie wystarczyła do wywołania API. Elido hashuje każdy token za pomocą HMAC-SHA256 i peppera po stronie serwera oraz pokazuje pełny token dokładnie raz.
Wypróbuj Elido
Wklej URL, otrzymaj krótki link
Bez rejestracji. Link działa 30 dni. Zarejestruj się, aby zachować go na zawsze.
Za darmo, bez rejestracji · 2 dziennie