Àmbits
Què pot fer una clau.
El vocabulari
Un conjunt tancat, resource:action. Prou petit per mostrar-lo a una persona en una llista de caselles, i prou estable perquè una concessió desada continuï volent dir el mateix un any després. Aquest mateix vocabulari és el que s'utilitza per escriure un ROL d'espai de treball i el que controla les eines MCP, de manera que un client de només lectura ni tan sols pot veure una eina d'enviament. Un alfabet, tres superfícies.
| Àmbit | Concedeix |
|---|---|
| emails:send | Enviar correu |
| emails:read | Llegir els missatges enviats i el seu estat de lliurament |
| drafts:read | Llegir els esborranys |
| drafts:write | Crear i editar esborranys |
| threads:read | Llegir fils i missatges |
| threads:write | Etiquetar, marcar com a llegits i arxivar fils |
| labels:read | Llegir les etiquetes |
| labels:write | Crear i editar etiquetes |
| contacts:read | Llegir els contactes |
| contacts:write | Afegir, editar i eliminar contactes |
| audiences:read | Llegir les audiències i qui hi ha |
| audiences:write | Crear i editar audiències, i canviar qui hi ha |
| calendar:read | Llegir els esdeveniments i les invitacions del calendari |
| calendar:write | Crear, modificar i respondre esdeveniments del calendari |
| templates:read | Llegir les plantilles de correu i previsualitzar-les |
| templates:write | Crear, editar i enviar amb plantilles de correu |
| domains:read | Llegir els dominis i el seu estat de DNS |
| domains:write | Verificar i configurar dominis |
| webhooks:read | Llegir els endpoints de webhook i els seus lliuraments |
| webhooks:write | Crear, editar i provar webhooks |
| rules:read | Llegir les regles de correu i provar-les |
| rules:write | Crear, editar i reordenar regles de correu |
| connections:read | Llegir quines bústies estan connectades |
| members:read | Veure qui hi ha a l'espai de treball i què té |
| members:write | Afegir i treure persones, i canviar a què poden accedir |
| roles:read | Llegir els rols que defineix aquest espai de treball |
| roles:write | Crear, editar i esborrar rols |
| settings:read | Llegir la configuració de la bústia, inclosa la signatura |
| settings:write | Canviar la configuració de la bústia i la signatura |
| keys:write | Substituir el seu propi secret sense que ningú hagi d'obrir la consola |
Una clau creada sense una llista d'àmbits meditada rep emails:send i res més. El valor per defecte segur per a una credencial és el més estret que la faci útil.
Una clau està limitada pel rol que hi ha al darrere
Una clau es pot emetre contra un ROL, i un rol és un sostre més que no pas una segona concessió. El que la clau pot fer realment són els seus propis àmbits INTERSECATS amb els permisos d'aquell rol (key.scopes ∩ role.permissions), calculats un sol cop a la frontera, a cada petició, abans d'arribar a cap endpoint. Res del que hi ha més avall no sap que existeixen els rols: un àmbit que el rol no té simplement no és a la llista que llegeixen les comprovacions d'àmbit.
Així doncs, les dues llistes es llegeixen juntes i cap no guanya per si sola. Una clau que porta emails:send sota un rol que no el té no pot enviar; un rol que té emails:send no dona res a una clau que mai no l'ha demanat. Marcar un àmbit és demanar autoritat, i el rol decideix quina part del que has demanat obtens.
Una clau SENSE rol no té sostre i, per tant, és tan àmplia com l'espai de treball contra el qual es va emetre. És el que porta cada clau creada abans que existissin els rols i el que encara obté un propietari si deixa el camp en blanc, de manera que un rol null és l'estat MÉS AMPLI en què pot estar una clau, no pas el més estret. També és per això que esborrar un rol t'obliga a dir on han d'anar les seves claus: deixar-les òrfenes les promocionaria totes en silenci.
La intersecció es resol a cada petició en comptes de quedar estampada a la clau en el moment d'emetre-la. Això fa que estrènyer un rol sigui una revocació en viu, vigent a la crida següent de qui truca i sense haver de rotar la clau, i que eixamplar-lo ho sigui exactament igual, que és la meitat que val la pena recordar.
GET /ping i GET /keys/self informen de scopes al costat de grantedScopes i roleId per una fallada en concret. scopes és la llista efectiva i l'única que autoritza res; grantedScopes és allò amb què es va emetre la clau. Tot el que és a la segona i falta a la primera ho ha tret el rol, i aquesta diferència és tota la resposta a «la meva clau té emails:send i rebo insufficient_scope». La solució és canviar el rol, no pas una altra clau.
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"}Hi ha cinc permisos que no poden arribar mai a una clau: api-keys:read, api-keys:write, billing:read, billing:write i workspace:manage. Són permisos però no àmbits, de manera que cap rol, per generós que sigui, no els pot posar en un token: encunyar una altra clau, canviar què pot fer una altra clau o moure el pla és cosa que només fa una persona amb la sessió iniciada. L'única cosa que una clau pot fer sobre si mateixa és substituir el seu propi secret, darrere de l'àmbit keys:write. GET /roles/permissions marca aquests cinc amb scope: false, que és el que permet que un sol component dibuixi tant la matriu de rols com la llista de caselles de creació de claus.
roles:write és, de fet, tot el vocabulari, i fer veure el contrari seria la documentació més perillosa. Una clau que el tingui pot fer un PATCH al mateix rol que la limita i atorgar-se tota la resta, i com que el sostre es resol a cada petició el més ampli s'aplica ja a la crida següent. No és un forat per tapar, perquè un editor de rols que no pot editar rols no és un editor de rols. És un motiu per no posar roles:write en una clau que només havia de llegir la llista de membres.
Abast d'enviament
A banda dels àmbits, una clau es pot estrènyer pel que fa a com pot enviar. Porta dues llistes. domainAllowlist conté dominis sencers, i una clau que té un domini pot enviar com qualsevol adreça d'aquest domini, incloses les adreces creades després de la clau. addressAllowlist conté adreces concretes. Deixa-les totes dues buides i la clau és tan àmplia com l'espai de treball, mai més. GET /keys/self mostra totes dues llistes i GET /addresses informa del que una clau determinada pot fer servir realment, que és la resposta a un from_address_forbidden inexplicable.
El mateix conjunt estreny el que la clau llegeix. El correu enviat, el seguiment i el calendari només responen per a les adreces amb què la clau pot enviar, de manera que una clau limitada a un domini ni envia ni llegeix en nom d'un altre. Un domini sencer també permet que la clau configuri l'amfitrió de seguiment d'aquell domini, cosa que una clau limitada a adreces concretes no pot fer.
Tres estretaments, doncs, que es componen en comptes de sobreescriure's: els àmbits de la clau, els permisos del rol que hi ha per sobre i els dominis i les adreces que pot posar en una capçalera From. Un enviament necessita tots tres, i un rebuig només anomena el primer amb què s'ha trobat.