Questa pagina è stata tradotta dall'API Cloud Translation.

Panoramica dell'autenticazione API basata su IAM

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Apigee supporta l'autenticazione e l'autorizzazione basate su IAM per i proxy API. Per utilizzare questa funzionalità, includi i criteri VerifyIAM nel flusso di richieste del proxy e configura l'identificatore utente (di solito l'indirizzo email) del consumer API in modo che disponga del ruolo o delle autorizzazioni IAM Google Cloud necessari per richiamare le API Apigee. La richiesta API deve superare un token di accesso Google Cloud valido per l'utente.

Gli amministratori possono concedere l'autorizzazione a qualsiasi Google Cloud entità, non solo a singoli utenti.

Utilizzare controllo dell'accesso basato su IAM

Questa sezione descrive il processo end-to-end per la configurazione dell'autenticazione e dell'autorizzazione basate su IAM, come vengono valutate le richieste una volta configurato l'accesso e come revocare l'accesso per i consumer API che in precedenza avevano accesso.

Aggiungere la gestione degli accessi

Per configurare la gestione dell'accesso per un proxy API:

Aggiungi il criterio VerifyIAM al proxy o ai proxy API Apigee nell'ambito del flusso di richieste.
L'amministratore cloud per il progetto Apigee:
1. Concede il ruolo IAM deploymentInvoker (o un ruolo personalizzato con l'autorizzazione IAM apigee.deployments.invoke) all'entità Google Cloud del consumer API a livello di progetto. In questo modo, il consumer dell'API ha accesso all'invocazione di tutte le API ospitate nell'organizzazione Apigee associata.
  
  o
2. Utilizza l'azione SetIamPolicy per concedere il ruolo o l'autorizzazione al principal Google Cloud del consumer API in un determinato deployment o in più deployment in modo iterativo. Utilizza l'operazione di elenco sulla risorsa di deployment per visualizzare tutti i deployment all'interno di un ambiente, inclusi proxy API e flussi condivisi. Il nome del deployment è il nome del proxy API o del flusso condiviso.
  Nota:l'aggiunta del ruolo o dell'autorizzazione alle implementazioni di flussi condivisi non crea un controllo dei criteri VerifyIAM sui flussi condivisi; applica le autorizzazioni solo ai proxy. Per i proxy che chiamano flussi condivisi, le autorizzazioni devono essere applicate ai proxy. Con il concatenamento dei proxy, concedi l'autorizzazione sul proxy con il criterio; l'autorizzazione non è richiesta sugli altri proxy che fanno parte della catena.
Indirizza il consumer API a generare un token di accesso, che passerà all'interno della richiesta API Apigee per il controllo delle autorizzazioni. Il token generato deve avere l'ambito di autenticazione https://www.googleapis.com/auth/cloud-platform.

Operazioni amministrative

Questa sezione elenca le azioni intraprese dagli amministratori API (produttori di API) durante la gestione delle autorizzazioni basate su IAM.

La documentazione per le operazioni basate su API utilizzate per la gestione dell'accesso basato su IAM è disponibile nella documentazione di riferimento delle API organizations.environments e organizations.environments.deployments e include le operazioni SetIamPolicy, GetIamPolicy, TestIamPermissions e GetDeployment.

Questa tabella associa le operazioni alle autorizzazioni richieste:

Operazione amministrativa	Azione	Autorizzazione IAM necessaria	Risorsa IAM su cui è necessaria l'autorizzazione^*
GetDeployment	Recupera informazioni per un deployment in un ambiente Apigee	apigee.deployments.get	Progetto Google Cloud o ambiente Apigee
ListDeployments	Elenca i deployment in un ambiente Apigee	apigee.deployments.list	Progetto o ambiente Apigee
SetIamPolicy	Imposta l'accesso di chiamata per i consumer API in un determinato deployment API	apigee.deployments.setIamPolicy	Progetto Google Cloud o ambiente Apigee
GetIamPolicy	Recupera l'insieme di impostazioni di accesso all'invocazione per un deployment dell'API	apigee.deployments.getIamPolicy	Progetto Google Cloud o ambiente Apigee
TestIamPermissions	Controlla se l'utente che chiama questa API dispone dell'autorizzazione menzionata nel payload	Nessuna autorizzazione IAM necessaria	N/D

^* Il progetto Google Cloud è il progetto utilizzato per il provisioning di Apigee. Le autorizzazioni a livello di ambiente Apigee vengono impostate nell'ambiente utilizzando setIAMPolicy.

Controllo dell'accesso in runtime

Quando il consumer dell'API tenta di accedere a un'API con controllo dell'accesso dell'accesso basato su IAM, viene eseguito un controllo per verificare se dispone del token di accesso necessario e del ruolo o dell'autorizzazione appropriati a livello di progetto o deployment. In questo caso, l'utente può continuare ad accedere al proxy. In caso contrario, vengono bloccati.

Rimuovi accesso

Per rimuovere l'accesso a livello di progetto:per rimuovere l'accesso per un consumer API gestito a livello di progetto, l'amministratore Cloud per il progetto Apigee revoca il ruolo IAM deploymentInvoker (o il ruolo personalizzato con l'autorizzazione IAM apigee.deployments.invoke) dall'entità Google Cloud del consumer API per il progetto Google Cloud .

Se l'accesso è stato concesso per singoli deployment utilizzando setIamPolicy, rimuovi il ruolo o l'autorizzazione dai deployment utilizzando un'altra operazione setIamPolicy.

Caratteristiche e limitazioni del controllo dell'accesso basato su IAM

Tieni presente queste caratteristiche e limitazioni quando utilizzi l'autenticazione e l'autorizzazione basate su IAM:

In genere, l'esecuzione dei criteri con VerifyIAM richiede tra 10 e 50 millisecondi. Tuttavia, alcune chiamate potrebbero riscontrare latenze più elevate. Ad esempio, nella regione asia-east2 in particolare, la latenza media può aumentare fino a 50 ms e alcune chiamate potrebbero richiedere circa 100 ms per essere completate.
Tieni presente che queste cifre relative alla latenza non sono garantite.
L'inclusione del criterio VerifyIAM per un proxy è un controllo verificato/non verificato; i ruoli e le autorizzazioni specifici del consumer API non vengono presi in considerazione nei processi successivi del flusso di richiesta o risposta.
Poiché un controllo dell'autorizzazione viene eseguito solo al momento dell'esecuzione di VerifyIAM, VerifyIAM deve essere il primo criterio nel flusso di richieste, dopo solo i criteri di gestione del traffico.
Se la convalida dell'autorizzazione va a buon fine o se il produttore dell'API ha contrassegnato il criterio VerifyIAM per continuare in caso di errore, il flusso di richieste continua a eseguire gli altri criteri, se presenti, raggiungendo infine il server di destinazione. Se il controllo delle autorizzazioni non va a buon fine e il produttore dell'API non ha contrassegnato il criterio per continuare in caso di errore, l'utente riceve un errore.
L'aggiunta dell'accesso di chiamata (apigee.deployments.invoke) a livello di ambiente non trasferisce l'accesso di chiamata a tutti i deployment API all'interno dell'ambiente.
Le condizioni IAM non sono supportate nella risorsa di deployment e non possono essere utilizzate per controllare l'accesso all'invocazione. Per ulteriori informazioni, consulta la sezione Aggiunta di condizioni IAM di Apigee ai criteri.
Controllo dell'accesso basato su IAM supporta un massimo di 1500 associazioni di ruolo all'interno di un singolo criterio e altre limitazioni. Consulta Quote e limiti IAM.
Controllo dell'accesso basato su IAM è soggetto a ritardi di propagazione di IAM.
Il tentativo di gestire altre operazioni apigee.deployments, ad esempio apigee.deployments.delete tramite setIAMPolicy a livello di deployment, non sarà efficace, ma non restituirà nemmeno un errore. Solo apigee.deployements.invoke è effettivo.
L'accesso a un deployment viene eliminato quando il proxy corrispondente viene annullato il deployment dall'ambiente o eliminato; l'accesso deve essere aggiunto di nuovo al momento del redeployment.
L'autenticazione e l'autorizzazione basate su IAM non sono al momento disponibili in modalità ibrida.

Esempi

Questa sezione fornisce esempi di concessione e revoca dell'accesso basato su IAM alle API. Questi esempi presuppongono che VerifyIAM sia già stato aggiunto al proxy API appropriato.

In questi esempi, utilizza la console Cloud o gcloud (mostrato) per gestire ruoli o autorizzazioni sul principal Google Cloud del consumer API.

Concedere e revocare l'accesso utente per richiamare tutte le API in un'organizzazione Apigee

Per aggiungere l'accesso, aggiungi il ruolo deploymentInvoker:

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects add-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

Per revocare l'accesso, rimuovi il ruolo deploymentInvoker:

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects remove-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

Concedere e revocare l'accesso degli utenti a deployment specifici all'interno di un ambiente

Per aggiungere il ruolo di invoker per un singolo utente a un deployment specifico:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
          "user:'"$USER"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

Una risposta corretta dovrebbe essere simile alla seguente:

{
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user-email@example.com"
        ]
      }
    ]
  }

Per aggiungere il ruolo di invoker per più utenti a un deployment specifico:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER1=EMAIL_FOR_USER1
USER2=EMAIL_FOR_USER2
USER3=EMAIL_FOR_USER3
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER1"'",
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

Per eseguire una query sull'oggetto policy impostato in precedenza:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

Dovresti visualizzare una risposta di esito positivo come quella mostrata sopra.

L'utente può verificare se è in grado di accedere al deployment specificato (se l'autorizzazione apigee.deployments.invoke è impostata per l'utente in un deployment specificato), senza richiamare direttamente l'API di cui è stato eseguito il deployment. Per farlo, l'utente può inviare questa richiesta utilizzando un token di accesso che genera:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

La risposta deve includere l'autorizzazione apigee.deployments.invoke per l'utente.

Per revocare l'accesso a un deployment specifico per un singolo utente, rimuovi il ruolo deploymentInvoker per quell'utente. Per farlo, recupera prima l'oggetto criterio attualmente associato al deployment:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

La risposta di conferma dovrebbe essere simile alla seguente.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user1-email@example.com",
          "user:user2-email@example.com",
          "user:user3-email@example.com"
        ]
      }
    ]
  }

Per rimuovere l'associazione per un singolo utente, utilizza setIamPolicy e specifica nel payload gli utenti che devono continuare ad avere accesso, come faresti quando imposti l'accesso iniziale per questi utenti. Continuando con l'esempio mostrato sopra, se vuoi rimuovere l'accesso per USER1, ma mantenere l'accesso per USER2 e USER3, devi utilizzare questo comando:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

Per rimuovere l'associazione per tutti gli utenti di un deployment specifico, specifica un payload vuoto:

  curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{}'

Per verificare che l'associazione sia stata rimossa, assicurati che l'autorizzazione apigee.deployments.invoke non esista per l'utente nel deployment:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

Dovrebbe restituire una risposta appropriata, ad esempio un output vuoto se nessun utente dispone dell'autorizzazione per richiamare l'API.