Refactor code structure for improved readability and maintainability
This commit is contained in:
330
ID_MAGICO_AUTH_PROCCESS.md
Normal file
330
ID_MAGICO_AUTH_PROCCESS.md
Normal file
@@ -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
|
||||
|
||||
|
||||
|
||||
|
||||
```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/>}
|
||||
|
||||
App->>API: Ustawienie sesji
|
||||
Note right of App: POST /v1/auth/session<br/>Authorization: Bearer {access_token}
|
||||
|
||||
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: 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`), 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.
|
||||
Reference in New Issue
Block a user