Kapsamlar
Bir anahtarın neyi yapmasına izin verildiği.
Sözlük
Kapalı bir küme, resource:action. Bir insana onay kutusu listesinde gösterilecek kadar küçük ve saklanan bir yetkinin bir yıl sonra da aynı anlama gelmesini sağlayacak kadar kararlı. Bir çalışma alanı ROLÜ de aynı sözlükle yazılır ve MCP araçlarına erişimi de aynı sözlük belirler; dolayısıyla salt okunur bir istemci gönderim araçlarını göremez bile. Tek alfabe, üç yüzey.
| Kapsam | Verdiği yetki |
|---|---|
| emails:send | E-posta gönderir |
| emails:read | Gönderilen mesajları ve teslim durumlarını okur |
| drafts:read | Taslakları okur |
| drafts:write | Taslak oluşturur ve düzenler |
| threads:read | Yazışmaları ve mesajları okur |
| threads:write | Yazışmaları etiketler, okundu olarak işaretler ve arşivler |
| labels:read | Etiketleri okur |
| labels:write | Etiket oluşturur ve düzenler |
| contacts:read | Kişileri okur |
| contacts:write | Kişi ekler, düzenler ve kaldırır |
| audiences:read | Kitleleri ve içlerinde kimlerin olduğunu okur |
| audiences:write | Kitle oluşturur ve düzenler, içlerinde kimlerin olduğunu değiştirir |
| calendar:read | Takvim etkinliklerini ve davetlerini okur |
| calendar:write | Takvim etkinlikleri oluşturur, değiştirir ve yanıtlar |
| templates:read | E-posta şablonlarını okur ve önizler |
| templates:write | E-posta şablonları oluşturur, düzenler ve onlarla gönderim yapar |
| domains:read | Alan adlarını ve DNS durumlarını okur |
| domains:write | Alan adlarını doğrular ve yapılandırır |
| webhooks:read | Webhook uç noktalarını ve teslimatlarını okur |
| webhooks:write | Webhook oluşturur, düzenler ve test eder |
| rules:read | Posta kurallarını okur ve test eder |
| rules:write | Posta kuralları oluşturur, düzenler ve yeniden sıralar |
| connections:read | Hangi posta kutularının bağlı olduğunu okur |
| members:read | Çalışma alanında kimlerin olduğunu ve neye sahip olduklarını görür |
| members:write | Kişi ekler ve çıkarır, nelere erişebileceklerini değiştirir |
| roles:read | Bu çalışma alanının tanımladığı rolleri okur |
| roles:write | Rol oluşturur, düzenler ve siler |
| settings:read | İmza dahil posta kutusu ayarlarını okur |
| settings:write | Posta kutusu ayarlarını ve imzayı değiştirir |
| keys:write | Kimse konsolu açmadan kendi gizli anahtarını yeniler |
Üzerinde düşünülmüş bir kapsam listesi olmadan oluşturulan bir anahtar emails:send alır, başka hiçbir şey almaz. Bir kimlik bilgisi için güvenli varsayılan, onu işe yarar kılan en dar ayardır.
Bir anahtar, arkasındaki rolle sınırlanır
Bir anahtar bir ROLE bağlı olarak verilebilir ve rol ikinci bir yetki değil, bir tavandır. Anahtarın gerçekte ne yapabileceği, kendi kapsamlarının o rolün izinleriyle KESİŞİMİDİR (key.scopes ∩ role.permissions); bu, herhangi bir uç noktaya ulaşılmadan önce, her istekte, sınırda bir kez hesaplanır. Sonraki katmanlardaki hiçbir şey rollerin varlığından haberdar değildir: rolün sahip olmadığı bir kapsam, kapsam kontrollerinin okuduğu listede basitçe yer almaz.
Yani iki liste birlikte okunur ve hiçbiri tek başına belirleyici değildir. emails:send taşıyan ama bu izne sahip olmayan bir rolün altındaki anahtar gönderim yapamaz; emails:send iznine sahip bir rol de bunu hiç istememiş bir anahtara hiçbir şey vermez. Bir kapsamı işaretlemek yetki istemektir ve istediğinizin ne kadarını alacağınıza rol karar verir.
ROLÜ OLMAYAN bir anahtarın tavanı yoktur ve bu nedenle verildiği çalışma alanı kadar geniştir. Roller var olmadan önce oluşturulmuş her anahtar bu durumdadır ve bir sahip alanı boş bıraktığında hâlâ bunu elde eder; dolayısıyla null bir rol, bir anahtarın olabileceği en DAR değil, en GENİŞ durumdur. Bir rolü silerken anahtarlarının nereye gideceğini belirtmenizin istenmesinin nedeni de budur: onları sahipsiz bırakmak her birini sessizce yükseltirdi.
Kesişim, anahtar verilirken üzerine işlenmek yerine istek başına çözümlenir. Bu, bir rolü daraltmayı canlı bir geri alma işlemine dönüştürür; anahtarın döndürülmesine gerek kalmadan çağıranın bir sonraki çağrısında yürürlüğe girer. Genişletmek de tam olarak aynı şekilde canlıdır; hatırlanmaya değer yarısı budur.
GET /ping ve GET /keys/self, özellikle tek bir hata durumu için scopes ile birlikte grantedScopes ve roleId bildirir. scopes etkin listedir ve herhangi bir şeye yetki veren tek listedir; grantedScopes ise anahtarın verildiği kapsamlardır. İkincide olup birincide olmayan her şeyi rol almıştır ve bu fark, "anahtarımda emails:send var ama insufficient_scope alıyorum" sorusunun tam yanıtıdır. Çözüm başka bir anahtar değil, bir rol değişikliğidir.
curl "$OE/ping" -H "$AUTH" { "ok": true, "keyId": "4c1b257a66287fd113bd89d0", "mode": "live", "scopes": ["emails:read", "threads:read"], "roleId": "role_c40a95f21cc65d31c2a89e07", "grantedScopes": ["emails:send", "emails:read", "threads:read"], "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}Beş izin bir anahtara asla ulaşamaz: api-keys:read, api-keys:write, billing:read, billing:write ve workspace:manage. Bunlar izindir ama kapsam değildir; dolayısıyla ne kadar cömert olursa olsun hiçbir rol onları bir token'a ekleyemez: başka bir anahtar üretmek, başka bir anahtarın ne yapabileceğini değiştirmek ya da planı değiştirmek yalnızca oturum açmış bir kişinin yapabileceği şeylerdir. Bir anahtarın kendisine yapabileceği tek şey, keys:write kapsamı altında kendi gizli anahtarını yenilemektir. GET /roles/permissions bu beşini scope: false olarak işaretler; tek bir bileşenin hem rol matrisini hem de anahtar oluşturma onay kutusu listesini çizebilmesini sağlayan da budur.
roles:write fiilen sözlüğün tamamıdır ve aksini iddia etmek daha tehlikeli bir dokümantasyon olurdu. Bu kapsamı taşıyan bir anahtar, kendisini sınırlayan rolü PATCH ile düzenleyip kendine diğer her şeyi verebilir ve tavan istek başına çözümlendiği için genişletilmiş tavan daha bir sonraki çağrıda geçerli olur. Bu kapatılacak bir açık değildir, çünkü rolleri düzenleyemeyen bir rol düzenleyicisi rol düzenleyicisi değildir. Bu, yalnızca üye listesini okuması gereken bir anahtara roles:write vermemek için bir nedendir.
Gönderim kapsamı
Kapsamlardan ayrı olarak, bir anahtar neyin adına gönderebileceği konusunda da daraltılabilir. İki liste taşır. domainAllowlist tüm alan adlarını tutar ve bir alan adına sahip anahtar, anahtardan sonra oluşturulanlar dahil o alan adındaki her adres adına gönderebilir. addressAllowlist tek tek adresleri tutar. İkisini de boş bırakırsanız anahtar çalışma alanı kadar geniş olur, asla daha geniş değil. GET /keys/self iki listeyi de gösterir ve GET /addresses belirli bir anahtarın gerçekte neyi kullanabileceğini bildirir; açıklanamayan bir from_address_forbidden hatasının yanıtı budur.
Aynı küme anahtarın neyi okuyabileceğini de daraltır. Gönderilen posta, izleme ve takvim yalnızca anahtarın adına gönderebildiği adresler için yanıt verir; dolayısıyla tek bir alan adıyla sınırlanmış bir anahtar başka bir alan adı adına ne gönderir ne de okur. Tüm bir alan adı ayrıca anahtarın o alan adının izleme host'unu ayarlamasına izin verir; tek adreslerle sınırlı bir anahtar bunu yapamaz.
Demek ki üç daraltma var ve bunlar birbirini geçersiz kılmaz, birlikte uygulanır: anahtardaki kapsamlar, üstündeki rolün izinleri ve bir From başlığına koyabileceği alan adları ile adresler. Bir gönderim üçünü de gerektirir ve bir ret yalnızca karşılaştığı ilkini adlandırır.