diff --git a/COMPANY_MAGICO_APP_MANAGMENT.md b/COMPANY_MAGICO_APP_MANAGMENT.md new file mode 100644 index 0000000..7418cea --- /dev/null +++ b/COMPANY_MAGICO_APP_MANAGMENT.md @@ -0,0 +1,281 @@ +# Zarządzanie aplikacją TravelManager w ekosystemie Magico + +Dokumentacja procesu aktywacji i zarządzania aplikacją TravelManager dla firm w systemie Magico. + +--- + +## Przegląd + +Proces aktywacji TravelManager dla firmy składa się z dwóch głównych kroków: + +1. **Aktywacja aplikacji** – użytkownik/admin włącza TravelManager w panelu Magico +2. **Tworzenie tenanta** – automatyczne utworzenie środowiska dla firmy w TravelManager +3. **Synchronizacja użytkowników** – pobranie listy użytkowników firmy z Magico do TravelManager + +--- + +## Krok 1: Aktywacja aplikacji TravelManager + +### Scenariusze aktywacji + +**Scenariusz A:** Użytkownik w sklepie aplikacji (magico.pro) +- Użytkownik przegląda sklep aplikacji w magico.pro +- Kliknięcie "Aktywuj" przy aplikacji TravelManager + +**Scenariusz B:** Administrator w panelu zarządzania Magico +- Administrator loguje się do panelu zarządzania całym systemem Magico +- Włączenie aplikacji TravelManager dla konkretnej firmy + +### Rezultat aktywacji + +Po kliknięciu aktywacji system Magico wykonuje automatycznie **POST** do TravelManager API w celu utworzenia nowego tenanta. + +--- + +## Krok 2: Tworzenie tenanta w TravelManager + +### Endpoint tworzenia tenanta + +**POST** `manager.travelmanager.pl/api/tenant` + +System Magico automatycznie wywołuje ten endpoint po aktywacji aplikacji. + +### Nagłówki + +``` +Content-Type: application/json +Authorization: Bearer {magico_system_token} +``` + +### Body żądania (minimalne/przykładowe) + +```json +{ + "company_name": "Nazwa Firmy Sp. z o.o.", + "company_id": 34 +} +``` + +| Parametr | Typ | Opis | +|---------------|--------|-----------------------------------------| +| `company_name`| string | Pełna nazwa firmy z systemu Magico | +| `company_id` | int | Unikalny identyfikator firmy w Magico | + +### Odpowiedź sukces (201) + +```json +{ + "status": "success", + "message": "Tenant created successfully", + "tenant_id": "tenant_34_travelmanager", + "company_id": 34, + "created_at": "2026-02-17T10:30:00Z" +} +``` + +### Odpowiedź błąd + +**400 Bad Request** - Nieprawidłowe dane +```json +{ + "status": "error", + "message": "Invalid company data", + "errors": ["company_id is required", "company_name is required"] +} +``` + +**409 Conflict** - Tenant już istnieje +```json +{ + "status": "error", + "message": "Tenant already exists for this company", + "existing_tenant_id": "tenant_34_travelmanager" +} +``` + +--- + +## Krok 3: Synchronizacja użytkowników z Magico + +Po utworzeniu tenanta, TravelManager automatycznie pobiera listę użytkowników firmy z systemu Magico. + +### Endpoint pobierania użytkowników + +**GET** `company.magico.pro/api/company/{company_id}/users` + +TravelManager wykonuje to zapytanie używając tokena systemowego. + +### Nagłówki + +``` +Authorization: Bearer {travelmanager_system_token} +Accept: application/json +``` + +### Parametry URL + +| Parametr | Typ | Opis | +|-------------|-----|-------------------------------------------| +| `company_id`| int | ID firmy (np. 34) z kroku tworzenia tenanta | + +### Przykładowe zapytanie + +``` +GET https://company.magico.pro/api/company/34/users +Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc... +Accept: application/json +``` + +### Odpowiedź Magico API (200) + +```json +{ + "status": "success", + "company_id": 34, + "company_name": "Nazwa Firmy Sp. z o.o.", + "users": [ + { + "name": "Jan Kowalski", + "email": "jan.kowalski@firma.pl", + "global_user_id": 123, + "username": "jan.kowalski", + "role": "admin", + "active": true + }, + { + "name": "Anna Nowak", + "email": "anna.nowak@firma.pl", + "global_user_id": 124, + "username": "anna.nowak", + "role": "user", + "active": true + } + ], + "total_users": 2 +} +``` + +### Struktura użytkownika + +| Pole | Typ | Opis | +|------------------|---------|----------------------------------------| +| `name` | string | Pełne imię i nazwisko użytkownika | +| `email` | string | Adres email użytkownika | +| `global_user_id` | int | Globalny ID użytkownika w systemie Magico | +| `username` | string | Login użytkownika | +| `role` | string | Rola użytkownika (admin, user, etc.) | +| `active` | boolean | Status aktywności konta | + +--- + +## Krok 4: Tworzenie powiązań użytkowników w TravelManager + +### Proces powiązywania + +Po otrzymaniu listy użytkowników z Magico, TravelManager: + +1. **Tworzy rekordy użytkowników** w swoim tenantcie +2. **Zapisuje mapowanie** między `global_user_id` (Magico) a lokalnym ID w TravelManager +3. **Umożliwia powiązanie** użytkowników między systemem Magico a TravelManager + +### Przykładowa struktura w bazie TravelManager + +```sql +-- Tabela tenantów +CREATE TABLE tenants ( + id VARCHAR(50) PRIMARY KEY, + company_id INT NOT NULL, + company_name VARCHAR(255) NOT NULL, + created_at TIMESTAMP DEFAULT NOW() +); + +-- Tabela użytkowników tenanta +CREATE TABLE tenant_users ( + id INT AUTO_INCREMENT PRIMARY KEY, + tenant_id VARCHAR(50) NOT NULL, + global_user_id INT NOT NULL, -- ID z Magico + local_user_id INT, -- lokalne ID w TravelManager + name VARCHAR(255) NOT NULL, + email VARCHAR(255) NOT NULL, + username VARCHAR(100) NOT NULL, + role VARCHAR(50), + active BOOLEAN DEFAULT TRUE, + synced_at TIMESTAMP DEFAULT NOW(), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) +); +``` + +--- + +## Pełny flow aktywacji + +![Diagram procesu tworzenia tenanta](tenant_create_v1.png) + +```mermaid +sequenceDiagram + participant U as Użytkownik/Admin + participant M as Magico.pro + participant T as TravelManager + participant C as Company.Magico.pro + + U->>M: Kliknięcie "Aktywuj TravelManager" + M->>T: POST /api/tenant (company_name, company_id) + T->>T: Tworzenie tenanta w bazie + T->>M: 201 Tenant created + T->>C: GET /api/company/{id}/users + C->>T: Lista użytkowników firmy + T->>T: Tworzenie powiązań użytkowników + M->>U: Aplikacja aktywowana pomyślnie +``` + +--- + +## Bezpieczeństwo i tokeny + +### Tokeny systemowe + +- **Magico System Token** - używany do tworzenia tenantów w TravelManager +- **TravelManager System Token** - używany do pobierania użytkowników z Magico + +### Konfiguracja tokenów + +Tokeny muszą być skonfigurowane w: +- **Magico** - endpoint TravelManager dla tworzenia tenantów +- **TravelManager** - endpoint Magico dla pobierania użytkowników +- **Company.Magico.pro** - autoryzacja zapytań od TravelManager + +--- + +## Obsługa błędów + +### Scenariusze błędów + +1. **Błąd tworzenia tenanta** + - Logowanie błędu w systemie Magico + - Informowanie użytkownika o problemie z aktywacją + +2. **Błąd pobierania użytkowników** + - Tenant zostaje utworzony, ale bez użytkowników + - Możliwość ponownej synchronizacji + +3. **Problemy z tokenami** + - Sprawdzanie ważności tokenów systemowych + - Procedury odnawiania tokenów + +### Retry i ponowne próby + +- **Retry logic** dla zapytań HTTP +- **Timeout** dla długotrwałych operacji +- **Kolejka zadań** dla operacji asynchronicznych + +--- + + +### Logi systemowe + +Każda operacja powinna być logowana: +- Aktywacja aplikacji przez użytkownika +- Tworzenie tenanta +- Pobieranie użytkowników +- Błędy i wyjątki + diff --git a/COMPANY_MAGICO_APP_MANAGMENT_V2.md b/COMPANY_MAGICO_APP_MANAGMENT_V2.md new file mode 100644 index 0000000..44549e2 --- /dev/null +++ b/COMPANY_MAGICO_APP_MANAGMENT_V2.md @@ -0,0 +1,345 @@ +# Zarządzanie aplikacją TravelManager w ekosystemie Magico + +Dokumentacja procesu aktywacji i zarządzania aplikacją TravelManager dla firm w systemie Magico. + +--- + +## Przegląd + +Proces aktywacji TravelManager dla firmy składa się z następujących kroków: + +1. **Aktywacja aplikacji** – użytkownik/admin włącza TravelManager w panelu Magico +2. **Tworzenie tenanta z użytkownikami** – automatyczne utworzenie środowiska dla firmy w TravelManager wraz z przesłaniem listy użytkowników +3. **Synchronizacja zmian** – automatyczne aktualizowanie listy użytkowników przy każdej zmianie w systemie Magico + +--- + +## Krok 1: Aktywacja aplikacji TravelManager + +### Scenariusze aktywacji + +**Scenariusz A:** Użytkownik w sklepie aplikacji (magico.pro) +- Użytkownik przegląda sklep aplikacji w magico.pro +- Kliknięcie "Aktywuj" przy aplikacji TravelManager + +**Scenariusz B:** Administrator w panelu zarządzania Magico +- Administrator loguje się do panelu zarządzania całym systemem Magico +- Włączenie aplikacji TravelManager dla konkretnej firmy + +### Rezultat aktywacji + +Po kliknięciu aktywacji system Magico: +1. Pobiera listę użytkowników firmy z bazy danych +2. Wykonuje automatycznie **POST** do TravelManager API z pełnymi danymi tenanta i użytkowników + +--- + +## Krok 2: Tworzenie tenanta z użytkownikami w TravelManager + +### Endpoint tworzenia tenanta z użytkownikami + +**POST** `manager.travelmanager.pl/api/tenant` + +System Magico automatycznie wywołuje ten endpoint po aktywacji aplikacji, przesyłając od razu pełną listę użytkowników firmy. + +### Nagłówki + +``` +Content-Type: application/json +Authorization: Bearer {magico_system_token} +``` + +### Body żądania + +```json +{ + "company_name": "Nazwa Firmy Sp. z o.o.", + "company_id": 34, + "users": [ + { + "name": "Jan Kowalski", + "email": "jan.kowalski@firma.pl", + "global_user_id": 123, + "username": "jan.kowalski", + "role": "admin", + "active": true + }, + { + "name": "Anna Nowak", + "email": "anna.nowak@firma.pl", + "global_user_id": 124, + "username": "anna.nowak", + "role": "user", + "active": true + } + ] +} +``` + +| Parametr | Typ | Opis | +|---------------|--------|-----------------------------------------| +| `company_name`| string | Pełna nazwa firmy z systemu Magico | +| `company_id` | int | Unikalny identyfikator firmy w Magico | +| `users` | array | Lista wszystkich użytkowników firmy | + +### Struktura użytkownika w tablicy `users` + +| Pole | Typ | Opis | +|------------------|---------|----------------------------------------| +| `name` | string | Pełne imię i nazwisko użytkownika | +| `email` | string | Adres email użytkownika | +| `global_user_id` | int | Globalny ID użytkownika w systemie Magico | +| `username` | string | Login użytkownika | +| `role` | string | Rola użytkownika (admin, user, etc.) | +| `active` | boolean | Status aktywności konta | + +### Odpowiedź sukces (201) + +```json +{ + "status": "success", + "message": "Tenant created successfully with users", + "tenant_id": "tenant_34_travelmanager", + "company_id": 34, + "users_imported": 2, + "created_at": "2026-02-17T10:30:00Z" +} +``` + +### Odpowiedź błąd + +**400 Bad Request** - Nieprawidłowe dane +```json +{ + "status": "error", + "message": "Invalid company data", + "errors": ["company_id is required", "company_name is required"] +} +``` + +**409 Conflict** - Tenant już istnieje +```json +{ + "status": "error", + "message": "Tenant already exists for this company", + "existing_tenant_id": "tenant_34_travelmanager" +} +``` + +--- + +## Krok 3: Synchronizacja zmian użytkowników + +Kiedy lista użytkowników w systemie Magico ulegnie zmianie (dodanie, usunięcie, edycja użytkownika), system automatycznie wysyła aktualizację do wszystkich połączonych aplikacji, w tym TravelManager. + +### Endpoint aktualizacji użytkowników + +**PUT** `manager.travelmanager.pl/api/tenant/{company_id}/users` + +Magico.pro wywołuje ten endpoint za każdym razem gdy: +- Dodany zostanie nowy użytkownik do firmy +- Usunięty zostanie użytkownik z firmy +- Zmienione zostaną dane użytkownika (email, rola, status aktywności) +- Zmieniony zostanie status aktywności użytkownika + +### Nagłówki + +``` +Content-Type: application/json +Authorization: Bearer {magico_system_token} +``` + +### Parametry URL + +| Parametr | Typ | Opis | +|-------------|-----|-------------------------------------------| +| `company_id`| int | ID firmy (np. 34) dla której aktualizujemy użytkowników | + +### Body żądania + +```json +{ + "company_id": 34, + "company_name": "Nazwa Firmy Sp. z o.o.", + "users": [ + { + "name": "Jan Kowalski", + "email": "jan.kowalski@firma.pl", + "global_user_id": 123, + "username": "jan.kowalski", + "role": "admin", + "active": true + }, + { + "name": "Anna Nowak", + "email": "anna.nowak@firma.pl", + "global_user_id": 124, + "username": "anna.nowak", + "role": "user", + "active": true + }, + { + "name": "Michał Wiśniewski", + "email": "michal.wisniewski@firma.pl", + "global_user_id": 125, + "username": "michal.wisniewski", + "role": "user", + "active": true + } + ], + "total_users": 3, + "updated_at": "2026-02-17T11:45:00Z" +} +``` + +### Odpowiedź TravelManager (200) + +```json +{ + "status": "success", + "message": "Users synchronized successfully", + "company_id": 34, + "users_updated": 3, + "users_added": 1, + "users_removed": 0, + "users_modified": 2, + "synchronized_at": "2026-02-17T11:45:15Z" +} +``` + +--- + +## Krok 4: Zarządzanie użytkownikami w TravelManager + +### Proces zarządzania + +TravelManager otrzymuje pełną listę użytkowników od Magico i: + +1. **Podczas tworzenia tenanta:** + - Tworzy rekordy wszystkich użytkowników w swoim tenantcie + - Zapisuje mapowanie między `global_user_id` (Magico) a lokalnym ID w TravelManager + +2. **Podczas synchronizacji zmian:** + - Porównuje otrzymaną listę z aktualnym stanem + - Dodaje nowych użytkowników + - Usuwa użytkowników nieobecnych na nowej liście + - Aktualizuje dane zmodyfikowanych użytkowników + +### Przykładowa struktura w bazie TravelManager + +```sql +-- Tabela tenantów +CREATE TABLE tenants ( + id VARCHAR(50) PRIMARY KEY, + company_id INT NOT NULL, + company_name VARCHAR(255) NOT NULL, + created_at TIMESTAMP DEFAULT NOW() +); + +-- Tabela użytkowników tenanta +CREATE TABLE tenant_users ( + id INT AUTO_INCREMENT PRIMARY KEY, + tenant_id VARCHAR(50) NOT NULL, + global_user_id INT NOT NULL, -- ID z Magico + local_user_id INT, -- lokalne ID w TravelManager + name VARCHAR(255) NOT NULL, + email VARCHAR(255) NOT NULL, + username VARCHAR(100) NOT NULL, + role VARCHAR(50), + active BOOLEAN DEFAULT TRUE, + synced_at TIMESTAMP DEFAULT NOW(), + FOREIGN KEY (tenant_id) REFERENCES tenants(id) +); +``` + +--- + +## Pełny flow aktywacji +![Diagram procesu tworzenia tenanta](tenant_create_v2.png) + +```mermaid +sequenceDiagram + participant U as Użytkownik/Admin + participant M as Magico.pro + participant DB as Magico DB + participant T as TravelManager + + U->>M: Kliknięcie "Aktywuj TravelManager" + M->>DB: Pobierz listę użytkowników firmy + DB->>M: Lista użytkowników + M->>T: POST /api/tenant (company_name, company_id, users[]) + T->>T: Tworzenie tenanta + import użytkowników + T->>M: 201 Tenant created with users + M->>U: Aplikacja aktywowana pomyślnie +``` + +## Flow synchronizacji zmian +![Diagram procesu tworzenia tenanta](tenant_user_sync_v2.png) + +```mermaid +sequenceDiagram + participant A as Admin/System + participant M as Magico.pro + participant DB as Magico DB + participant T as TravelManager + + A->>M: Dodanie/edycja/usunięcie użytkownika + M->>DB: Aktualizacja danych użytkownika + M->>DB: Pobierz aktualną listę użytkowników firmy + DB->>M: Aktualna lista użytkowników + M->>T: PUT /api/tenant/{company_id}/users (users[]) + T->>T: Synchronizacja użytkowników + T->>M: 200 Users synchronized +``` + +--- + +## Bezpieczeństwo i tokeny + +### Tokeny systemowe + +- **Magico System Token** - używany do tworzenia tenantów i synchronizacji użytkowników w TravelManager + +### Konfiguracja tokenów + +Tokeny muszą być skonfigurowane w: +- **Magico** - endpoint TravelManager dla tworzenia tenantów i synchronizacji użytkowników +- **TravelManager** - autoryzacja zapytań od systemu Magico + +--- + +## Obsługa błędów + +### Scenariusze błędów + +1. **Błąd tworzenia tenanta z użytkownikami** + - Logowanie błędu w systemie Magico + - Informowanie użytkownika o problemie z aktywacją + - Rollback - brak utworzenia tenanta + +2. **Błąd synchronizacji użytkowników** + - Logowanie błędu synchronizacji + - Retry automatyczny po określonym czasie + - Alert dla administratorów o problemach synchronizacji + +3. **Problemy z tokenami** + - Sprawdzanie ważności tokena systemowego Magico + - Procedury odnawiania tokenów + +### Retry i ponowne próby + +- **Retry logic** dla zapytań synchronizacji użytkowników (maksymalnie 3 próby) +- **Timeout** dla długotrwałych operacji (30 sekund) +- **Kolejka zadań** dla operacji synchronizacji w przypadku błędów + +--- + + +### Logi systemowe + +Każda operacja powinna być logowana: +- Aktywacja aplikacji przez użytkownika +- Tworzenie tenanta z użytkownikami +- Synchronizacja zmian użytkowników (dodanie, usunięcie, modyfikacja) +- Błędy i wyjątki + diff --git a/ID_MAGICO_AUTH_PROCCESS.md b/ID_MAGICO_AUTH_PROCCESS.md new file mode 100644 index 0000000..bd7d7ba --- /dev/null +++ b/ID_MAGICO_AUTH_PROCCESS.md @@ -0,0 +1,330 @@ +# Logowanie i ustawianie sesji z Id Magico + +Dokumentacja autentykacji przez Id Magico (https://id.magico.pro) i ustawiania sesji w API TravelManager. + +--- + +## Przegląd + +API TravelManager korzysta z **Id Magico** jako centralnego systemu autentykacji. Pełny flow: + +1. **OAuth** – przekierowanie użytkownika do Id Magico, otrzymanie `code` +2. **Token** – wymiana `code` na `access_token` +3. **Sesja** – użycie tokena w `POST v1/auth/session` do ustawienia sesji w API TravelManager + +--- + +## Krok 1: Uzyskiwanie tokena (OAuth 2.0 – Authorization Code) + +### 1.1. Generowanie linku autoryzacyjnego + +Przekieruj użytkownika do Id Magico, aby się zalogował. Skonstruuj URL: + +``` +GET {id.baseURL}oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}&state={state} +``` + +| Parametr | Opis | +|----------------|----------------------------------------------------------------------| +| `client_id` | ID aplikacji w Id Magico (otrzymane przy rejestracji klienta OAuth) | +| `redirect_uri` | Adres powrotu po autoryzacji – musi być zarejestrowany w Id Magico | +| `response_type`| Stała: `code` | +| `scope` | Zakres uprawnień (np. `openid`, `profile` – wg dokumentacji Id Magico) | +| `state` | Losowy ciąg do weryfikacji (zabezpieczenie CSRF) | + +**Przykład:** + +``` +https://id.magico.pro/oauth/authorize?client_id=travelmanager&redirect_uri=https://manager.travel360.pl/auth/callback&response_type=code&scope=openid&state=abc123xyz +``` + +Użytkownik zaloguje się w Id Magico. Po akceptacji zostanie przekierowany z powrotem na `redirect_uri` z parametrem `code`: + +``` +https://manager.travel360.pl/auth/callback?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&state=abc123xyz +``` + +### 1.2. Wymiana code na access_token + +Wyślij żądanie POST do endpointu tokenów Id Magico: + +``` +POST {id.baseURL}oauth/token +Content-Type: application/x-www-form-urlencoded + +grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret} +``` + +| Parametr | Opis | +|-----------------|---------------------------------------------------------------| +| `grant_type` | Stała: `authorization_code` | +| `code` | Kod autoryzacyjny z kroku 1 (jeden raz, krótko ważny) | +| `redirect_uri` | Ten sam adres co w żądaniu autoryzacji | +| `client_id` | ID aplikacji | +| `client_secret` | Tajny klucz aplikacji (tylko po stronie serwera) | + +**Przykład odpowiedzi (200):** + +```json +{ + "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", + "token_type": "Bearer", + "expires_in": 3600 +} +``` + + +--- + +## Krok 2: Ustawianie sesji w API TravelManager + +Mając `access_token` z kroku 1, wywołaj endpoint sesji API TravelManager. + +--- + +## Endpoint ustawiania sesji + +**POST** `v1/auth/session` + +Weryfikuje token Bearer z Id Magico i ustawia sesję. W tym miejscu zwracany jest company_id (tenant_id), używany do rozróźnienia tenanta na backendzie + +### Nagłówek + +``` +Authorization: Bearer {token_z_id_magico} +Content-Type: application/json +``` + +### Przykładowe żądanie + +``` +POST /v1/auth/session +Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc... +Accept: application/json +``` + +### Odpowiedź sukces (200) + +```json +{ + "status": true, + "message": "is login" +} +``` + +### Odpowiedź błąd (401) + +```json +{ + "status": false, + "message": "401 Unauthorized" +} +``` + +Błąd 401 zwracany jest gdy: +- token jest nieprawidłowy lub wygasły, + +--- + +## Co jest zapisywane w sesji + +Po poprawnym wywołaniu `v1/auth/session` w sesji zapisywane są m.in.: + +| Klucz sesji | Opis | +|---------------|--------------------------------------------------| +| `userdata` | Obiekt z danymi użytkownika (patrz niżej) | +| `user_id` | ID użytkownika z Id Magico | + +### Struktura `userdata` + +```json +{ + "username": "jan.kowalski", + "id": 123, + "user_id": 123, + "level": "admin", + "image": "https://...", + "name": "Jan Kowalski", + "client_id": 123, + "guid": "uuid-guid", + "company_id": 123, + "token": "eyJ0eXAiOiJKV1QiLCJhbGc..." +} +``` + +| Pole | Opis | +|-------------|-------------------------------------------| +| `username` | Login użytkownika | +| `user_id` | ID użytkownika w Id Magico | +| `level` | Rola (np. `admin`) | +| `company_id`| ID firmy | +| `token` | Token Bearer z Id Magico | +| `guid` | Identyfikator GUID z Id Magico | + +--- + +## Wylogowanie + +**GET** `v1/auth/logout` +**POST** `v1/auth/logout` + +Niszczy sesję i usuwa dane użytkownika. + +### Przykład + +``` +POST /v1/auth/logout +Cookie: app_session=... +``` + +### Odpowiedź (200) + +```json +{ + "status": true, + "message": "logout" +} +``` + +--- + +## Weryfikacja tokena w Id Magico + +API TravelManager weryfikuje token przez wywołanie Id Magico: + +``` +GET {magico.auth.serwer}api/v1/authorize/me +Authorization: Bearer {token} +Accept: application/json +``` + +Zmienna środowiskowa: `magico.auth.serwer` (np. `https://id.magico.pro/`). + +### Oczekiwana odpowiedź Id Magico + +```json +{ + "user": { + "username": "jan.kowalski", + "user_id": 123, + "image": "https://...", + "name": "Jan Kowalski" + }, + "company_id": 123, + "role": "admin", + "guid": "uuid-guid" +} +``` + +--- + +## Flow integracji (pełny przebieg) + +1. **Generuj link** do Id Magico (Krok 1.1) i przekieruj użytkownika. +2. Po zalogowaniu Id Magico przekierowuje na `redirect_uri` z parametrem `code`. +3. **Wymień `code` na token** – POST do Id Magico `/oauth/token` (Krok 1.2). +4. **Ustaw sesję** – `POST v1/auth/session` z nagłówkiem `Authorization: Bearer {access_token}`. +5. API zwraca `200` i ustawia sesję (ciastko `app_session`). +6. Kolejne żądania do chronionych endpointów wysyłają ciastko sesji. +7. Przy wylogowaniu: `POST v1/auth/logout`. + +--- + +## Diagram sekwencji procesu autentykacji + +![Diagram procesu tworzenia tenanta](tenant_auth.png) + + +```mermaid +sequenceDiagram + participant User as Użytkownik + participant App as Aplikacja TravelManager + participant IdMagico as Id Magico + participant API as TravelManager API + + Note over User, API: OAuth 2.0 Authorization Code Flow + + User->>App: Chce się zalogować + App->>User: Przekierowanie do Id Magico + Note right of App: GET /oauth/authorize?
client_id={client_id}&
redirect_uri={redirect_uri}&
response_type=code&
scope={scope}&
state={state} + + User->>IdMagico: Logowanie użytkownika + IdMagico->>User: Formularz logowania + User->>IdMagico: Dane logowania + IdMagico->>User: Przekierowanie z kodem + Note right of IdMagico: Redirect na: {redirect_uri}?
code={authorization_code}&
state={state} + + User->>App: Powrót z kodem autoryzacyjnym + App->>IdMagico: Wymiana code na token + Note right of App: POST /oauth/token
grant_type=authorization_code
code={code}
client_id={client_id}
client_secret={client_secret} + + IdMagico->>App: access_token + Note left of IdMagico: {
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 3600
} + + App->>API: Ustawienie sesji + Note right of App: POST /v1/auth/session
Authorization: Bearer {access_token} + + API->>IdMagico: Weryfikacja tokena + Note right of API: GET /api/v1/authorize/me
Authorization: Bearer {access_token} + + IdMagico->>API: Dane użytkownika + Note left of IdMagico: {
"user": {...},
"company_id": 123,
"role": "admin"
} + + alt Użytkownik ma prawidłowy token + API->>API: Utworzenie sesji + API->>App: Sukces (200) + Note left of API: {
"status": true,
"message": "is login"
}
+ cookie app_session + App->>User: Zalogowany - dostęp do aplikacji + + Note over User, API: Dalsze żądania z ciastkiem sesji + User->>App: Żądania do chronionych zasobów + App->>API: Żądania z cookie app_session + API->>App: Odpowiedzi (autoryzowane) + App->>User: Dane/funkcjonalność + + Note over User, API: Wylogowanie + User->>App: Wyloguj + App->>API: POST /v1/auth/logout + API->>App: Sukces wylogowania + App->>User: Wylogowany + else Nieprawidłowy token lub brak uprawnień + API->>App: Błąd (401) + Note left of API: {
"status": false,
"message": "401 Unauthorized"
} + App->>User: Błąd autoryzacji + end +``` + +--- + +## Endpointy chronione + +Endpointy z filtrem `login` (np. `v1/project`, `v1/ticket`, `v1/setting`) wymagają: +- poprawnej sesji (ciastko `app_session`), lub +- wcześniejszego wywołania `POST v1/auth/session` z tokenem Bearer. + +Brak sesji skutkuje odpowiedzią **401 Unauthorized**: +```json +{ + "status": false, + "data": [], + "message": "Nieautoryzowany dostęp" +} +``` + +--- + +## Konfiguracja + +| Zmienna | Opis | +|----------------------|-----------------------------------------------------| +| `magico.auth.serwer` | URL serwera Id Magico (np. `https://id.magico.pro/`) | +| `id.baseURL` | URL panelu Id Magico (np. `https://id.magico.pro/`) | + +Dla OAuth (krok 1) potrzebujesz także `client_id` i `client_secret` aplikacji zarejestrowanej w Id Magico. `redirect_uri` musi być zgłoszony w konfiguracji klienta OAuth. + +--- + +## Uwagi + +- Token Bearer jest przekazywany **tylko przy wywołaniu** `v1/auth/session`. +- Po ustawieniu sesji używane jest **ciastko sesji** (`app_session`), nie token w nagłówku. diff --git a/tenant_auth.png b/tenant_auth.png new file mode 100644 index 0000000..10095c0 Binary files /dev/null and b/tenant_auth.png differ diff --git a/tenant_create_v1.png b/tenant_create_v1.png new file mode 100644 index 0000000..e989aae Binary files /dev/null and b/tenant_create_v1.png differ diff --git a/tenant_create_v2.png b/tenant_create_v2.png new file mode 100644 index 0000000..5e4bfc5 Binary files /dev/null and b/tenant_create_v2.png differ diff --git a/tenant_user_sync_v2.png b/tenant_user_sync_v2.png new file mode 100644 index 0000000..ad56792 Binary files /dev/null and b/tenant_user_sync_v2.png differ