API belirteçleriyle kimlik doğrulama
Her REST API isteğiyle bir API belirteci veya servis hesabı anahtarı gönderin; kimlik bilgilerinin nelere eriştiğini ve isteklerin neden reddedildiğini öğrenin.
Her REST API isteği, Authorization başlığında bir kimlik bilgisi taşır. Bu makalede kimlik bilgisinin nasıl gönderileceği, her kimlik bilgisi türünün nelere erişebildiği ve bir istek reddedildiğinde ne yapılacağı açıklanır.
Başlamadan önce
- Bir kimlik bilgisi edinin. Kimlik & ErişimAPI belirteçleri sayfasında bir API belirteci ya da Kimlik & ErişimServis Hesapları sayfasında bir servis hesabı için anahtar oluşturun. Bkz. API belirteci oluşturma ve Anahtarları yönetme.
- API belirteci oluşturmak için Sahip rolüne ya da API belirteçlerini yönetebilen özel bir role ihtiyacınız vardır. Katkıda bulunan ve Okuyucu rolleri belirteçleri yalnızca görüntüleyebilir.
- Gizli anahtarı gösterildiği anda saklayın. Gizli anahtar yalnızca bir kez gösterilir.
Kimlik bilgisi seçme
| Kimlik bilgisi | Başlangıcı | Kimin adına işlem yapar | Neler yapabilir |
|---|---|---|---|
| API belirteci | pc_live_ | Onu oluşturan kullanıcı | O kullanıcının rolünün her projede izin verdikleri; yalnızca belirtecin kapsamları dahilinde |
| Servis hesabı anahtarı | sak_live_ | Servis hesabı | Servis hesabına verilen rollerin izin verdikleri; yalnızca anahtarın kapsamları içinde |
Kişiler ayrıldığında veya rolleri değiştiğinde çalışmaya devam etmesi gereken otomasyonlar için servis hesabı anahtarı kullanın. Bir kullanıcının API belirteçleri, kullanıcı kaldırıldığında iptal edilir ve kullanıcının hesabı devre dışıyken çalışmaz.
Bu kimlik bilgilerinin hiçbiri openstack CLI veya Terraform gibi OpenStack araçlarıyla çalışmaz. Bu araçlar bir OpenStack uygulama kimlik bilgisi kullanır. Bkz. OpenStack uyumlu araçlar.
Kimlik bilgisini gönderme
Kimlik bilgisini her isteğin Authorization başlığına, Bearer sözcüğünden sonra koyun. Çalıştığını denetlemek için kendi kimliğinizi okuyun:
curl "https://<api-host>/api/v1/account/whoami" \
-H "Authorization: Bearer $PC_TOKEN"<api-host>: API’nin ana bilgisayar adı.PC_TOKEN: API belirtecini veya servis hesabı anahtarını tutan bir ortam değişkeni.
200 OK yanıtı, kimlik bilgisinin erişebildiği kuruluşları, abonelikleri ve projeleri listeler. 401 Unauthorized yanıtı, kimlik bilgisinin geçerli olmadığı anlamına gelir. Bkz. Sorun giderme.
Kimlik bilgilerini kaynak kodun ve sürüm kontrolünün dışında tutun. Örnekteki gibi bir gizli anahtar deposundan veya bir ortam değişkeninden yükleyin.
Belirteç kapsamları
Bir API belirteci iki şeyle sınırlıdır: onu oluşturan kullanıcının rolü ve belirteç için seçtiğiniz kapsamlar. Bir istek yalnızca ikisi de izin verdiğinde geçer. Örneğin compute:write kapsamına sahip bir belirteç, kullanıcısının projede Okuyucu rolü varsa sanal makine oluşturamaz. Bir write kapsamı, eşleşen read kapsamını içermez: belirteç bir kaynağı hem değiştirecek hem okuyacaksa ikisini de seçin.
Katalogda 17 kapsam vardır: sekiz alanın her biri için bir read ve bir write kapsamı ile audit:read.
| Kapsam | İzin verdikleri |
|---|---|
compute:read | Sanal makineleri, boyutları, anahtar çiftlerini, imajları, sanal makine anlık görüntülerini ve sanal makine metriklerini okuma. |
compute:write | Bu kaynakları oluşturma, değiştirme ve silme; başlatma ve durdurma gibi sanal makine eylemleri. |
storage:read | Diskleri, disk anlık görüntülerini, disk aktarımlarını, yedekleme planlarını, dosya paylaşımlarını ve kovaları okuma. |
storage:write | Bu kaynakları oluşturma, değiştirme ve silme. |
network:read | Ağları, alt ağları, yönlendiricileri, ağ arabirimlerini, genel IP’leri, güvenlik gruplarını ve Site-to-Site VPN kaynaklarını okuma. |
network:write | Bu kaynakları oluşturma, değiştirme ve silme. |
loadbalancer:read | Yük dengeleyicileri ve kullandıkları sertifikaları okuma. |
loadbalancer:write | Bu kaynakları oluşturma, değiştirme ve silme. |
kubernetes:read | Kubernetes kaynaklarını okuma; işlemlerini ve olaylarını izleme. |
kubernetes:write | Bu kaynakları oluşturma, değiştirme ve silme. |
observability:read | Uyarı kurallarını, bildirim kanallarını ve sağlık olaylarını okuma. |
observability:write | Uyarı kurallarını ve bildirim kanallarını oluşturma, değiştirme ve silme. |
billing:read | Maliyet verilerini, bütçeleri, taahhütleri, faturaları, kredileri, ödeme yöntemlerini ve kotaları okuma. |
billing:write | Faturalandırma ve maliyet verilerini değiştirme; örneğin bütçe oluşturma, kupon kullanma veya kota artışı isteme. |
iam:read | Kullanıcıları, rolleri, servis hesaplarını, API belirteçlerini ve Activity Log içindeki etkinlik kayıtlarını okuma. |
iam:write | Kimlik ve erişim değişiklikleri: kullanıcı davet etme, rol verme, servis hesaplarını ve API belirteçlerini yönetme, oturum açma politikasını ve çoklu oturum açmayı değiştirme. |
audit:read | Activity Log içindeki etkinlik kayıtlarını okuma. |
Activity Log, iam:read veya audit:read kapsamını kabul eder: belirtecin yalnızca birine sahip olması yeter.
Bir aboneliği veya projeyi silmek için iam:write kapsamı ve her kaynak alanının yazma kapsamı gerekir: compute:write, storage:write, network:write, loadbalancer:write, kubernetes:write ve observability:write.
Abonelik oluşturmak için iam:write ve billing:write kapsamları gerekir, çünkü abonelik bir faturalandırma hesabıdır.
Konsolda kapsamları bir API belirteci veya servis hesabı anahtarı oluştururken seçersiniz. API’de belirteç oluştururken bunları scopes alanında gönderirsiniz.
API belirtecinin çağıramadıkları
Bir belirteç, kapsamına sahip olduğu API’nin her alanını çağırabilir; Identity & Access Management ve faturalandırmadaki değişiklikler de buna dahildir. Her belirteç için şu sınırlar geçerlidir:
- Yalnızca konsol işlemleri. Bazı işlemler hiçbir zaman belirteç kabul etmez. Bkz. Konsol oturumu gerektiren işlemler.
- Belirtecin üstünde kimlik bilgisi yok. Bir belirteç, başka bir belirteci veya servis hesabı anahtarını yalnızca kendisinde bulunan kapsamlarla oluşturabilir. Kendisinde olmayan bir kapsam
403 ForbiddenveTOKEN_SCOPE_MISSINGnedeniyle reddedilir. - Belirtecten uzun yaşayan kimlik bilgisi yok. Süresi dolacak bir belirteç, daha geç sona erecek veya hiç sona ermeyecek bir belirteç oluşturamaz ya da yenileyemez. Böyle bir belirtecin oluşturduğu servis hesabı anahtarı belirteçten geç sona ermez. Ret yanıtı
403 ForbiddenveTOKEN_FENCE_EXCEEDEDnedenidir. - Belirtecin IP izin listesinin dışında kimlik bilgisi yok. IP izin listesi olan bir belirteç, yalnızca boş olmayan izin listesi kendi listesinin içinde kalan belirteçleri oluşturabilir veya yenileyebilir. Anahtarın izin listesi olmadığından servis hesabı anahtarı oluşturamaz. Ret yanıtı
403 ForbiddenveTOKEN_FENCE_EXCEEDEDnedenidir.
Servis hesabı anahtarı kapsamları
Servis hesabı anahtarının da kapsamları vardır; servis hesabının rollerine ek olarak API belirteciyle aynı kapsam denetiminden geçer. Anahtar oluştururken kapsamlarını iam:write olmayan katalogdan seçersiniz. Kapsam belirtmeden oluşturulan anahtar, iam:write dışındaki her kapsamı alır. iam:write isteyen bir istek 422 Unprocessable Entity ile reddedilir.
Anahtar, kapsamları ne olursa olsun iam:write gerektiren her işlemde 403 Forbidden ve INTERACTIVE_SESSION_REQUIRED koduyla reddedilir. Örnekler: kullanıcı davet etme, rol verme ve belirteç ya da anahtar oluşturma. Bu değişiklikleri konsolda veya iam:write kapsamlı bir API belirteciyle yapın.
Kimlik bilgisinin geçerli olduğu yerler
- Tek bir kuruluş. Kimlik bilgisi yalnızca oluşturulduğu kuruluşta çalışır. Başka bir kuruluşun projesine yönelik istek, proje yokmuş gibi
404 Not Founddöndürür. - O kuruluşun her projesi. API belirteci, oluşturduğunuz projeye bağlı değildir. Kuruluşta kullanıcısının rolü olan her projede çalışır.
- IP izin listesi. Bir belirteçte IP izin listesi ayarlarsanız diğer adreslerden gelen istekler
401 Unauthorizedile reddedilir. - Sona erme ve iptal. Süresi dolmuş veya iptal edilmiş bir belirteç
401 Unauthorizedile reddedilir. Platform, belirteçle gelen her isteği belirtecin güncel durumuna göre denetler; bu nedenle bir belirteci iptal etmek, belirtecin bir sonraki isteğinde etkili olur. - Ömür. Belirteç oluştururken sona erme süresini 30, 60 veya 90 gün, özel bir tarih ya da süresiz olarak belirlersiniz. Özel tarih en fazla bugünden 365 gün sonrası (UTC) olabilir. Daha geç bir tarih
422 Unprocessable Entityvetoken_lifetime_exceeds_maximumnedeniyle reddedilir. - Yenileme. Bir API belirtecini yenilediğinizde önceki gizli anahtar 24 saat boyunca çalışmaya devam eder; böylece onu istemcilerinizde değiştirebilirsiniz. Bkz. API belirtecini yenileme.
- Idempotency anahtarları. Bir API belirteci veya servis hesabı anahtarıyla, kaynak oluşturan ve
202 Acceptedyanıtı veren birPOSTisteği (örneğin sanal makine veya disk oluşturma)Idempotency-Keybaşlığını taşımalıdır. Başlık yoksa istekIDEMPOTENCY_KEY_REQUIREDkoduyla400 Bad Requestyanıtıyla reddedilir. Diğer yazma isteklerinde başlık isteğe bağlıdır; ancak başlık olmadan yapılan bir yeniden deneme değişikliği yeniden uygulayabilir. Bkz. Idempotent istekler. - Hız limitleri. Her kimlik bilgisinin bir hız limiti vardır; her kuruluşun da tüm kimlik bilgileri için toplu bir limiti vardır. Yanıtlar
X-RateLimit-Limit,X-RateLimit-Remainingve limitin sıfırlanmasına kalan saniye sayısı olanX-RateLimit-Resetbaşlıklarını taşır. Limiti aşan bir istek,RATE_LIMITEDkodu ve birRetry-Afterbaşlığıyla429 Too Many Requestsalır. Bkz. Hız sınırlama.
Konsol oturumu gerektiren işlemler
Şu işlemler, yakın zamanda iki adımlı doğrulama yapılmış ve giriş yapılmış bir konsol oturumu gerektirir:
- OpenStack kimlik bilgisi oluşturma.
- OpenStack kimlik bilgisini yenileme.
- Kuruluşun OpenStack API erişimini açma veya kapatma.
API belirteci veya servis hesabı anahtarıyla bu işlemler 403 Forbidden ve INTERACTIVE_SESSION_REQUIRED koduyla reddedilir. Bkz. Ek doğrulama (step-up).
Sorun giderme
FORBIDDEN kodlu bir 403 Forbidden yanıtı, isteğin neden reddedildiğini belirten details.reason alanını taşıyabilir. API ağ geçidinin verdiği bir ret yanıtında details yoktur. Tablo iki durumu da listeler.
| Yanıt | Neden | Çözüm |
|---|---|---|
401, UNAUTHENTICATED | Kimlik bilgisi yanlış, süresi dolmuş veya iptal edilmiş; istek belirtecin IP izin listesi dışındaki bir adresten geliyor ya da belirtecin kullanıcısı devre dışı. | Değeri ve durumunu Kimlik & ErişimAPI belirteçleri sayfasında kontrol edin. Gerekirse yeni bir belirteç oluşturun. |
403, neden TOKEN_SCOPE_MISSING | Belirteçte veya anahtarda işlemin gerektirdiği bir kapsam eksik. details.missingTokenScopes eksik kapsamları listeler. | Bu kapsamlara sahip bir belirteç ya da anahtar oluşturun. Servis hesabı anahtarı iam:write kapsamına sahip olamaz: bu işlemler için bir API belirteci veya konsolu kullanın. |
403, neden TOKEN_FENCE_EXCEEDED | Bir belirteç, kendisinden uzun yaşayacak veya IP izin listesinin ötesine geçecek bir kimlik bilgisi oluşturmaya ya da yenilemeye çalıştı. details.tokenFence sınırı belirtir: expiry, ipAllowlist veya identity. | Yeni kimlik bilgisine daha erken bir sona erme tarihi ve belirtecin kendi listesinin içinde kalan bir IP izin listesi verin ya da onu konsolda oluşturun. |
403, details olmadan FORBIDDEN | Projedeki rol işleme izin vermiyor. | Bir sahipten bu izni veren bir rol isteyin. |
403, neden ROLE_PERMISSION_MISSING | Rol bu belirli işleme izin vermiyor. details.requiredPermission ve details.requiredLevel gerekeni belirtir. | Bir sahipten bu izni veren bir rol isteyin. |
403, neden SUBSCRIPTION_ROLE_REQUIRED | Kaynak aboneliğe ait ve rol yalnızca bir projede verilmiş. | Abonelik üzerinde bir rol isteyin. |
403, INTERACTIVE_SESSION_REQUIRED | İşlem bir konsol oturumu gerektiriyor ya da iam:write gerektiriyor ve çağıran bir servis hesabı anahtarı. | İşlemi konsolda yapın. iam:write gerektiren bir işlem için bu kapsama sahip bir API belirteci de kullanabilirsiniz. |
404, NOT_FOUND | Proje veya kaynak yok, başka bir kuruluşa ait ya da kimlik bilgisi tarafından görülemiyor. | Proje ID’sini GET /account/whoami ile kontrol edin. |
Tüm hata kodları için bkz. Hatalar.