# 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 i Sesja** – wymiana `code` na `access_token` oraz automatyczne ustawienie sesji wewnętrznie przez backend 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: Automatyczne ustawienie sesji przez backend TravelManager

Po otrzymaniu `access_token` z kroku 1, backend TravelManager automatycznie weryfikuje token i ustawia sesję wewnętrznie.

---

## Proces wewnętrzny ustawiania sesji

**Proces wewnętrzny** w backendzie TravelManager po otrzymaniu tokena:

1. Backend automatycznie weryfikuje token Bearer z Id Magico
2. Pobiera dane użytkownika z Id Magico
3. Ustawia sesję dla użytkownika
4. Zwraca odpowiedź do aplikacji klienckiej

W tym miejscu pobierany jest company_id (tenant_id), używany do rozróźnienia tenanta na backendzie

### Proces weryfikacji tokena

Backend TravelManager wewnętrznie:
- Weryfikuje otrzymany token przez wywołanie Id Magico
- Automatycznie tworzy sesję po pozytywnej weryfikacji
- Nie wymaga dodatkowego wywołania API przez klienta

### Odpowiedź do aplikacji klienckiej

Po pomyślnym ustawieniu sesji wewnętrznie:

```json
{
  "status": true,
  "message": "is login"
}
```

### Błędy autoryzacji

```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 i ustaw sesję** – POST do Id Magico `/oauth/token` (Krok 1.2), następnie backend TravelManager automatycznie weryfikuje token i ustawia sesję wewnętrznie.
4. API zwraca `200` z ustawioną sesją (ciastko `app_session`).
5. Kolejne żądania do chronionych endpointów wysyłają ciastko sesji.
6. Przy wylogowaniu: `POST v1/auth/logout`.

---

## Diagram sekwencji procesu autentykacji



```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?<br/>client_id={client_id}&<br/>redirect_uri={redirect_uri}&<br/>response_type=code&<br/>scope={scope}&<br/>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}?<br/>code={authorization_code}&<br/>state={state}

    User->>App: Powrót z kodem autoryzacyjnym
    App->>IdMagico: Wymiana code na token
    Note right of App: POST /oauth/token<br/>grant_type=authorization_code<br/>code={code}<br/>client_id={client_id}<br/>client_secret={client_secret}

    IdMagico->>App: access_token
    Note left of IdMagico: {<br/>"access_token": "eyJ...",<br/>"token_type": "Bearer",<br/>"expires_in": 3600<br/>}

    Note over App, API: Backend TravelManager automatycznie ustawia sesję
    App->>API: Przekazanie tokena (wewnętrznie)
    API->>IdMagico: Weryfikacja tokena
    Note right of API: GET /api/v1/authorize/me<br/>Authorization: Bearer {access_token}

    IdMagico->>API: Dane użytkownika
    Note left of IdMagico: {<br/>"user": {...},<br/>"company_id": 123,<br/>"role": "admin"<br/>}

    alt Użytkownik ma prawidłowy token
        API->>API: Automatyczne utworzenie sesji
        API->>App: Sukces (200)
        Note left of API: {<br/>"status": true,<br/>"message": "is login"<br/>}<br/>+ 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: {<br/>"status": false,<br/>"message": "401 Unauthorized"<br/>}
        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`) ustawionej podczas procesu autoryzacji.

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.