## Po co to?

Zespoły enterprise potrzebują dwóch rzeczy, żeby spełnić wymogi dotyczące dostępu: pracownicy logują się przez Twojego dostawcę tożsamości (bez osobnych haseł do Kit), a dostęp jest przyznawany i odbierany automatycznie, gdy ktoś dołącza lub odchodzi. Kit obsługuje jedno i drugie — **logowanie SAML single sign-on** dla logowania oraz **synchronizację katalogu Google Workspace** dla automatycznego provisioningu i deprovisioningu.

Oba ustawisz w **Settings → Integrations** i oba wymagają konfiguracji przez administratora.

> [!NOTE]
> SSO i synchronizacja katalogu są niezależne. Możesz włączyć samo SSO, samą synchronizację katalogu albo jedno i drugie naraz.

## Część 1: logowanie SAML single sign-on

SAML SSO pozwala Twojemu zespołowi logować się przez Twojego dostawcę tożsamości (Google Workspace, Okta, Microsoft Entra, OneLogin i inne). Kit jest **service providerem (SP)**, a Twój dostawca tożsamości to **IdP**.

### Krok 1 — przekaż swojemu IdP dane service providera Kit

W konfiguracji aplikacji SAML po stronie IdP użyj tych wartości ze strony ustawień **SSO** w Kit:

| Pole w Twoim IdP | Wartość z Kit |
|---|---|
| ACS URL / Reply URL / Single sign-on URL | `https://app.startupkit.app/users/auth/saml/callback` |
| SP Entity ID / Audience URI | `https://app.startupkit.app/users/auth/saml/metadata` |
| Format Name ID | Adres e-mail |

Dokładne wartości dla Twojego konta zobaczysz na stronie ustawień SSO, a jeśli Twój IdP woli zaimportować metadane, dostępny jest też do pobrania **metadata URL** service providera.

### Krok 2 — zweryfikuj swoją domenę e-mail

Kit przyjmuje logowania SSO tylko dla tych domen e-mail, które **zweryfikowałeś** dla swojego konta (na przykład `acme.com`). To właśnie dzięki temu dostawca tożsamości innej organizacji nie zaloguje użytkowników do Twojego workspace'u. Zweryfikuj domenę w **Settings → Custom Domains / Account** przed włączeniem SSO.

### Krok 3 — wklej dane swojego IdP do Kit

Wróć na stronę ustawień SSO w Kit i wpisz:

- **IdP Entity ID** — Issuer / Entity ID z aplikacji SAML Twojego IdP
- **IdP SSO URL** — adres logowania udostępniany przez Twojego IdP
- **IdP signing certificate** — certyfikat X.509 (PEM), którym Twój IdP podpisuje asercje

Możesz też wkleić **metadata XML** swojego IdP, a Kit uzupełni te pola za Ciebie.

### Krok 4 — włącz SSO

Kliknij **Enable SSO**. Twój zespół może już logować się przez Twojego dostawcę tożsamości. Obsługiwane jest zarówno logowanie inicjowane po stronie IdP (uruchomienie Kit z panelu IdP), jak i standardowe logowanie.

> [!IMPORTANT]
> Gdy nowa osoba loguje się przez SSO po raz pierwszy, Kit zakłada jej konto automatycznie — pod warunkiem, że jej domena e-mail jest zweryfikowana dla Twojego workspace'u. Jeśli użytkownik z takim adresem już istnieje, Kit łączy tożsamość SSO z tym istniejącym kontem.

## Część 2: provisioning katalogu Google Workspace

Synchronizacja katalogu trzyma członków Twojego konta w Kit zgodnie z katalogiem Google Workspace. Ponieważ Google nie wypycha zmian do aplikacji, Kit **pobiera** dane z Google Admin SDK według harmonogramu — to Google jest zawsze źródłem prawdy.

### Krok 1 — autoryzuj konto serwisowe Kit (domain-wide delegation)

**Super admin** Google Workspace musi autoryzować konto serwisowe Kit do odczytu Twojego katalogu:

1. Otwórz konsolę Google Admin → **Security → Access and data control → API controls → Domain-wide delegation**.
2. Kliknij **Add new** i wpisz **Client ID** konta serwisowego Kit (widoczny na stronie ustawień katalogu w Kit).
3. Dodaj te zakresy OAuth **tylko do odczytu**, oddzielone przecinkami:
   - `https://www.googleapis.com/auth/admin.directory.user.readonly`
   - `https://www.googleapis.com/auth/admin.directory.group.readonly`
   - `https://www.googleapis.com/auth/admin.directory.group.member.readonly`
4. Autoryzuj. Propagacja może potrwać kilka minut.

> [!CAUTION]
> Kit prosi wyłącznie o zakresy **tylko do odczytu** — nigdy nie może modyfikować Twojego katalogu Google. Odczytuje Twoich użytkowników i grupy, żeby odzwierciedlić je w Kit.

### Krok 2 — skonfiguruj połączenie w Kit

Na stronie ustawień katalogu w Kit wpisz:

- **Primary domain** — Twoja domena Workspace (na przykład `acme.com`)
- **Delegated admin email** — administrator Workspace, pod którego Kit się podszywa (tylko do odczytu), żeby wylistować katalog
- **Admin group emails** (opcjonalnie) — członkowie tych grup Google dostają rolę administratora konta Kit
- **Google customer ID** — zostaw `my_customer`, chyba że zarządzasz wieloma organizacjami Google

### Krok 3 — przetestuj połączenie

Kliknij **Test connection**. Kit wykona próbny odczyt i zgłosi sukces albo dokładnie powie, czego brakuje:

| Wynik | Co oznacza |
|---|---|
| Active | Domain-wide delegation i zakresy są skonfigurowane poprawnie. |
| Service account not authorized for domain-wide delegation | Client ID nie został dodany w konsoli Admin (krok 1). |
| Missing required directory scopes | Client ID jest autoryzowany, ale nie przyznano zakresów tylko do odczytu. |

## Jak działa provisioning i deprovisioning

Gdy połączenie jest **Active**, Kit uzgadnia skład Twojego zespołu automatycznie.

| Zachowanie | Szczegóły |
|---|---|
| Częstotliwość synchronizacji | Mniej więcej co godzinę. Użyj **Sync now** na stronie katalogu, żeby uruchomić ją od razu. |
| Źródło prawdy | Google Workspace. Kit je odzwierciedla — nigdy nie zapisuje zmian z powrotem. |
| Nowy użytkownik w katalogu | Powstaje konto Kit, a osoba staje się członkiem Twojego workspace'u. |
| Usunięty / zawieszony użytkownik | Jego członkostwo w Kit zostaje usunięte, a tokeny API i sesje połączonych aplikacji są unieważnione. |
| Mapowanie grupa → rola | Członkowie skonfigurowanych przez Ciebie grup administratorów stają się administratorami w Kit. |
| Rozliczanie miejsc | Provisionowany członek domyślnie **zajmuje miejsce** (możesz to przełączyć osobno dla każdego połączenia). Przy wyłączonym automatycznym zajmowaniu miejsc nowi użytkownicy z katalogu nie są dodawani automatycznie. |

### Czego Kit nigdy nie ruszy

- **Właściciel konta** nigdy nie jest usuwany przez synchronizację katalogu, nawet jeśli nie ma go w katalogu.
- **Ręcznie zaproszeni członkowie** nigdy nie są usuwani ani przeklasyfikowani — synchronizacja katalogu zarządza tylko tymi członkami, których sama provisionowała.

> [!TIP]
> Żeby kogoś offboardować, usuń go lub zawieś w Google Workspace. Przy następnej synchronizacji (albo gdy klikniesz **Sync now**) Kit automatycznie odbierze mu dostęp i unieważni jego tokeny.

## Checklist

- [ ] Zweryfikuj swoją domenę e-mail dla konta
- [ ] Skonfiguruj swojego IdP, podając ACS URL i SP Entity ID z Kit
- [ ] Wklej do Kit swój IdP Entity ID, SSO URL i certyfikat podpisujący
- [ ] Włącz SSO i przetestuj logowanie
- [ ] Super admin autoryzuje Client ID konta serwisowego Kit do domain-wide delegation z trzema zakresami tylko do odczytu
- [ ] Wpisz primary domain, delegated admin email i ewentualne grupy administratorów
- [ ] Uruchamiaj **Test connection**, aż zgłosi Active
- [ ] Potwierdź swoją politykę miejsc (automatyczne zajmowanie włączone lub wyłączone)