Jak nadać dostęp grupami i mapowaniem zakresów

Platforma sama niczego nie nadaje. To, co użytkownik może zrobić, wynika z grup w claimie groups jego tokenu oraz z dwóch rzeczy, które prowadzisz: grup ról u dostawcy tożsamości i mapowania zakresów w portalu.

Pytanie	Rozstrzyga
Czy ten użytkownik może wywoływać narzędzia o takim ryzyku w tym systemie?	Grupa roli w Keycloaku: `mcp-<system>-read`, `-write`, `-destructive`
Na których projektach, przestrzeniach, grupach lub kolejkach?	Mapowanie zakresów w portalu: grupa na zakresy zasobów
Który klient AI w ogóle może wywoływać narzędzia?	`MCP_ALLOWED_CLIENTS` w gatewayu

Grupy ról w Keycloaku

Utwórz po jednej grupie na system i ryzyko w konsoli realmu (https://<platforma>/auth/admin/mcp/console/) i dodaj do nich użytkowników. Nazwy są dokładne i rozróżniają wielkość liter, a token musi je nieść bez ścieżki (mcp-jira-read, nie /mcp-jira-read). Realm z paczki Compose definiuje tylko mcp-platform-admin, administratorów platformy. Pozostałe tworzysz przy dodawaniu serwera.

Grupa	Pozwala na
`mcp-<system>-read`	Narzędzia z ryzykiem Odczyt, na przykład `mcp-gitlab-read`, `mcp-jira-read`
`mcp-<system>-write`	Narzędzia z ryzykiem Zapis, na przykład `mcp-gitlab-write`
`mcp-<system>-destructive`	Narzędzia z ryzykiem Usuwanie. Każde wywołanie wymaga też kodu z Authenticatora użytkownika
`mcp-platform-admin`	Strony Administracja w portalu

Narzędzie może w manifeście wskazać też dodatkową grupę, na przykład mcp-opensearch-ops dla narzędzi OpenSearch dotyczących całego klastra. Wtedy użytkownik potrzebuje obu grup. Dodatkowa grupa może tylko zawęzić dostęp. Nazwy grup używanych przez serwer są w jego README.

Sama grupa roli nie wystarcza do zapisu: zapisy są dozwolone tylko w zakresach, które nadaje mapowanie zakresów (następna sekcja). Niektóre serwery stosują zakresy także do odczytu. Service Desk i OpenSearch, na przykład, nic nie dają bez grupy zmapowanej na kolejkę albo prefiks indeksu.

Aby użytkownicy widzieli w portalu, o jakie grupy mogą prosić, wypisz grupy każdego systemu w pliku katalogu portalu (zobacz Konfiguracja). Nie wpisuj tam mcp-platform-admin. Portal pokaże wtedy uprawnienia, a użytkowników dodajesz do grup w Keycloaku. Ten katalog nie składa wniosków.

Mapowanie zakresów

Zakres wskazuje jeden zasób: <Przestrzeń>::<Typ>/<id>. Grupa w mapowaniu nadaje wypisane obok niej zakresy każdemu, kto do niej należy. Grupa bez wpisu nic nie nadaje.

Otwórz Administracja, Mapowanie zakresów.
Wybierz Dodaj grupę i wpisz Grupa: nazwę zaczynającą się od mcp-, złożoną z liter, cyfr, kropek, podkreślników i myślników.
Wpisz Zakresy (jeden w wierszu).
Powtórz dla każdej grupy, potem wybierz Zapisz mapowanie. Jeśli portal o to poprosi, potwierdź tożsamość u dostawcy tożsamości. Wracasz ze swoimi zmianami.

Przykłady:

Grupa	Zakresy
`mcp-jira-proj-ABC`	`Jira::Project/ABC`
`mcp-team-platform`	`Jira::Project/PLAT` `Confluence::Space/PLATFORM`
`mcp-gitlab-team-a`	`GitLab::Group/team-a` (obejmuje podgrupy i projekty pod nią)
`mcp-servicedesk-it`	`ServiceDesk::Queue/IT`

Grupa może mieć jeden zakres albo kilka, jak mcp-team-platform.

Zasady, które gateway sprawdza przy zapisie:

Typ (Jira::Project, GitLab::Group i tak dalej) musi być zadeklarowany przez zarejestrowany serwer, a jego deklaracja musi mieć wzorzec zakresu. Serwery deklarują typy w politykach, które zatwierdziłeś (zobacz Jak dodać i zatwierdzić serwer MCP). Lista Typy zasobów zadeklarowane przez zarejestrowane serwery pod formularzem pokazuje typy i ich wzorce. Typ oznaczony nie można nadać nie ma wzorca zakresu.
Część po ukośniku musi pasować do wzorca zakresu typu. Klucz projektu Jira, na przykład, to wielkie litery, cyfry i podkreślniki, od 2 do 10 znaków.
Grupa występuje raz. Identyfikatory zakresów to tylko ASCII.

Cały dokument zapisuje się naraz. Jeśli jeden zakres jest nieprawidłowy, nic nie zostanie zapisane, a portal pokazuje powód podany przez gateway wraz z odniesieniem dla wsparcia. Formularz ostrzega też o złym typie lub wzorcu przed zapisem.

Mapowanie zakresów z trzema grupami i błędem: jeden zakres wskazuje typ, którego nikt nie deklaruje

Serwery podejmują zapisane mapowanie w ciągu kilku sekund. Jeśli dwóch administratorów edytuje naraz, drugi zapis jest odrzucany, bo dokument się zmienił, a portal pokazuje aktualne mapowanie jeszcze raz (Poniżej aktualne mapowanie; Twoje zmiany nie zostały zachowane.). Gdy usuniesz serwer, znikają razem z nim jego wpisy. Jeśli zatwierdzenie nowych polityk unieważni wpis, ocena pomija go, dopóki go nie poprawisz.

Klienci AI

Gateway przyjmuje wywołania narzędzi tylko od klientów AI, których identyfikator (claim azp tokenu od dostawcy tożsamości) jest na liście. Domyślnie to claude-code i claude-ai (Claude Desktop i claude.ai).

Aby dopuścić innego klienta:

Zarejestruj klienta u dostawcy tożsamości, z odbiorcą (audience) mcp-gateway w jego tokenach. Realm z paczki Compose ma klientów claude-code i claude-ai. Wymagania wobec tokenu: Uwierzytelnianie.
Ustaw listę w środowisku gatewaya, rozdzieloną przecinkami, i uruchom gateway ponownie:
Okno terminala
```
MCP_ALLOWED_CLIENTS=claude-code,claude-ai,<id-twojego-klienta>
```
Sprawdź, czy nowy klient się loguje i wyświetla narzędzia.

Identyfikator klienta zawiera tylko litery, cyfry, kropki, podkreślniki i myślniki (od 1 do 128 znaków). Przy kilku instancjach gatewaya ustaw tę samą wartość na każdej. Zmiana listy podnosi rewizję danych polityk, a gateway przekazuje listę serwerom.

Klient spoza listy jest odrzucany, jakiekolwiek grupy ma użytkownik.