Personalizzazione dei truststore per la verifica del certificato TLS

Scopri come aggiungere bundle CA e autorità di certificazione ai truststore personalizzati con API Gateway.

I gateway API creati con il servizio API Gateway verificano i certificati TLS presentati mediante un truststore. Il truststore può contenere certificati radice CA (Certificate Authority) e bundle CA di certificati radice e intermedi. Un bundle CA predefinito viene aggiunto al truststore di ogni gateway API, contenente certificati di CA pubbliche ben note. Il bundle CA predefinito consente al gateway API di verificare i certificati TLS presentati dai servizi backend.

Oltre al bundle CA predefinito, è possibile scegliere di aggiungere i certificati radice di altre CA e altri bundle CA al truststore di un gateway API. Questi bundle CA e CA aggiuntivi sono definiti CA personalizzati e bundle CA personalizzati. Per aggiungere un bundle CA o CA personalizzato al truststore di un gateway API, è innanzitutto necessario creare una risorsa CA o una risorsa bundle CA nel servizio Certificati. Dopo aver creato la risorsa nel servizio Certificati, è possibile aggiungerla al truststore del gateway API. L'aggiunta di bundle CA e CA personalizzati consente di personalizzare il truststore in base alle proprie esigenze.

Dopo aver aggiunto CA e bundle CA personalizzati al truststore, le connessioni TLS al gateway API (anche dal back-end HTTPS e dalla cache delle risposte) vengono verificate utilizzando sia il bundle CA predefinito che le CA e i bundle CA personalizzati. Inoltre, se è stato specificato il supporto mTLS per una distribuzione API, il gateway API utilizza CA personalizzate e bundle CA personalizzati per verificare i certificati client API. Tenere presente che il gateway API non utilizza il bundle CA predefinito per verificare i certificati client API durante un handshake mTLS. Pertanto, se desideri che un gateway API supporti mTLS, devi aggiungere CA e bundle CA personalizzati al truststore del gateway API

Per alcuni clienti, è obbligatorio per motivi di sicurezza utilizzare truststore personalizzati che contengono solo CA private e nessuna CA pubblica. Per altri clienti, l'uso di truststore personalizzati è probabilmente guidato da requisiti commerciali.

Aggiunta di CA e bundle CA personalizzati al truststore di un gateway API

Per personalizzare il truststore di un gateway API aggiungendo un bundle CA (Certificate Authority) o CA personalizzato, creare prima una risorsa CA (Certificate Authority) o una risorsa bundle CA nel servizio Certificati, quindi aggiungerla al truststore del gateway API.

Passo 1: creare una risorsa CA e/o una risorsa bundle CA nel servizio certificati

Seguire le istruzioni riportate nella documentazione del servizio Certificates per creare una risorsa CA (Certificate Authority) e/o una risorsa bundle CA.

Passo 2: aggiungere la risorsa CA o la risorsa bundle CA al truststore di un gateway API

Per aggiungere una risorsa CA (Certificate Authority) o una risorsa bundle CA al truststore di un gateway API durante la creazione o l'aggiornamento del gateway API, effettuare le operazioni riportate di seguito.

Seguire le istruzioni riportate in Creazione di un gateway API o Aggiornamento di un gateway API o di una distribuzione API per creare o aggiornare un gateway API utilizzando la console o l'interfaccia CLI.
Specificare la risorsa CA e/o la risorsa bundle CA dal servizio Certificati da aggiungere al truststore del gateway API, come descritto nelle istruzioni riportate di seguito.
- Se si utilizza la console: nella sezione Opzioni avanzate della finestra di dialogo Crea gateway o Modifica gateway, fare clic su Aggiungi autorità di certificazione e selezionare una o più risorse CA o bundle CA da aggiungere al truststore del gateway API come CA personalizzate e bundle CA personalizzati (oltre al bundle CA predefinito).
- Se si utilizza l'interfaccia CLI: impostare l'argomento --ca-bundles file:///<filename> sul nome di un file contenente i dettagli di una o più risorse CA o risorse bundle CA da aggiungere al truststore del gateway API come CA personalizzate e bundle CA personalizzati (oltre al bundle CA predefinito). Specificare i dettagli in formato JSON valido nel seguente formato:
```
[
  {
    "type": "CA_BUNDLE",
    "caBundleId": "ocid1.cabundle..."
  },
  {
    "type": "CERTIFICATE_AUTHORITY",
    "certificateAuthorityId": "ocid1.cabundle..."
  }
]
```
Il servizio API Gateway crea o aggiorna il gateway API con un truststore contenente il bundle CA e/o CA personalizzato specificato, oltre al bundle CA predefinito.

Rimozione di CA e bundle CA personalizzati dal truststore di un gateway API

Dopo aver aggiunto un bundle CA (Certificate Authority) o CA personalizzato al truststore di un gateway API, è possibile decidere che il bundle CA o CA non sia più necessario.

È possibile rimuovere alcune o tutte le CA e i bundle CA personalizzati dal truststore di un gateway API, a condizione che non vi siano API abilitate per mTLS distribuite nel gateway API. Se nel gateway API sono distribuite una o più API abilitate per mTLS, nel truststore del gateway API deve essere sempre presente almeno un bundle CA o CA personalizzato.

Uso della console

Per rimuovere un bundle CA o CA personalizzato dal truststore di un gateway API utilizzando la console:

Nella console aprire il menu di navigazione e fare clic su Servizi per sviluppatori. In Gestione API, fare clic su Gateway.
Scegliere un compartimento in cui si dispone dell'autorizzazione per lavorare.
Nella pagina Gateway fare clic sul nome del gateway API da cui si desidera rimuovere il bundle CA o CA personalizzato per visualizzare la pagina Dettagli gateway.
Nella pagina Dettagli gateway, selezionare Autorità di certificazione dalla lista Risorse per visualizzare i bundle CA e CA personalizzati nel truststore del gateway API.
Fare clic su il menu Azioni () accanto al bundle CA o CA personalizzato che si desidera rimuovere e selezionare Rimuovi.

Tenere presente che non è possibile rimuovere tutte le CA e i bundle CA personalizzati dal truststore di un gateway API se nel gateway API sono distribuite una o più API abilitate per mTLS.
Confermare che si desidera rimuovere il bundle CA o CA personalizzato dal truststore del gateway API.

Uso dell'interfaccia CLI

Per rimuovere un bundle CA o CA personalizzato dal truststore di un gateway API utilizzando l'interfaccia CLI, effettuare le operazioni riportate di seguito.

Configurare l'ambiente client per l'uso dell'interfaccia CLI (Configuring Your Client Environment to use the CLI for API Gateway Development).
Per rimuovere un bundle CA o CA personalizzato dal truststore di un gateway API, effettuare le operazioni riportate di seguito.
1. Aprire un prompt dei comandi ed eseguire oci api-gateway gateway update per rimuovere il bundle CA o CA personalizzato dal truststore del gateway API:
```
oci api-gateway gateway update --gateway-id <gateway-ocid> --ca-bundles file:///<filename>
```
  dove <filename> è il nome di un file contenente i dettagli solo delle CA personalizzate e dei bundle CA personalizzati da conservare nel truststore del gateway API (oltre al bundle CA predefinito). Tutti i bundle CA o CA non contenuti nel file vengono rimossi dal truststore.
  
  Ad esempio:
```
oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --ca-bundles file:///bundles-to-keep.json
```
  Tenere presente che non è possibile rimuovere tutte le CA e i bundle CA personalizzati dal truststore di un gateway API se nel gateway API sono distribuite una o più API abilitate per mTLS.
  
  La risposta al comando include quanto riportato di seguito.
  - Stato del ciclo di vita (ad esempio, DELETED, FAILED).
  - ID della richiesta di lavoro per rimuovere le CA personalizzate o i bundle CA (i dettagli delle richieste di lavoro sono disponibili per sette giorni dopo il completamento, l'annullamento o l'errore).
  Se si desidera che il comando attenda la restituzione del controllo finché le CA personalizzate o i bundle CA non sono stati rimossi (o la richiesta non è riuscita), includere uno o entrambi i parametri riportati di seguito.
  - --wait-for-state DELETED
  - --wait-for-state FAILED
  Ad esempio:
```
oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --ca-bundles file:///bundles-to-keep.json --wait-for-state DELETED
```
2. (Facoltativo) Per visualizzare lo stato della richiesta di lavoro che sta rimuovendo il bundle CA o CA personalizzato, immettere:
```
oci api-gateway work-request get --work-request-id <work-request-ocid>
```
3. (Facoltativo) Per visualizzare i log della richiesta di lavoro che sta rimuovendo il bundle CA o CA personalizzato, immettere:
```
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
```
4. (Facoltativo) Se la richiesta di lavoro che rimuove il bundle CA o CA personalizzato non riesce e si desidera esaminare i log degli errori, immettere:
```
oci api-gateway work-request-error --work-request-id <work-request-ocid>
```
5. (Facoltativo) Per verificare che il bundle CA o CA personalizzato sia stato rimosso dal truststore del gateway API, immettere il comando seguente e confermare che il bundle CA o CA personalizzato non è più visualizzato:
```
oci api-gateway gateway get --gateway-id <gateway-ocid>
```

Per ulteriori informazioni sull'uso dell'interfaccia CLI, vedere Command Line Interface (CLI, interfaccia a riga di comando). Per un elenco completo dei flag e delle opzioni disponibili per i comandi della CLI, vedere la Guida della CLI.

Utilizzo dell'API

Per informazioni sull'uso dell'API e delle richieste di firma, consulta la documentazione dell'API REST e le credenziali di sicurezza. Per informazioni sugli SDK, vedere SDK e l'interfaccia CLI.

Utilizzare l'operazione UpdateGateway per specificare solo le CA personalizzate e i bundle CA personalizzati da conservare nel truststore del gateway API (oltre al bundle CA predefinito). Tutti i bundle CA o CA non specificati vengono rimossi dal truststore. Tenere presente che non è possibile rimuovere tutte le CA e i bundle CA personalizzati dal truststore di un gateway API se nel gateway API sono distribuite una o più API abilitate per mTLS.