API tokenləri ilə autentifikasiyadan keçin
Hər REST API sorğusu ilə API tokeni və ya xidmət hesabı açarı göndərin, hər giriş məlumatının nələrə çata bildiyini və sorğunun niyə rədd edildiyini öyrənin.
Hər REST API sorğusu Authorization başlığında giriş məlumatı daşıyır. Bu məqalə onu necə göndərməyi, hər növ giriş məlumatının nələrə çata bildiyini və sorğu rədd edildikdə nə etməli olduğunuzu göstərir.
Başlamazdan əvvəl
- Giriş məlumatı əldə edin. Identity & AccessAPI tokens bölməsində API tokeni (API token) və ya Identity & AccessService Accounts bölməsində xidmət hesabı (service account) üçün açar yaradın. API tokeni yaradın və Açarları idarə edin bölmələrinə baxın.
- API tokenləri yaratmaq üçün Owner rolu və ya API tokenlərini idarə edə bilən fərdi rol (custom role) lazımdır. Contributor və Reader rolları onlara yalnız baxa bilər.
- Sirr (secret) göstərildiyi anda onu saxlayın. Sirr bir dəfə göstərilir.
Giriş məlumatını seçin
| Giriş məlumatı | Başlanğıcı | Kimin adından işləyir | Nə edə bilər |
|---|---|---|---|
| API tokeni | pc_live_ | Onu yaradan istifadəçi | Həmin istifadəçinin rolunun hər layihədə (project) icazə verdiyi əməliyyatlar, yalnız tokenin miqyasları (scope) daxilində |
| Xidmət hesabı açarı | sak_live_ | Xidmət hesabı | Xidmət hesabına verilmiş rolların icazə verdikləri, yalnız açarın miqyasları daxilində |
İnsanlar ayrıldıqda və ya rolları dəyişdikdə işləməyə davam etməli olan avtomatlaşdırma üçün xidmət hesabı açarından istifadə edin. İstifadəçi silindikdə onun API tokenləri ləğv edilir, istifadəçinin hesabı qeyri-aktiv olduğu müddətdə isə onlar işləmir.
Bu giriş məlumatlarının heç biri openstack CLI və ya Terraform kimi OpenStack alətləri ilə işləmir. Bu alətlər OpenStack tətbiq giriş məlumatından (application credential) istifadə edir. OpenStack ilə uyğun alətlər səhifəsinə baxın.
Giriş məlumatını göndərin
Giriş məlumatını hər sorğunun Authorization başlığında Bearer sözündən sonra yerləşdirin. Onun işlədiyini yoxlamaq üçün öz kimliyinizi oxuyun:
curl "https://<api-host>/api/v1/account/whoami" \
-H "Authorization: Bearer $PC_TOKEN"<api-host>: API-nin host adı.PC_TOKEN: API tokenini və ya xidmət hesabı açarını saxlayan mühit dəyişəni.
200 OK cavabı giriş məlumatının çata bildiyi tenant-ları, abunəlikləri (subscription) və layihələri sadalayır. 401 Unauthorized cavabı giriş məlumatının etibarsız olduğunu bildirir. Nasazlığın həlli bölməsinə baxın.
Giriş məlumatlarını mənbə kodunda və versiya nəzarəti sistemində saxlamayın. Onları nümunədəki kimi sirr anbarından və ya mühit dəyişənindən yükləyin.
Token miqyasları
API tokenini iki şey məhdudlaşdırır: onu yaradan istifadəçinin rolu və onun üçün seçdiyiniz miqyaslar. Sorğu yalnız hər ikisi icazə verdikdə keçir. Məsələn, istifadəçisinin layihədə Reader rolu varsa, compute:write miqyaslı token virtual maşın (instance) yarada bilməz. write miqyası uyğun read miqyasını əhatə etmir: token resursu həm dəyişəcək, həm oxuyacaqsa, hər ikisini seçin.
Kataloqda 17 miqyas var: səkkiz sahənin hər biri üçün bir read və bir write miqyası, bir də audit:read.
| Miqyas | İcazə verir |
|---|---|
compute:read | Virtual maşınların, ölçülərin (size), açar cütlərinin (key pair), obrazların (image), virtual maşın ani görüntülərinin (snapshot) və virtual maşın göstəricilərinin oxunması. |
compute:write | Həmin resursların yaradılması, dəyişdirilməsi və silinməsi, həmçinin başlatma və dayandırma kimi virtual maşın əməliyyatları. |
storage:read | Disklərin (volume), disk ani görüntülərinin, disk ötürmələrinin, ehtiyat nüsxə planlarının (backup plan), fayl paylaşımlarının və bucket-lərin oxunması. |
storage:write | Həmin resursların yaradılması, dəyişdirilməsi və silinməsi. |
network:read | Şəbəkələrin (network), altşəbəkələrin (subnet), marşrutlaşdırıcıların (router), şəbəkə interfeyslərinin, Floating IP-lərin, təhlükəsizlik qruplarının (security group) və Site-to-Site VPN resurslarının oxunması. |
network:write | Həmin resursların yaradılması, dəyişdirilməsi və silinməsi. |
loadbalancer:read | Load balancer-lərin və onların istifadə etdiyi sertifikatların oxunması. |
loadbalancer:write | Həmin resursların yaradılması, dəyişdirilməsi və silinməsi. |
kubernetes:read | Kubernetes resurslarının oxunması, onların əməliyyatlarının və hadisələrinin izlənməsi. |
kubernetes:write | Həmin resursların yaradılması, dəyişdirilməsi və silinməsi. |
observability:read | Xəbərdarlıq qaydalarının, bildiriş kanallarının və sağlamlıq hadisələrinin oxunması. |
observability:write | Xəbərdarlıq qaydalarının və bildiriş kanallarının yaradılması, dəyişdirilməsi və silinməsi. |
billing:read | Xərc məlumatlarının, büdcələrin (budget), öhdəliklərin (commitment), hesab-fakturaların (invoice), kreditlərin, ödəniş üsullarının və kvotaların oxunması. |
billing:write | Ödəniş və xərc məlumatlarının dəyişdirilməsi, məsələn, büdcənin yaradılması, kuponun aktivləşdirilməsi və ya kvotanın artırılmasının tələb edilməsi. |
iam:read | İstifadəçilərin, rolların, xidmət hesablarının və API tokenlərinin, həmçinin Activity Log fəaliyyət qeydlərinin oxunması. |
iam:write | Kimlik və giriş dəyişiklikləri: istifadəçilərin dəvət edilməsi, rolların verilməsi, xidmət hesablarının və API tokenlərinin idarə edilməsi, daxil olma siyasətinin və vahid daxil olmanın (single sign-on) dəyişdirilməsi. |
audit:read | Activity Log fəaliyyət qeydlərinin oxunması. |
Activity Log iam:read və ya audit:read miqyasını qəbul edir: tokenə onlardan yalnız biri kifayətdir.
Abunəliyin və ya layihənin silinməsi üçün iam:write və hər resurs sahəsinin yazma miqyası lazımdır: compute:write, storage:write, network:write, loadbalancer:write, kubernetes:write və observability:write.
Abunəlik yaratmaq üçün iam:write və billing:write lazımdır, çünki abunəlik ödəniş hesabıdır.
Konsolda miqyasları API tokeni və ya xidmət hesabı açarı yaradarkən seçirsiniz. API-də token yaradarkən onları scopes sahəsində göndərirsiniz.
API tokeninin çağıra bilmədiyi əməliyyatlar
Token, miqyasına malik olduğu API-nin hər sahəsini çağıra bilər, o cümlədən Identity & Access Management və ödənişdəki dəyişiklikləri. Bu məhdudiyyətlər hər token üçün keçərlidir:
- Yalnız konsol əməliyyatları. Bəzi əməliyyatlar heç vaxt token qəbul etmir. Konsol seansı tələb edən əməliyyatlar bölməsinə baxın.
- Tokendən yuxarı giriş məlumatı yoxdur. Token başqa token və ya xidmət hesabı açarını yalnız özündə olan miqyaslarla yarada bilər. Özündə olmayan miqyas
403 ForbiddenvəTOKEN_SCOPE_MISSINGsəbəbi ilə rədd edilir. - Tokendən uzunömürlü giriş məlumatı yoxdur. Müddəti bitəcək token daha gec bitəcək və ya heç vaxt bitməyəcək token yarada və ya yeniləyə bilməz. Belə tokenin yaratdığı xidmət hesabı açarı tokendən gec bitmir. Rədd cavabı
403 ForbiddenvəTOKEN_FENCE_EXCEEDEDsəbəbidir. - Tokenin IP icazə siyahısından kənar giriş məlumatı yoxdur. IP icazə siyahısı olan token yalnız boş olmayan icazə siyahısı öz siyahısının daxilində qalan tokenləri yarada və ya yeniləyə bilər. Açarın icazə siyahısı olmadığından xidmət hesabı açarı yarada bilməz. Rədd cavabı
403 ForbiddenvəTOKEN_FENCE_EXCEEDEDsəbəbidir.
Xidmət hesabı açarı miqyasları
Xidmət hesabı açarının da miqyasları var; xidmət hesabının rollarına əlavə olaraq API tokeni ilə eyni miqyas yoxlamasından keçir. Açar yaradarkən miqyaslarını iam:write olmayan kataloqdan seçirsiniz. Miqyassız yaradılmış açar iam:write istisna olmaqla bütün miqyasları alır. iam:write tələb edən sorğu 422 Unprocessable Entity ilə rədd edilir.
Açar, miqyasları nə olursa olsun, iam:write tələb edən hər əməliyyatda 403 Forbidden və INTERACTIVE_SESSION_REQUIRED kodu ilə rədd edilir. Nümunələr: istifadəçilərin dəvət edilməsi, rolların verilməsi və token və ya açarın yaradılması. Bu dəyişiklikləri konsolda və ya iam:write miqyaslı API tokeni ilə edin.
Giriş məlumatı harada işləyir
- Bir tenant. Giriş məlumatı yalnız yaradıldığı tenant-da işləyir. Başqa tenant-ın layihəsi üçün sorğu, sanki layihə mövcud deyilmiş kimi,
404 Not Foundqaytarır. - Həmin tenant-ın hər layihəsi. API tokeni onu yaratdığınız layihəyə bağlı deyil. O, tenant-da istifadəçisinin rolu olan hər layihədə işləyir.
- IP icazə siyahısı (IP allowlist). Tokendə IP allowlist təyin etsəniz, digər ünvanlardan gələn sorğular
401 Unauthorizedilə rədd edilir. - Müddətin bitməsi və ləğv. Müddəti bitmiş və ya ləğv edilmiş token
401 Unauthorizedilə rədd edilir. Platforma hər bearer sorğusunu tokenin cari vəziyyəti ilə yoxlayır, ona görə tokenin ləğvi onun növbəti sorğusunda qüvvəyə minir. - Ömür. Token yaradarkən müddəti 30, 60 və ya 90 gün, xüsusi tarix və ya müddətsiz təyin edirsiniz. Xüsusi tarix bu gündən ən çox 365 gün sonra (UTC) ola bilər. Daha gec tarix
422 Unprocessable Entityvətoken_lifetime_exceeds_maximumsəbəbi ilə rədd edilir. - Rotasiya. API tokenini rotasiya etdikdə əvvəlki sirr 24 saat ərzində işləməyə davam edir ki, onu müştəri proqramlarınızda əvəz edə biləsiniz. API tokenini rotasiya edin bölməsinə baxın.
- İdempotentlik açarları. API tokeni və ya xidmət hesabı açarı ilə resurs yaradan və
202 Acceptedcavabı verənPOSTsorğusu (məsələn, virtual maşının və ya diskin yaradılması)Idempotency-Keybaşlığını daşımalıdır. Başlıq olmadıqda sorğuIDEMPOTENCY_KEY_REQUIREDkodu ilə400 Bad Requestcavabı alaraq rədd edilir. Digər yazma sorğularında başlıq məcburi deyil, lakin başlıqsız təkrar cəhd dəyişikliyi yenidən tətbiq edə bilər. İdempotent sorğular səhifəsinə baxın. - Sorğu limitləri. Hər giriş məlumatının sorğu limiti var, hər tenant-ın da bütün giriş məlumatları üzrə birlikdə limiti var. Cavablar
X-RateLimit-Limit,X-RateLimit-Remainingvə limitin sıfırlanmasına qalan saniyələrin sayı olanX-RateLimit-Resetbaşlıqlarını daşıyır. Limiti aşan sorğuRATE_LIMITEDkodu vəRetry-Afterbaşlığı ilə429 Too Many Requestsalır. Sorğu limiti bölməsinə baxın.
Konsol seansı tələb edən əməliyyatlar
Bu əməliyyatlar son iki faktorlu təsdiqləmə ilə daxil olunmuş konsol seansı tələb edir:
- OpenStack giriş məlumatının (OpenStack credential) yaradılması.
- OpenStack giriş məlumatının rotasiyası.
- Təşkilatın OpenStack API girişinin aktivləşdirilməsi və ya qeyri-aktiv edilməsi.
API tokeni və ya xidmət hesabı açarı ilə onlar 403 Forbidden və INTERACTIVE_SESSION_REQUIRED kodu ilə rədd edilir. Əlavə təsdiqləmə bölməsinə baxın.
Nasazlığın həlli
FORBIDDEN kodlu 403 Forbidden cavabı sorğunun niyə rədd edildiyini bildirən details.reason daşıya bilər. API şlüzünün rəddində details olmur. Cədvəl hər iki halı sadalayır.
| Cavab | Səbəb | Həll |
|---|---|---|
401, UNAUTHENTICATED | Giriş məlumatı yanlışdır, müddəti bitib və ya ləğv edilib; sorğu tokenin IP icazə siyahısından kənar ünvandan gəlir; yaxud tokenin istifadəçisi qeyri-aktiv edilib. | Dəyəri və onun statusunu Identity & AccessAPI tokens bölməsində yoxlayın. Lazım olarsa, yeni token yaradın. |
403, səbəb TOKEN_SCOPE_MISSING | Tokendə və ya açarda əməliyyatın tələb etdiyi miqyas yoxdur. details.missingTokenScopes çatışmayan miqyasları sadalayır. | Həmin miqyaslarla token və ya açar yaradın. Xidmət hesabı açarı iam:write miqyasına malik ola bilməz: həmin əməliyyatlar üçün API tokenindən və ya konsoldan istifadə edin. |
403, səbəb TOKEN_FENCE_EXCEEDED | Token özündən uzunömürlü olacaq və ya IP icazə siyahısından kənara çıxacaq giriş məlumatı yaratmağa və ya yeniləməyə çalışdı. details.tokenFence məhdudiyyəti göstərir: expiry, ipAllowlist və ya identity. | Yeni giriş məlumatına daha erkən bitmə tarixi və tokenin öz siyahısının daxilində qalan IP icazə siyahısı verin və ya onu konsolda yaradın. |
403, details olmadan FORBIDDEN | Layihədəki rol əməliyyata icazə vermir. | Sahibdən buna icazə verən rol istəyin. |
403, səbəb ROLE_PERMISSION_MISSING | Rol bu konkret əməliyyata icazə vermir. details.requiredPermission və details.requiredLevel nəyin lazım olduğunu göstərir. | Sahibdən buna icazə verən rol istəyin. |
403, səbəb SUBSCRIPTION_ROLE_REQUIRED | Resurs abunəliyə aiddir, rol isə yalnız layihədə verilib. | Abunəlikdə rol istəyin. |
403, INTERACTIVE_SESSION_REQUIRED | Əməliyyat konsol seansı tələb edir və ya iam:write tələb edir, çağıran isə xidmət hesabı açarıdır. | Onu konsolda yerinə yetirin. iam:write tələb edən əməliyyat üçün həmin miqyaslı API tokenindən də istifadə edə bilərsiniz. |
404, NOT_FOUND | Layihə və ya resurs mövcud deyil, başqa tenant-a aiddir və ya giriş məlumatına görünmür. | Layihə ID-sini GET /account/whoami ilə yoxlayın. |
Bütün xəta kodları üçün Xətalar səhifəsinə baxın.