Update authentication documentation to clarify token exchange and session setup process

This commit is contained in:
2026-02-18 08:19:30 +01:00
parent 81a4ea51cc
commit 974e78b5a3

View File

@@ -9,8 +9,7 @@ Dokumentacja autentykacji przez Id Magico (https://id.magico.pro) i ustawiania s
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
2. **Token i Sesja** wymiana `code` na `access_token` oraz automatyczne ustawienie sesji wewnętrznie przez backend TravelManager
---
@@ -76,34 +75,33 @@ grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}&client_id=
---
## Krok 2: Ustawianie sesji w API TravelManager
## Krok 2: Automatyczne ustawienie sesji przez backend TravelManager
Mając `access_token` z kroku 1, wywołaj endpoint sesji API TravelManager.
Po otrzymaniu `access_token` z kroku 1, backend TravelManager automatycznie weryfikuje token i ustawia sesję wewnętrznie.
---
## Endpoint ustawiania sesji
## Proces wewnętrzny ustawiania sesji
**POST** `v1/auth/session`
**Proces wewnętrzny** w backendzie TravelManager po otrzymaniu tokena:
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
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
### Nagłówek
W tym miejscu pobierany jest company_id (tenant_id), używany do rozróźnienia tenanta na backendzie
```
Authorization: Bearer {token_z_id_magico}
Content-Type: application/json
```
### Proces weryfikacji tokena
### Przykładowe żądanie
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
```
POST /v1/auth/session
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Accept: application/json
```
### Odpowiedź do aplikacji klienckiej
### Odpowiedź sukces (200)
Po pomyślnym ustawieniu sesji wewnętrznie:
```json
{
@@ -112,7 +110,7 @@ Accept: application/json
}
```
### Odpowiedź błąd (401)
### Błędy autoryzacji
```json
{
@@ -222,11 +220,10 @@ Zmienna środowiskowa: `magico.auth.serwer` (np. `https://id.magico.pro/`).
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`.
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`.
---
@@ -260,9 +257,8 @@ sequenceDiagram
IdMagico->>App: access_token
Note left of IdMagico: {<br/>"access_token": "eyJ...",<br/>"token_type": "Bearer",<br/>"expires_in": 3600<br/>}
App->>API: Ustawienie sesji
Note right of App: POST /v1/auth/session<br/>Authorization: Bearer {access_token}
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}
@@ -270,7 +266,7 @@ sequenceDiagram
Note left of IdMagico: {<br/>"user": {...},<br/>"company_id": 123,<br/>"role": "admin"<br/>}
alt Użytkownik ma prawidłowy token
API->>API: Utworzenie sesji
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
@@ -298,8 +294,7 @@ sequenceDiagram
## 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.
- poprawnej sesji (ciastko `app_session`) ustawionej podczas procesu autoryzacji.
Brak sesji skutkuje odpowiedzią **401 Unauthorized**:
```json