public/idmagicodocs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
idmagicodocs/ID_MAGICO_AUTH_PROCCESS.md

9.9 KiB
Raw Permalink Blame History

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):

{
  "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:

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

Błędy autoryzacji

{
  "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

{
  "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)

{
  "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

{
  "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

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:

{
  "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 View Git Blame Copy Permalink