構成可能なプロキシの下り方向 mTLS の有効化

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示します。

このトピックでは、下り方向の相互 TLS（mTLS）を有効にして、Apigee の構成可能な API プロキシから mTLS 対応のプロキシターゲットとバックエンドへのトラフィックを保護する方法について説明します。相互 TLS（mTLS）を使うと、TLS handshake でクライアントとサーバーの両方のエンドポイントの認証が可能となり、ユーザーはクライアントとサーバーの両方が信頼できるエンティティであることを確認できます。多くの企業は、ネットワーク内のすべてのトラフィックの信頼性とセキュリティを確保するために mTLS を利用しています。Apigee のお客様は、構成可能なプロキシに mTLS 機能を追加することで、構成可能なプロキシに移行した後もこれまでと同じように mTLS を利用できます。また、既存の構成可能なプロキシとバックエンド間の通信のセキュリティを強化できます。

以下のセクションでは、Apigee の構成可能なプロキシへの下り方向（例: ゲートウェイ -> バックエンド）のトラフィックに対して mTLS サポートを設定するために必要な手順の概要を説明します。

構成可能な API プロキシ^{プレビュー}の開発は、Apigee 有料サブスクリプションの組織のお客様のみが利用できます。Apigee を従量課金制で使用している組織のお客様は、プログラム可能な API プロキシを作成できます。

mTLS のコンセプトの概要

次の図は、クライアントとサーバー（この場合は構成可能なプロキシとターゲットバックエンド）間の mTLS handshake の仕組みを示しています。

mTLS の図

上の図では、サーバーとクライアントの両方が独自の証明書 / 公開鍵と秘密鍵を含むキーストアを持っており、「相互」の TLS handshake が可能であることを示しています。検証の際、構成可能なプロキシのクライアントはトラストストア内の証明書とターゲットサーバーのバックエンドから送信された証明書を比較します。

TLS handshake を実行する場合:

TLS サーバーは、認証を受けるために自身の証明書を TLS クライアントに提示します。
クライアントはサーバーの ID を検証した後、認証を受けるために自身の証明書をサーバーに提示します。
相互認証の後、クライアントとサーバーは、両者の間でリクエストとレスポンスを暗号化するのに使用する、共有の秘密鍵を計算します。

mTLS 対応の構成可能なプロキシをデプロイする

次のセクションでは、ゲートウェイとターゲットバックエンドサーバー間のトラフィックの mTLS に対応する構成可能なプロキシをデプロイするために必要な手順を説明します。

ステップ 1: ソースファイルを構成する

mTLS 対応の構成可能なプロキシをデプロイする前に、次のような新しいファイルをいくつか設定する必要があります。

構成可能なプロキシゲートウェイがターゲットバックエンドサーバーと通信するために使用するトラストストア（証明書のみのエイリアス）、鍵、証明書エイリアス。
上記のトラストストア、鍵、証明書を含む Apigee キーストア。
ターゲットサーバーの構成にキーストアの詳細を含むアーカイブのデプロイ。

必要なソースファイルを作成するには:

次のコマンドを使用して、プライベート認証局（CA）の秘密鍵と公開鍵を作成します。

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

次のコマンドを使用して、構成可能なプロキシゲートウェイの証明書、秘密鍵、証明書署名リクエスト（CSR）を作成します。
```
openssl genrsa -out my_gateway.key 2048
openssl req -new -key my_gateway.key -out my_gateway.csr
```

前の手順で作成した認証局を使用して、新しく作成したクライアント証明書に署名します。

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

次のコマンドを使用して、サーバー証明書、秘密鍵、証明書署名リクエスト（CSR）を作成します。
```
openssl genrsa -out my_server.key 2048
openssl req -new -key my_server.key -subj '/CN=${SERVER_HOST}' -out my_server.csr
```

前の手順で作成した認証局を使用して、新しく作成したサーバー証明書に署名します。

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

正常に完了すると、次の例に示すように、ディレクトリに 8 つの新しいファイルが追加されます。

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

ステップ 2: キーストアを構成する

次の手順に沿い Apigee キーストアを作成して構成します。

ブラウザで Apigee UI を開きます。
[管理] > [環境] > [TLS Keystores] を選択します。
[+ Keystore] ボタンをクリックして、新しいキーストアを作成します。
次の図に示すように、[New Keystore] ダイアログに名前を入力します。
[Add Keystore] をクリックします。
[TLS Keystores] ランディングページで、先ほど作成したキーストアの行を選択し、[+] をクリックして新しいエイリアスを作成します。
[Create new alias] 画面で次の操作を行います。
- [Alias Name] を入力します。
- [Certificate Details] パネルの [Type] プルダウンから [Certificate and Key] を選択します。
- ファイル選択ツールを使用して、前の手順で作成したキーストアの証明書ファイルを選択します。
- [Key Password] を入力します。
- ファイル選択ツールを使用して、前の手順で作成したキーファイルを選択します。
次の図に示すように、各フィールドの入力が完了したら [Save] をクリックし、エイリアスと証明書の詳細を保存します。
[TLS Keystores] ランディングページで、先ほど作成したキーストアの行を選択し、[+] をクリックしてトラストストアの新しいエイリアスを作成します。
[Create new alias] 画面で次の操作を行います。
- [Alias Name] を入力します。
- [Certificate Details] パネルの [Type] プルダウンから [Certificate Only] を選択します。
- ファイル選択ツールを使用して、前の手順で作成したトラストストアの証明書ファイルを選択します。
- 次の図に示すように、各フィールドの入力が完了したら [Save] をクリックし、エイリアスと証明書の詳細を保存します。

これで、mTLS 対応の構成可能なプロキシアーカイブをデプロイするときに必要な TLS の詳細を含む、キーストアとトラストストアが Apigee 内に作成されました。

ステップ 3: アーカイブをフォーマットする

証明書と鍵を保持するキーストアが作成されたので、mTLS 対応の構成可能なプロキシのデプロイに使用するアーカイブを作成できます。

完了すると、アーカイブファイルの構造は次のようになります。

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

targetservers.json ファイルは、前のステップで構成したキーストアへの参照を保持するために使用されます。このファイルには、ステップ 2 で作成したキーストア、エイリアス、トラストストアへの参照が含まれている必要があります。次に例を示します。

#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"
    },
    …
]

mTLS を有効にするときに targetservers.json ファイルの SSLInfo セクションで必須となるフィールドは、次のとおりです。

enabled
clientAuthEnabled
keyStore
keyAlias
trustStore

オプションのフィールドは次のとおりです。

protocols
ciphers

これで、このターゲットサーバーをアーカイブプロキシ内で参照できるようになりました。たとえば、apiproxies/helloworld/config.yaml に次のようなオペレーションを含めることができます。

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

ステップ 4: プロキシをデプロイする

アーカイブの設定が完了したら、次のコマンドを使用して構成可能なプロキシをデプロイします。

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

ここで

ENV_NAME は、プロキシをデプロイする Apigee 環境です。
ORG_NAME は Apigee 組織の名前です。
PATH_TO_SOURCE は、アーカイブ構成を含むソースディレクトリへの相対パスです。

次に例を示します。

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

デプロイオペレーションが完了すると、次のメッセージが表示されます。

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

デプロイが失敗した場合は、アーカイブデプロイのエラーを参照し、このステップに関連する問題のトラブルシューティングを行います。

ステップ 5: プロキシを確認する

プロキシが正常にデプロイされたら、次のようなコマンドを使用して、期待どおりに動作することを確認できます。

$ curl https://ORG_NAME-ENV_NAME.PROXY_URL

ここで

ENV_NAME は、プロキシをデプロイする Apigee 環境です。
ORG_NAME は Apigee 組織の名前です。
PROXY_URL はデプロイしたプロキシの URL です。

たとえば、成功時にメッセージを返す helloworld プロキシを呼び出す場合は、次のようにします。

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

プロキシが期待どおりに機能している場合は、次のように表示されます。

{
        "message": "Hello world!"
}

プロキシの証明書を更新する

Apigee では、証明書が自動更新されることはありません。プロキシの意図した動作を維持するには、環境で使用する証明書を随時更新する必要があります。次の手順では、構成可能なプロキシに使用するのと同じキーストアの下に、新しいエイリアスまたはトラストストアを作成する方法を説明します。

エイリアス証明書を更新するには:

ブラウザで Apigee UI を開きます。
[管理] > [環境] > [TLS Keystores] を選択し、更新するキーストアを選択します。
上記のステップ 2: キーストアを構成するの説明に従って、新しいエイリアスオブジェクトを作成し、新しいキーストアの証明書ファイルを選択します。

新しいキーストアオブジェクトを参照するように targetservers.json ファイルを更新します。次に例を示します。

$ 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"
    },
    …
]

新しいアーカイブをデプロイします。次に例を示します。
```
$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE
```
ここで
- ENV_NAME は、プロキシをデプロイする Apigee 環境です。
- ORG_NAME は Apigee 組織の名前です。
- PATH_TO_SOURCE は、アーカイブ構成を含むソースディレクトリへの相対パスです。
次に例を示します。
```
$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src
```
デプロイオペレーションが完了すると、次のメッセージが表示されます。
```
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.
```

プロキシが、エイリアスオブジェクトに含まれる更新されたキーストア証明書ファイルを使用するようになりました。上記のステップ 4: プロキシを確認するで概説されている手順に沿って、プロキシが想定どおりに動作していることを確認してください。

トラストストア証明書を更新するには:

ブラウザで Apigee UI を開きます。
[管理] > [環境] > [TLS Keystores] を選択し、更新するキーストアを選択します。
上記のステップ 2: キーストアを構成するの説明に従って、新しいエイリアスオブジェクトを作成し、新しいキーストアの証明書ファイルを選択します。

新しいキーストアオブジェクトを参照するように targetservers.json ファイルを更新します。次に例を示します。

$ 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"
    },
    …
]

新しいアーカイブをデプロイします。次に例を示します。
```
$ gcloud alpha apigee archives deploy --env=ENV_NAME --org=ORG_NAME --source=PATH_TO_SOURCE
```
ここで
- ENV_NAME は、プロキシをデプロイする Apigee 環境です。
- ORG_NAME は Apigee 組織の名前です。
- PATH_TO_SOURCE は、アーカイブ構成を含むソースディレクトリへの相対パスです。
次に例を示します。
```
$ gcloud alpha apigee archives deploy --env=dev --org=myorg --source=src
```
デプロイオペレーションが完了すると、次のメッセージが表示されます。
```
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.
```

プロキシが、エイリアスオブジェクトに含まれる更新されたトラストストア証明書ファイルを使用するようになりました。上記のステップ 4: プロキシを確認するで概説されている手順に沿って、プロキシが想定どおりに動作していることを確認してください。

トラブルシューティングとエラーガイド

このセクションでは、構成可能なプロキシ用に mTLS を構成する際に発生する可能性のある、一般的な構成の問題とエラーメッセージについて説明します。可能であれば、これらの問題に対して考えられる解決策が示されます。

キーストア更新エラー

このセクションでは、キーストアファイルの更新中に発生する可能性のあるエラーについて説明します。

キーストアエイリアスを更新する

新しいアーカイブをデプロイせずに、構成可能なプロキシ環境用のトラストストアまたはキーストアのエイリアスを新しい証明書で更新しようとすると、次のエラーが表示されます。

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.

キーストア参照を更新する

新しいアーカイブをデプロイせずに構成可能なプロキシ環境用のキーストア参照を更新しようとすると、次のエラーが表示されます。

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.

アーカイブデプロイのエラー

このセクションでは、構成可能なプロキシアーカイブのデプロイ時に発生する可能性のあるエラーケースについて説明します。

キーストアが見つからない

説明

このシナリオでは、指定されたアーカイブデプロイが、targetservers.json 内の存在しないキーストアを参照しています。

例

$ 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

解決策

このエラーを解決する方法は次のいずれかです。

targetservers.json ファイル内で参照されているのと同じ名前のキーストアを作成します。
既存の有効な Apigee キーストアを参照するように targetservers.json ファイルを更新します。

エイリアスが見つからない

説明

このシナリオでは、指定したアーカイブデプロイが、targetservers.json ファイル内の存在しないエイリアスを参照しています。

例

$ 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

解決策

このエラーを解決する方法は次のいずれかです。

targetservers.json ファイル内で参照されているのと同じ名前で、指定されたキーストア内にエイリアスを作成します。
既存の有効な Apigee キーストアとエイリアスの組み合わせを参照するように、targetservers.json ファイルを更新します。

トラストストアが見つからない

説明

このシナリオでは、指定したアーカイブデプロイが、targetservers.json ファイル内の存在しないエイリアスを参照しています。

例

$ 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

解決策

このエラーを解決する方法は次のいずれかです。

targetservers.json ファイルで参照されているのと同じ名前で、指定したキーストア内にトラストストアを作成します。
既存の有効な Apigee キーストアとトラストストアの組み合わせを参照するように、targetservers.json ファイルを更新します。

エイリアスまたはトラストストアの無効な証明書

説明

このシナリオでは、指定されたアーカイブデプロイが、targetservers.json ファイルで指定されたエイリアスまたはトラストストアに対して無効または期限切れの証明書を参照しています。

例

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

解決策

このエラーを解決する方法は次のいずれかです。

指定されているエイリアスを新しい有効な証明書で更新します。
既存の有効な Apigee キーストアとエイリアスの組み合わせを参照するように、targetservers.json ファイルを更新します。

ランタイムトラフィックのエラー

このセクションでは、実行時に発生する可能性のあるエラーのケースについて説明します。

期限切れまたは無効な証明書

説明

証明書が期限切れまたは無効の場合、構成可能なプロキシにリクエストを送信したときに 503 エラーが表示されることがあります。

例

$ 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

解決策

このエラーの原因を特定するために、次のことを確認してください。

バックエンドの証明書と鍵が、参照されたキーストアに存在するプロキシの証明書と鍵に対して有効である。
バックエンドの証明書が失効していない。確認手順は次のとおりです。
1. ブラウザで Apigee UI を開きます。
2. [管理] > [環境] > [TLS Keystores] を選択し、キーストアを選択します。
3. 証明書の [Expiration Status] を確認します。
参照されたキーストアがアーカイブのデプロイ中に更新されていない。

期限切れの証明書を更新するには、プロキシの証明書を更新するの手順を実施します。

構成可能なプロキシの下り方向 mTLS の有効化

mTLS のコンセプトの概要

mTLS 対応の構成可能なプロキシをデプロイする

ステップ 1: ソースファイルを構成する

ステップ 2: キーストアを構成する

ステップ 3: アーカイブをフォーマットする

ステップ 4: プロキシをデプロイする

ステップ 5: プロキシを確認する

プロキシの証明書を更新する

トラブルシューティングとエラー ガイド

キーストア更新エラー

キーストア エイリアスを更新する

キーストア参照を更新する

アーカイブ デプロイのエラー

キーストアが見つからない

説明

例

解決策

エイリアスが見つからない

説明

例

解決策

トラストストアが見つからない

説明

例

解決策

エイリアスまたはトラストストアの無効な証明書

説明

例

解決策

ランタイム トラフィックのエラー

期限切れまたは無効な証明書

説明

例

解決策

トラブルシューティングとエラーガイド

キーストアエイリアスを更新する

アーカイブデプロイのエラー

ランタイムトラフィックのエラー