HyperOne

# Uwierzytelnienie dostępu do Platformy

Większość żądań do API Platformy, wymaga uwierzytelnienia żądania, czyli udowodnienia, że pochodzi ono od uprawnionego Użytkownika.

W celu wykonywania operacji na Platformie poprzez API należy:

  • dokonać uwierzytelnienia Użytkownika, aby uzyskać identyfikator sesji Użytkownika albo
  • utworzyć Konto usługi, aby uzyskać identyfikator Konta Usługi

oraz

  • przesłać wraz z żądaniem token dostępu (identyfikator sesji Użytkownika lub identyfikator Konta Usługi)

# Uwierzytelnianie żądania

Uwierzytelnienie żądań kierowanych do API wymaga tokenu dostępu który może zostać uzyskany jako:

  • sesja Użytkownika
  • Klucz usługi

Poniżej porównanie funkcjonalności obu rozwiązań.

opis sesja Użytkownika Klucz usługi
Utworzenie Poprzez podanie nazwy użytkownika oraz hasła (możliwe także wymagane dwuskładnikowe uwierzytelnienie) Przez Użytkownika dla wybranego Projektu
Protokoły dla utworzenia HTTP, SSH HTTP
Zakres dostępu Możliwość wyboru Projektu dla każdego żądania do API wedle posiadanych uprawnień Użytkownika Jedynie w ramach Projektu do którego został przypisany
Uprawnienia Wszelkie uprawnienie włącznie z możliwością zarządzania Użytkownikiem, Projektami i Organizacją wedle posiadanych uprawnień do nich. Ograniczone do uprawnień w ramach pojedynczego Projektu wyszczególnionych przy tworzeniu z możliwością późniejszej modyfikacji zakresu uprawnień. Brak możliwości zarządzania Użytkownikami, Projektami lub Organizacją
Czas obowiązywania Przez około 1 godziny od ostatniej wykonanej operacji na API z jego użyciem albo do czasu usunięcia Do czasu określonego na stałe podczas utworzenia albo do czasu usunięcia
Zastosowanie Wykorzystanie w panelu oraz CLI w bezpośredniej interakcji z Użytkownikiem W skryptach i wszelkiej automatyzacji
Wymagane parametry x-auth-token oraz x-project w celu podania Projektu dla żądania jedynie x-auth-token
Kanały wykorzystania panel, narzędzie CLI, API narzędzie CLI, API
Dwuskładnikowe uwierzytelnienie zgodnie z konfiguracją Użytkownika tylko przy utworzeniu, brak wymogu przy wykorzystaniu

# Identyfikator sesji Użytkownika

Token dostępu stanowiący identyfikator sesji Użytkownika posiada wszystkie uprawnienia Użytkownika do wszystkich Projektów do których Użytkownik został dodany i pozwala wykonywać operację na nich wszystkich.

Wymagane jest aby każde żądanie do API posiadało dodatkowo w nagłówku pole x-project które będzie definiował w kontekście jakiego Projektu dane żądanie powinno zostać wykonane.

Taka sesja Użytkownika jest wykorzystywana w przypadku Panelu lub narzędzia CLI i powinna identyfikować osobę fizyczną, ponieważ posiada szerokie uprawnienia i ograniczony czas ważności.

# Identyfikator Konta Usługi

Token dostępu stanowiący identyfikator Konta Usługi jest tworzony w ramach pojedynczego Projektu i posiada ograniczone prawa dostępu np. tylko do utworzenia Obrazu lub danych operacji na pojedynczym lub wszystkich zasobach. Jego utworzenie jest prostą operacją.

Ze względu że Konto usługi jest utworzone w ramach Projektu w takim przypadku nie ma konieczności przy wysyłaniu żądania do API podawać w nagłówku pola x-project, ponieważ Projekt jest już zdefiniowany i przypisany do Konta usługi.

Głównym zastosowaniem Konta usługi jest automatyzacja i wykorzystanie w skryptach lub oprogramowaniu bezpośrednio komunikującym się z API, ponieważ poprzez nadanie jedynie bardzo ograniczonych i zawężonych uprawnień zwiększamy bezpieczeństwo. Konto usługi nie posiada dostępu lub nie umożliwia modyfikacji danych Projektu lub Użytkownika ze względów bezpieczeństwa.

Identyfikator Konta Usługi nie ulega zmianie od momentu jego utworzenia do usunięcia przez Użytkownika, co zapewnia stabilność procesów, które go wykorzystują. Jego funkcjonalność może zostać ograniczona poprzez modyfikacje praw dostępu.

# Uwierzytelnienie dla sesji Użytkownika

Uwierzytelnienie Użytkownika w celu uzyskania identyfikatora sesji Użytkownika może odbywać się następującymi metodami:

  • uwierzytelnianie HTTP
  • uwierzytelnianie SSH

Identyfikator sesji Użytkownika niezależny od formy uwierzytelniania ważny jest około 60 godzin od ostatniego żądania. Dowolne żądanie z wykorzystaniem identyfikatora sesji może przedłużyć jego ważność do godziny.

# Uwierzytelnianie dla sesji Użytkownika poprzez HTTP

$ http -v POST https://api.hyperone.com/v1/user/user@example.com/session password="SomePassword"
POST /v1/user/user@example.com/session HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 31
Content-Type: application/json
Host: api.hyperone.com
User-Agent: HTTPie/0.9.2

{
    "password": "SomePassword"
}

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 279
Content-Type: application/json; charset=utf-8
Date: Wed, 14 Nov 2018 16:17:58 GMT
ETag: W/"117-yP0knerlhN5P+EmQ5R/l3XVB7v0"
Referrer-Policy: strict-origin-when-cross-origin
Server: nginx
Set-Cookie: x-auth-token=5beab306913f2d5d821b350c; Path=/; Expires=Wed, 14 Nov 2018 17:17:58 GMT; HttpOnly; Secure
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

{
    "_id": "5beab306913f2d5d821b350c",
    "access": [
        {
            "_id": "5beabe03680cffd11f0e653d",
            "method": "ALL",
            "path": "/"
        }
    ],
    "clientIp": "62.181.3.201",
    "createdBy": "user@example.com",
    "createdOn": "2018-11-14T16:17:58.691Z",
    "expiry": "2018-11-14T17:17:58.691Z",
    "userAgent": "HTTPie/0.9.2"
}

W przypadku dwuskładnikowego uwierzytelniania API może odmówić dostępu, pomimo prawidłowego hasła. Wskazuje wówczas w odpowiedzi dopuszczalne formy dwuskładnikowego uwierzytelniania dla danego Użytkownika:

HTTP/1.1 403 Forbidden
Connection: keep-alive
Content-Length: 95
Content-Type: application/json; charset=utf-8
Date: Wed, 14 Nov 2018 16:22:08 GMT
ETag: W/"5f-B9yRZdFJ8bamT6aiGzDt/Jq8ySs"
Server: nginx

{
    "code": "CHALLENGE_REQUEST",
    "message": "challenge request",
    "status": 403,
    "value": [
        "totp",
        "otac"
    ]
}

Należy wówczas ponowić żądanie przesyłając także kod uwierzytelniający:

$ http -v POST https://hyperone.com/v1/user/user@example.com/session password="SomePassword" challenge:='{"totp":980350}'
POST /v1/user/user@example.com/session HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 65
Content-Type: application/json
Host: api.hyperone.com
User-Agent: HTTPie/0.9.2

{
    "challenge": {
        "totp": 980350
    },
    "password": "SomePassword"
}

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 289
Content-Type: application/json; charset=utf-8
Date: Wed, 14 Nov 2018 16:27:14 GMT
ETag: W/"121-Iz6lTv8neWrXqycLchMC/mvror8"
Referrer-Policy: strict-origin-when-cross-origin
Server: nginx
Set-Cookie: x-auth-token=5beab306913f2d5d821b350c; Path=/; Expires=Wed, 14 Nov 2018 17:27:14 GMT; HttpOnly; Secure
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

{
    "_id": "5beab306913f2d5d821b350c",
    "access": [
        {
            "_id": "5bec4ce23fcfc062ba95aa55",
            "method": "ALL",
            "path": "/"
        }
    ],
    "clientIp": "62.181.3.201",
    "createdBy": "user@example.com",
    "createdOn": "2018-11-14T16:27:14.045Z",
    "expiry": "2018-11-14T17:27:14.044Z",
    "userAgent": "HTTPie/0.9.2"
}

# Uwierzytelnianie dla sesji Użytkownika poprzez SSH

W celu wykorzystania SSH do uwierzytelniania należy uzyskać połączenie SSH z Platformą z wykorzystaniem klucza SSH Użytkownika, która wówczas zwróci identyfikator sesji Użytkownika:

$ ssh -o "User=user@example.com" api.hyperone.com -s rbx-auth
{"_id":"5beab306913f2d5d821b350c","expiry":"2018-11-14T17:42:43.448Z","createdBy":"user@example.com","createdOn":"2018-11-14T16:42:43.449Z","access":[{"_id":"5bec50833fcfc062ba95d0b5","path":"/","method":"ALL"}],"clientIp":"::ffff:10.80.7.50","userAgent":"SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.6"}

# Uwierzytelnienie żądania do Platformy

Token dostępu oraz inne parametry wymagane dla uwierzytelnienia żądania mogą zostać przekazane do API na kilka sposobów.

opis query header cookie
token dostępu authtoken x-auth-token x-auth-token
projekt project x-project -

W przypadku podania parametrów na kilka sposobów zostanie wykorzystany pierwszy znaleziony w następującej kolejności: query, header, cookie.

Jeżeli nie zaznaczono inaczej, wszystkie żądania do API Platformy, wymagają uwierzytelnienia.

Przykładowe poprawne żądanie z wykorzystaniem Konta Usługi:

$ http -v GET https://api.hyperone.com/v1/ip x-auth-token:5af0bbbcb7802508ad844caa
GET /v1/ip HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: api.hyperone.com
User-Agent: HTTPie/0.9.2
x-auth-token: 5af0bbbcb7802508ad844caa


HTTP/1.1 200 OK
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json; charset=utf-8
Date: Wed, 14 Nov 2018 23:47:36 GMT
ETag: W/"b57-N+imK4oxVYs5yAsFHPjgpoAOfSY"
Referrer-Policy: strict-origin-when-cross-origin
Server: nginx
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Transfer-Encoding: chunked
Vary: Accept-Encoding
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

[
    {
        ...
    }
]
← Nagłówki żądania →
Czy uważasz ten artykuł za przydatny? Tak Nie
HyperOne
Zaufanie
Istotne narzędzia
Społeczność
Problemy