Ativar mTLS do sul para proxies configuráveis

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Neste tópico, descrevemos como ativar o TLS mútuo sul (mTLS, na sigla em inglês) para proteger o tráfego do proxy de API configurável da Apigee para destinos e back-ends de proxy compatíveis com mTLS. O mútuo TLS (mTLS) permite a autenticação de endpoints de cliente e servidor em um handshake de TLS, permitindo que os usuários garantam que o cliente e o servidor são entidades confiáveis. Muitas empresas respondem a mTLS para garantir que todo o tráfego dentro de uma rede seja confiável e seguro. Ao adicionar a funcionalidade mTLS a proxies configuráveis, os clientes da Apigee manterão facilmente o uso atual de mTLS ao fazer a transição para o uso de proxies configuráveis ou aumentar a segurança das comunicações entre os proxies configuráveis e os back-ends.

Veja nas seções a seguir as etapas necessárias para configurar o suporte a mTLS para tráfego do sul (gateway -> back-end) para proxies configuráveis da Apigee.

O ^{PRÉ-LANÇAMENTO} de proxies de API configuráveis está disponível apenas para clientes com organizações de assinatura paga da Apigee. Os clientes da Apigee com organizações de pagamento por utilização podem criar proxies de API programáveis.

Visão geral dos conceitos do mTLS

O diagrama a seguir mostra como o handshake mTLS funciona entre um cliente e um servidor. Neste caso, um proxy configurável e um back-end de destino:

diagrama-mtls

No diagrama acima, o servidor e o cliente têm um keystore que contém o próprio certificado/chave pública e chave privada, indicando a possibilidade de um handshake "mútuo" TLS. Durante a verificação, o cliente do proxy configurável compara o certificado no truststore com o certificado enviado pelo back-end do servidor de destino.

Ao executar o handshake de TLS:

O servidor TLS apresenta o certificado ao cliente TLS para que ele faça a própria autenticação.
O cliente verifica a identidade do servidor e apresenta o próprio certificado para se autenticar no servidor.
Depois da autenticação mutuamente, o cliente e o servidor calculam uma chave de senha secreta usada para criptografar solicitações e respostas entre elas.

Implantar um proxy configurável compatível com mTLS

A seção a seguir descreve as etapas necessárias para implantar um proxy configurável com mTLS ativado para o tráfego entre o gateway e o servidor de back-end de destino.

Etapa 1: configurar os arquivos de origem

Antes de implantar um proxy configurável compatível com mTLS, você precisa configurar alguns novos arquivos, incluindo os seguintes:

Um truststore (um alias somente de certificado), uma chave e um alias de certificado usados pelo gateway de proxy configurável para se comunicar com o servidor de back-end de destino.
Um keystore da Apigee que contém o truststore, a chave e o certificado descritos acima.
Uma implantação de arquivo contendo os detalhes dos keystores no armazenamento de destino.

Para criar os arquivos de origem necessários:

Crie as chaves privada e pública da autoridade de certificação (CA) privada usando o seguinte comando:

openssl req \
  -new \
  -x509 \
  -nodes \
  -days 365 \
  -subj '/CN=my-ca' \
  -keyout RootCA.key \
  -out RootCA.pem

Crie o certificado de gateway de proxy configurável, a chave privada e a solicitação de assinatura de certificado (CSR, na sigla em inglês) usando os seguintes comandos:
```
openssl genrsa -out my_gateway.key 2048
openssl req -new -key my_gateway.key -out my_gateway.csr
```

Assine o certificado do cliente recém-criado usando a autoridade de certificação que você criou anteriormente:

openssl x509 -req -in my_gateway.csr -CA RootCA.pem \
  -CAkey RootCA.key -set_serial 01 -out my_gateway.pem -days 365 -sha256

Crie um certificado do servidor, uma chave privada e uma solicitação de assinatura de certificado (CSR, na sigla em inglês) usando os comandos a seguir:
```
openssl genrsa -out my_server.key 2048
openssl req -new -key my_server.key -subj '/CN=${SERVER_HOST}' -out my_server.csr
```

Assine o certificado de servidor recém-criado usando a autoridade de certificação que você criou anteriormente:

openssl x509 -req -in my_server.csr -CA RootCA.pem \
  -CAkey RootCA.key -set_serial 01 -out my_server.pem -days 365 -sha256

Após a conclusão, você terá oito arquivos novos no diretório, como mostrado no exemplo abaixo:

ls \
  RootCA.key
  RootCA.pem // Certificate used for the Apigee truststore
  my_gateway.csr
  my_gateway.key  // Used for the Apigee key
  my_gateway.pem // Used for the client cert alias
  my_server.csr
  my_server.key // Used for the server key
  my_server.pem // Used for the server cert

Etapa 2: configurar o keystore

Crie e configure um keystore da Apigee usando as seguintes etapas:

Abra a IU da Apigee em um navegador.
Selecione Admin > Environments > TLS Keystores.
Clique no botão + Keystore para criar um novo keystore.
Digite um nome na caixa de diálogo New Keystore, como mostrado na figura abaixo:
Clique em Add Keystore.
Na página de destino Keystores TLS, selecione a linha do keystore que você acabou de criar e clique em + para criar um novo alias.
Na tela Criar novo alias:
- Digite o Nome do alias.
- Selecione Certificate and Key no menu suspenso Tipo do painel Detalhes do certificado.
- Use o seletor de arquivos para escolher o arquivo de certificado do keystore criado em uma etapa anterior.
- Digite a senha do Key.
- Use o seletor de arquivos para escolher o arquivo de chaves criado em uma etapa anterior.
Quando os campos estiverem preenchidos, como mostrado na imagem abaixo, clique em Salvar para salvar os detalhes de alias e certificado.
Na página de destino Keystores TLS, selecione a linha do keystore que você acabou de criar e clique em + para criar um novo alias para o truststore.
Na tela Criar novo alias:
- Digite o Nome do alias.
- Selecione Apenas certificado na lista suspensa Tipo do painel Detalhes do certificado.
- Use o seletor de arquivos para escolher o Arquivo de certificado do Truststore criado em uma etapa anterior.
- Quando os campos estiverem preenchidos, conforme mostrado na imagem abaixo, clique em Salvar para salvar os detalhes de alias e certificado.

Agora você tem um keystore e um truststore na Apigee que contém os detalhes do TLS necessários ao implantar o arquivo de proxy configurável com mTLS.

Etapa 3: formatar o arquivo

Agora que você tem um keystore com os certificados e a chave, é possível criar o arquivo usado para implantar o proxy configurável com o mTLS.

A estrutura do arquivo ficará assim:

src/
|  main/apigee
|  |  apiproxies/helloworld
|  |  |  config.yaml
|  |  environments/dev
|  |  |  deployments.json
|  |  |  targetservers.json
…

O arquivo targetservers.json é usado para armazenar as referências ao keystore configurado na etapa anterior. O arquivo precisa conter referências à referência ao keystore, alias e truststore criados na etapa 2. Exemplo:

#targetservers.json
[
    {
        "name": "mymtlstarget",
        "description": "An example use mTLS",
        "host": "foo",
        "port": 8080,
        "isEnabled": true,
        "sSLInfo": {
                "enabled": true,
                "clientAuthEnabled": true,
                "keyStore": "mtls_keystore",
                "keyAlias": "mtls_alias",
                "trustStore": "mtls_truststore",
                "ignoreValidationErrors": false,
                "protocols": [
                "1.2"
                ],
                }
        },
        "protocol": "HTTP"
    },
    …
]

Os únicos campos que são obrigatórios na seção SSLInfo do arquivo targetservers.json ao ativar o mTLS são os seguintes:

ativado
clientAuthEnabled
keyStore
keyAlias
trustStore

Os campos opcionais são:

protocolos
criptografia

Agora você pode fazer referência a esse servidor de destino no seu proxy de arquivamento. Por exemplo, apiproxies/helloworld/config.yaml pode conter uma operação como a seguinte:

...
operations:
  - id: mTLSOperation
   target:
      target_server_id: "mymtlstarget"
    http_match:
      - path_template: "/foo"
        method: GET
...

Etapa 4: implantar o proxy

Quando a configuração do arquivo estiver concluída, implante o proxy configurável usando o seguinte comando:

$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE

Em que:

ENV_NAME é o ambiente da Apigee em que o proxy deve ser implantado.
ORG_NAME é o nome da organização da Apigee;
PATH_TO_SOURCE é o caminho relativo para o diretório de origem que contém a configuração do arquivo.

Por exemplo:

$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src

Quando a operação de implantação for concluída, você verá a seguinte mensagem:

Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.

Se a implantação falhar, consulte Arquivar erros de implantação para resolver problemas relacionados a esta etapa.

Etapa 5: verificar o proxy

Depois que seu proxy for implantado, você poderá usar um comando como o seguinte para garantir que ele funcione como esperado:

$ curl https://ORG_NAME-ENV_NAME.PROXY_URL

Em que:

ENV_NAME é o ambiente da Apigee em que o proxy deve ser implantado.
ORG_NAME é o nome da organização da Apigee;
PROXY_URL no URL do proxy implantado

Por exemplo, se você estiver chamando um proxy helloworld que deve retornar uma mensagem em caso de êxito:

$ curl https://myorg-dev.apigee.net/helloworld

Se o proxy estiver funcionando conforme o esperado, você verá o seguinte:

{
        "message": "Hello world!"
}

Atualizar um certificado para seu proxy

A Apigee não renova automaticamente os certificados em seu nome. Para manter os proxies funcionando conforme o esperado, talvez seja necessário atualizar periodicamente os certificados usados pelos seus ambientes. As etapas a seguir descrevem como criar um novo alias ou truststore no mesmo keystore usado para o proxy configurável.

Para atualizar um certificado de alias:

Abra a IU da Apigee em um navegador.
Selecione Admin > Environments > TLS Keystores e selecione o keystore que você quer atualizar.
Crie um novo objeto de alias e selecione o novo arquivo de certificado do Keystore, conforme descrito na Etapa 2: configurar o keystore acima.

Atualize o arquivo targetservers.json para fazer referência ao novo objeto de keystore. Por exemplo:

$ cat src/main/apigee/apiproxies/helloworld/apiproxy/environments/dev/targetservers.json
[
    {
        "name": "mymtlstarget",
        "description": "An example use mTLS",
        "host": "foo",
        "port": 8080,
        "isEnabled": true,
        "sSLInfo": {
                "enabled": true,
                "clientAuthEnabled": true,
                "keyStore": "mtls_keystore",
                "keyAlias": "new_mtls_alias",
                "trustStore": "mtls_truststore",
                "ignoreValidationErrors": false,
                "protocols": [
                "1.2"
                ],
                }
        },
        "protocol": "HTTP"
    },
    …
]

Implante o novo arquivo. Exemplo:
```
$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE
```
Em que:
- ENV_NAME é o ambiente da Apigee em que o proxy deve ser implantado.
- ORG_NAME é o nome da organização da Apigee;
- PATH_TO_SOURCE é o caminho relativo para o diretório de origem que contém a configuração do arquivo.
Por exemplo:
```
$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src
```
Quando a operação de implantação for concluída, você verá a seguinte mensagem:
```
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.
```

Agora seu proxy deve usar o arquivo de certificado keystore atualizado no objeto de alias. Confirme se o proxy está funcionando conforme o esperado usando as etapas descritas na Etapa 4: Verificar o proxy acima.

Para atualizar um certificado do truststore:

Abra a IU da Apigee em um navegador.
Selecione Admin > Environments > TLS Keystores e selecione o keystore que você quer atualizar.
Crie um novo objeto de alias e selecione o novo arquivo de certificado do Keystore, conforme descrito na Etapa 2: configurar o keystore acima.

Atualize o arquivo targetservers.json para fazer referência ao novo objeto de keystore. Por exemplo:

$ cat src/main/apigee/apiproxies/helloworld/apiproxy/environments/dev/targetservers.json
[
    {
        "name": "mymtlstarget",
        "description": "An example use mTLS",
        "host": "foo",
        "port": 8080,
        "isEnabled": true,
        "sSLInfo": {
                "enabled": true,
                "clientAuthEnabled": true,
                "keyStore": "mtls_keystore",
                "keyAlias": "mtls_alias",
                "trustStore": "new_mtls_truststore",
                "ignoreValidationErrors": false,
                "protocols": [
                "1.2"
                ],
                }
        },
        "protocol": "HTTP"
    },
    …
]

Implante o novo arquivo. Exemplo:
```
$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE
```
Em que:
- ENV_NAME é o ambiente da Apigee em que o proxy deve ser implantado.
- ORG_NAME é o nome da organização da Apigee;
- PATH_TO_SOURCE é o caminho relativo para o diretório de origem que contém a configuração do arquivo.
Por exemplo:
```
$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src
```
Quando a operação de implantação for concluída, você verá a seguinte mensagem:
```
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.
```

Agora seu proxy deve usar o arquivo de certificado truststore atualizado no objeto alias. Confirme se o proxy está funcionando conforme o esperado usando as etapas descritas na Etapa 4: Verificar o proxy acima.

Guia de solução de problemas e erro

Nesta seção, descrevemos vários problemas comuns de configuração e mensagens de erro que podem ser encontrados ao configurar o mTLS para seu proxy configurável. Sempre que possível, sugerimos soluções em potencial para esses problemas.

Erros de atualização do keystore

Esta seção descreve erros que você pode encontrar ao fazer atualizações em arquivos keystore.

Atualizar um alias de keystore

Se você tentar atualizar um alias do truststore ou do keystore com um novo certificado para um ambiente de proxy configurável sem implantar um novo arquivo, o seguinte erro será exibido:

Alias updates are currently disabled for configurable proxy environments. To update the certificate,
create a new alias and reference it within a new archive deployment.

Atualizar uma referência de keystore

Se você tentar atualizar uma referência de keystore para um ambiente de proxy configurável sem implantar um novo arquivo, o seguinte erro será exibido:

Reference updates are currently disabled for configurable proxy environments.
To update the reference, create a new reference and reference it within a new archive deployment.

Arquivar erros de implantação

Esta seção descreve casos de erro que você pode encontrar ao implantar o arquivo de proxy configurável.

Armazenamento de chaves ausente

Descrição

Nesse cenário, a implantação de arquivo especificada faz referência a um keystore inexistente na targetservers.json.

Exemplo

$ gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

Using Apigee organization 'myorg'
done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: missing required private key for "alias \"organizations/{org}/environments/{env}/keystores/does-not-exist/aliases/my_alias\"";
    missing required certificate(s) for "alias \"organizations/{org}/environments/{env}/keystores/does-not-exist/aliases/my_alias\""'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/afjq46noszlmmgt3uh
name: organizations/{org}/operations/6b7dbb09-fa01-4cb1-8c3f-9393027b3d92
organization: {org}
uuid: 6b7dbb09-fa01-4cb1-8c3f-9393027b3d92

Resolução

Para resolver o erro, é possível:

Crie um keystore com o mesmo nome referenciado no arquivo targetservers.json.
Atualize o arquivo targetservers.json para fazer referência a um keystore válido da Apigee.

Alias ausente

Descrição

Neste cenário, a implantação de arquivo especificada referencia um alias inexistente no arquivo targetservers.json:

Exemplo

$ gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

Using Apigee organization 'myorg'
done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: missing required private key for "alias \"organizations/{org}/environments/{env}/keystores/docs-keystore/aliases/does-not-exist\"";
    missing required certificate(s) for "alias \"organizations/{org}/environments/{env}/keystores/docs-keystore/aliases/does-not-exist\""'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/knvztvpqxbpojcdi9o
name: organizations/{org}/operations/2917bb4a-ebcb-4c59-8f48-187f6423da5d
organization: {org}
uuid: 2917bb4a-ebcb-4c59-8f48-187f6423da5d

Resolução

Para resolver o erro, é possível:

Crie um alias no keystore especificado com o mesmo nome referenciado no arquivo targetservers.json.
Atualize o arquivo targetservers.json para fazer referência a uma combinação válida de keystore e alias da Apigee.

O Truststore está faltando

Descrição

Neste cenário, a implantação de arquivo especificada referencia um alias inexistente no arquivo targetservers.json:

Exemplo

$ gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

Using Apigee organization 'myorg'
done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: missing required certificate(s) for truststore
    "organizations/{org}/environments/{env}/keystores/does-not-exist"'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/{archive}
name: organizations/{org}/operations/5bb2ab24-e4ba-4fb9-ab7e-d620a0672557
organization: {org}
uuid: 5bb2ab24-e4ba-4fb9-ab7e-d620a0672557

Resolução

Para resolver o erro, é possível:

Cria um truststore no keystore especificado com o mesmo nome referenciado no arquivo targetservers.json
Atualize o arquivo targetservers.json para fazer referência a uma combinação válida de keystore e truststore da Apigee.

Certificado inválido para alias ou truststore

Descrição

Nesse cenário, a implantação de arquivamento especificada referencia um certificado inválido ou expirado: o alias ou o truststore especificado no arquivo targetservers.json:

Exemplo

gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

done: true
error:
  code: 3
  message: 'generic::invalid_argument: proxy "organizations/{org}/apis/{api}/revisions/1"
    contains reference(s) to invalid target server(s): target server "mtlstarget-docs"
    contains invalid TLS settings: truststore "organizations/{org}/environments/{env}/keystores/expired-keystore"
    contains an invalid certificate within alias "organizations/{org}/environments/{env}/keystores/expired-keystore/aliases/expired":
    certificate has expired'
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: FINISHED
  targetResourceName: organizations/{org}/environments/{env}/archiveDeployments/{archive}
name: organizations/{org}/operations/3e28f818-8e1f-4afc-aedd-4aed29cc5519
organization: {org}
uuid: 3e28f818-8e1f-4afc-aedd-4aed29cc5519

Resolução

Para resolver o erro, é possível:

Atualize o alias especificado com um certificado novo e válido
Atualize o arquivo targetservers.json para fazer referência a uma combinação válida de keystore e alias da Apigee.

Erros de tráfego do ambiente de execução

Esta seção descreve casos de erro que você pode encontrar no ambiente de execução.

Certificados expirados ou inválidos

Descrição

Caso um certificado tenha expirado ou seja inválido, talvez você veja um erro 503 ao fazer uma solicitação ao seu proxy configurável:

Exemplo

$ curl https://myorg-dev.apigee.net/helloworld

upstream connect error or disconnect/reset before headers. reset reason: connection failure,
transport failure reason: TLS error: 268435581:SSL routines:OPENSSL_internal:CERTIFICATE_VERIFY_FAILED

Resolução

Para determinar a causa desse erro, verifique se:

Os certificados e chaves de back-end são válidos para os certificados e as chaves de proxy presentes no keystore referenciado.
Os certificados de back-end não expiraram. Para confirmar,
1. Abra a IU da Apigee em um navegador.
2. Selecione Admin > Environments > TLS Keystores e selecione seu keystore.
3. Verifique o status de expiração dos certificados.
O keystore referenciado não foi atualizado no meio de uma implantação de arquivo.

Para atualizar um certificado expirado, siga as instruções de Atualizar um certificado para seu proxy.