325 lines
9.9 KiB
Markdown
325 lines
9.9 KiB
Markdown
# 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.
|