Baza wiedzy o chmurze

# Autoryzacja

# OAuth

Autoryzacja w API Oktawave jest oparta o specyfikację OAuth2 oraz OpenID Connect (opens new window). Proces uwierzytelnienia wymaga potwierdzenia klienta API (klientem API jest aplikacja) oraz użytkownika, w imieniu którego aplikacja będzie wykonywać operacje.

Aby skorzystać z zasobów API Oktawave, każde żądanie musi być zautoryzowane. Do autoryzacji wymagane jest podanie ważnego tokenu. W tym celu należy wykonać dwie operacje:

  • Stworzyć (zarejestrować) aplikację klienta,
  • Wygenerować token dostępowy na podstawie danych uwierzytelniających aplikację klienta oraz użytkownika.

# Rejestracja aplikacji klienta API Oktawave

Wejdź na stronę id.oktawave.com/core/clients (opens new window) i stwórz nowego klienta reprezentującego aplikację korzystającą z API Oktawave.

Podczas tworzenia klienta należy podać:

  • identyfikator klienta (ten identyfikator będzie potrzebny do operacji generowania tokena),
  • nazwa klienta,
  • hasło (hasło będzie potrzebne do operacji generowania tokena),
  • czas życia tokena.

Każdy użytkownik może stworzyć dowolną liczbę klientów, jak również wiele skryptów może posługiwać się tym samym ClientId.

# Zakres dostępu

Tworząc klienta API użytkownik może określić w jakim zakresie zostanie udzielony mu dostęp do poszczególnych zasobów. Do wyboru są:

  • oktawave.api - całkowity dostęp odczytu i modyfikacji wszystkich zasobów,
  • oktawave.api.readonly - dostęp tylko do zasobów GET, próba dostępu do zasobu modyfikującego zwróci status 403;

Klient może mieć przypisane oba powyższe zakresy i przesyłać tylko wybrane podczas generowania tokenu.

# Token

Następny krok to generowanie tokena. Aby skorzystać z zasobów API, każde żądanie musi być zautoryzowane. Do autoryzacji wymagane jest podanie ważnego tokenu.

Aby go uzyskać, należy wywołać zasób serwera autoryzacyjnego dostępny pod https://id.oktawave.com/core/connect/token (opens new window)

Parametry, które zostały użyte w żądaniu:

  • grant_type - typ autoryzacji, w tym momencie dostępny tylko password i refresh_token
  • username - nazwa użytkownika Oktawave
  • password - hasło użytkownika Oktawave
  • scope - zakres dostępu (dostępne są oktawave.api, oktawave.api.readonly i offline_access)

W odpowiedzi serwer prześle access_token o czasie życia zależnym od ustawień nadanych dla klienta.

# Żądanie

curl -X POST 
-d "grant_type=password&username=test_login&password=test_pass&scope=oktawave.api offline_access"
-u "clientId:clientSecret"
'https://id.oktawave.com/core/connect/token'

# Odpowiedź

{
  "access_token": "09b2c9833d70ec777c406263687853c1",
  "expires_in": 1000,
  "token_type": "Bearer"
}

# Odświeżanie tokena

Tokeny powinny mieć krótki czas życia (zazwyczaj jest to kilka minut). Ma to na celu zabezpieczenie zasobów API, nawet w sytuacji gdy token zostanie wykradziony. Żeby uniknąć podawania danych dostępowych za każdym razem gdy token wygaśnie, można skorzystać z mechanizmu odświeżania tokena.

Aby móc skorzystać z mechanizmu odświeżania, należy przede wszystkim dodać podczas pierwszej autoryzacji dodatkowy zakres dostępu (scope) - offline_access.

curl -X POST 
-d "grant_type=password&username=test_login&password=test_pass&scope=oktawave.api offline_access" 
-u "clientId:clientSecret"
'https://id.oktawave.com/core/connect/token'

Odpowiedź serwera będzie wtedy wyglądała następująco:

{
  "access_token": "09b2c9833d70ec777c406263687853c1",
  "expires_in": 1000,
  "token_type": "Bearer",
  "refresh_token": "77715c5fd2cb6794437aaa560d63bcf3"
}

Odświeżenie tokena polega na wysłaniu (w dowolnym momencie) żądania wraz z otrzymanym refresh_token do następującego zasobu (uwaga, zmienia się grant_type):

curl -X POST 
-d "grant_type=refresh_token&refresh_token=77715c5fd2cb6794437aaa560d63bcf3" 
-u "clientId:clientSecret"
'https://id.oktawave.com/core/connect/token'

W odpowiedzi otrzymamy nowy access_token i refresh_token.

Każdy refresh_token jest jednorazowy, serwer odrzuci próbę odświeżenia jeśli refresh_token był już użyty.

← Przykłady →