API Chiavi

Le chiavi API vengono utilizzate per autenticare le richieste al Capgo API. Le chiavi sono specifiche dell'organizzazione e possono essere assegnate ruoli RBAC per un controllo di accesso fine-granulare. Ogni chiave può anche avere una data di scadenza facoltativa e può essere creata come una 'chiave sicura' (hashata) dove il valore in chiaro viene mostrato solo una volta.

Utilizza una chiave API

Passa la tua chiave API nella x-api-key testa di ogni richiesta:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/...

La authorization testa è accettata anche, ma è principalmente destinata ai token JWT. Quando il valore è una chiave API formattata come UUID funziona, ma x-api-key è la testa raccomandata per tutti i tipi di chiavi (compresi le chiavi sicure/hasheade).

Permessi RBAC

Le chiavi API utilizzano lo stesso sistema di controllo degli accessi basato sui ruoli (RBAC) delle account utente. Quando si crea o si gestisce le chiavi tramite l'app web, si assegna un ruolo a due livelli:

• Ruolo dell'organizzazione — Definisce le autorizzazioni di base della chiave per l'intera organizzazione (ad esempio org_admin, org_member).
• Ruoli dell'app — Autorizzazioni opzionali per l'app (ad esempio app_admin, app_developer, app_uploader, app_reader).

Se una chiave API ha vincoli di ruolo espliciti, solo quei vincoli vengono valutati per le verifiche di autorizzazione. Le autorizzazioni personali del proprietario della chiave non sono ereditate dalla chiave.

Nota

Le chiavi senza vincoli di ruolo ricadono in un sistema basato su modalità (read, upload, write, all). Queste modalità sono obsolete — utilizza i ruoli RBAC al posto loro.

Creazione di permessi di organizzazione

La creazione di organizzazioni con una chiave API ora utilizza un permesso globale esplicito: org.create.

Questo permesso è separato dalle normali associazioni di ruolo per organizzazione/app perché una nuova organizzazione non esiste ancora quando POST /organization/ è chiamato. Per creare organizzazioni con una chiave API:

• La chiave API deve includere org.create in global_permissions.
• La stessa chiave API deve anche avere un'associazione di ruolo attuale per organizzazione-scopata org_admin o org_super_admin l'associazione di ruolo.
• Le nuove chiavi API non ricevono org.create di default. Abilita Consenti la creazione di organizzazioni quando si crea o si modifica una chiave RBAC API nel pannello di controllo.
• Existing write-capable org admin/super admin API keys were backfilled with org.create così che le integrazioni esistenti possano continuare a creare organizzazioni.

Quando una chiave API crea un'organizzazione, Capgo assegna automaticamente quella stessa chiave API org_super_admin nel nuovo organismo creato. Ciò consente all'integrazione di gestire l'organizzazione appena creata senza dover richiedere un ruolo di binding manuale separato.

Se si crea una chiave API attraverso il API, includere global_permissions insieme alla binding di amministratore di organizzazione:

{
  "name": "Provisioning key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "org_admin",
      "scope_type": "org",
      "org_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "global_permissions": ["org.create"]
}

org.create si applica solo alla creazione di organizzazioni. La cancellazione di un'organizzazione richiede comunque la possibilità di cancellare l'organizzazione di destinazione, tipicamente attraverso org_super_admin.

Chiavi sicure (hashate)

When creando una chiave sicura, il server genera il materiale di chiave e restituisce il valore in chiaro una volta sola. Solo una hash viene memorizzata. Ciò significa:

• La chiave in chiaro non può essere recuperata dopo la creazione.
• La regenerazione produce una nuova chiave in chiaro (mostrata una volta) e aggiorna la hash memorizzata.
• Le chiavi hashate sono raccomandate per l'uso di produzione.

Alcune organizzazioni impongono le chiavi hashate tramite la enforce_hashed_api_keys politica dell'org.

Scadenza

Le chiavi possono avere una data di scadenza facoltativa. Le chiavi scadute vengono rifiutate al livello di controllo delle autorizzazioni.

Le politiche delle organizzazioni possono imporre:

• Scadenza obbligatoria (require_apikey_expiration) — Tutti i nuovi chiavi devono avere una scadenza.
• Tempo di vita massimo (max_apikey_expiration_days) — La scadenza non può essere più lontana di N giorni da ora.

Pratiche di Sicurezza

1. Principio di Minima Autorità: Assegna il ruolo più restrittivo che ancora consente alla tua integrazione di funzionare
2. Rotazione Regolare: Rota le tue API chiavi periodicamente utilizzando la funzione di regenerazione
3. Memorizzazione Sicura: Memorizza le API chiavi in modo sicuro e non le commettere mai al controllo delle versioni
4. Usa chiavi hashate: Crea chiavi sicure (hashate) per integrazioni di produzione
5. Stabilisci Scadenza: Imposta sempre una data di scadenza sulle chiavi utilizzate per l'accesso temporaneo o CI/CD
6. Restrizioni di Scopo: Limita le chiavi a specifiche app con il ruolo minimo richiesto

Uso Comune

1. Integrazione CI/CD: Crea chiavi scolate a specifiche app con il app_uploader o app_developer ruolo e imposta una data di scadenza
2. Automazione di Deploy: Utilizza le chiavi con il app_developer ruolo per i script di deploy automatizzati
3. Strumenti di Monitoraggio: Crea le chiavi con il app_reader ruolo per le integrazioni di monitoraggio esterne
4. Accesso Amministrativo: Utilizza le chiavi con il org_admin ruolo con parsimonia per gli strumenti amministrativi
5. Integrazioni di Terze Parti: Crea le chiavi limitate a specifiche app con il ruolo richiesto minimo
6. Provisionamento dell'Organizzazione: Utilizza un org_admin o org_super_admin chiave RBAC con org.create solamente per l'automazione affidabile che ha bisogno di creare organizzazioni

Continua da API Chiavi

Se stai utilizzando API Chiavi per pianificare l'autenticazione e le flussi di account, connettilo con @capgo/capacitor-login-social per i dettagli di implementazione in @capgo/capacitor-login-social, @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric per i dettagli di implementazione in @capgo/capacitor-native-biometric, Autenticazione a due fattori per i dettagli di implementazione in Autenticazione a due fattori, e SSO (azienda) per i dettagli di implementazione in SSO (azienda).