操作ガイド

API のプロダクト構成について

スタートアップ時に、Apigee アダプタが Edge 組織 / 環境から API プロダクトの定義をダウンロードします。API プロダクトを作成するで説明されているとおり、アダプタはこの情報を使用して、Edge 環境内で API プロダクトにバインドした Istio サービスにポリシー（API キー検証の実行など）を適用します。

プロダクトの構成について、次の点に注意する必要があります。

  • 対象のサービス名が API プロダクトにバインドされていない場合、ポリシーは適用されません。Binding コマンドもご覧ください。
  • パスの照合は、Istio リクエストパスに対して行われます。
  • パスの照合には、Apigee のプロダクト ドキュメントで説明されているワイルドカードと同様の意味合いがありますが、ベースパスがないため、次のようにまとめることができます。
    • 単一のスラッシュ（/）のみで、任意のパスにマッチします。
    • * はスラッシュに囲まれたセグメント内のどの場所でも有効で、任意の文字列に一致します。
    • ** は末尾で有効で、行末までの任意の文字列に一致します。
  • 対象のサービスが API プロダクトにマッピングされている場合:
    • リクエストパスに一致しないリクエストは拒否されます。
    • リクエストパスに一致するリクエストに認証が適用されます。
    • 認証されたリクエストは、関連する任意の割り当てに適用されます。

分析ロギングについて

リクエストは、認証や API プロダクトとのマッピングに関係なく、分析をロギングする場合があります。Mixer の Apigee 分析ハンドラに送信されたリクエストは、Edge Analytics に設定され、Edge Analytics UI からアクセスできるようになります。

JWT ベースの認証を使用する

API キーを使用する代わりに、有効な JSON ウェブトークン（JWT）を受け入れるように Apigee アダプタを構成できます。このセクションでは、JWT を受け入れるように Adapter を構成する方法について説明します。

  1. cd を実行して、Apigee アダプタがインストールされているディレクトリ apigee-istio-adapter. に移動します。
  2. samples/apigee/authentication-policy.yaml ファイルを開きます。

  3. spec セクションで、独自の組織と環境の値を使用して、JWT 構成 URL を編集します。次に例を示します。

    issuer: https://org-env.apigee.net/istio-auth/token
jwks_uri: https://org-env.apigee.net/istio-auth/certs

    例:

    spec:
  origins:
  - jwt:
      issuer: https://jdoe-test.apigee.net/istio-auth/token
      jwks_uri: https://jdoe-test.apigee.net/istio-auth/certs

    Apigee Edge Private Cloud を使用している場合は、Private Cloud のインストールに適した値を参照する必要があります。たとえば、apigee.net を、組織環境の仮想ホスト エイリアスに置き換えます。仮想ホストの詳細については、Edge のドキュメントをご覧ください。

  4. 相互 TLS（mTLS）にポリシーを正しく構成します。

    Istio メッシュの mTLS 認証設定は、認証ポリシーに一致している必要があります。mTLS を使用するように Istio を設定している場合（つまり、Istio のインストール時に istio-demo-auth.yaml を適用した場合）、authentication-policy.yaml で mTLS を明示的に有効にする必要があります。この操作を行うには、次のように authentication-policy.yaml で mtls の行のコメントを解除します。

    peers:
- mtls:   # uncomment if you're using mTLS between services (eg. istio-demo-auth.yaml)

    メッシュで mTLS を有効にしていない場合は、認証ポリシーで有効にしないでください。mtls の行をコメントアウトします。ポリシーが一致しない場合は、upstream connect error または disconnect/reset before headers のようなエラーが表示されます。

  5. 変更を保存して、Istio 認証ポリシーを適用します。

    kubectl apply -f samples/apigee/authentication-policy.yaml

  6. /hello API を呼び出します（API キーヘッダーの指定は必須ではありません）。処理に失敗して、次のエラー メッセージが返されます。

    curl http://$HELLOWORLD_URL/hello
Origin authentication failed.

    次に、Apigee Edge から JWT トークンを取得します。

    apigee-istio token create -o [your org] -e [your environment] -i [consumer_key] -s [consumer_secret]

    ここで、Edge 組織、環境、作成したデベロッパー アプリのコンシューマ キーとコンシューマ シークレットを指定します。詳しくは、API キーを取得するをご覧ください。

    例:

    apigee-istio token create -o myorg -e test -i c8516b0faa10d7db48d1198fa86e0dfbad7645b0d064354619a3bf0cfa34ac3d -s ce6c9a03c2b70059be626dd349a74e52ca44593539229f350410f0010419eb9f
  {"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIifQ.eyJhcGlfcHJvZHVjdF9saXN0IjpbImlzdGlvLWhlbGxvIl0sImF1ZGllbmNlIoibWljcm9nYXRld2F5IiwianRpIjoiNDRhNzhhcQtMDVmMC00MTM5LTNjctOWIxZWFkZTA2N2Q2IiwiaXNzIjoiaHR0cHM6Ly93aWxsd2l0bWFuLXc3QuYXBpZ2VlLm5ldC9lZGdlbWljcm8tYXV0aC92ZXJpZnlBcLZXkiLCJhY2Nlc3NfdG9rZW4iOm51bGwsImNsaWVudF9pZCI6IjZVN2kyS0dyaEc4d0FHNkdZMWZ67WtEYmNtdU9RQ3hBIiwibmJmIjoxNTIyNDE4MTY2LA4CdyCJpYXQiOjE1MjI0MTgxNjYsImFwcGxpY2FaW9uX25hbWUiOiJoWxsby1pc3Rpby1hcHAiLCJleHAiOjE1MjI0MTg0Nj9.f9F0w0Z8MYXkKuSIY3UKN2-GyZnEtuz0pV0CNIoc7Op4GKkNN_nvcTmKXe3cadERBULozumfzMGAnjmrazDFkq90ADa2mv78yIBBQeDdMo2STPPIHPEsxre3Ll0mUeE7vvLBv1LC6_PtR79dYzQYGOExGL0hvihLmOLSFDy_qrljO9oR1XbMWGLTNGComYweujqzgHi0ZimgAkPf8Z84ADt07wmJ3N_j1SYmVp38InDrb9361kZIYGs-bz99BKMsEgxlhy5TEr8W7g8auLDbKdcBDTA96kSwihWTEdYJ3r5j2_mBdZxZ9WOxqb_CmIAZPl6Dgtm6xtc4w4EZ8iA"

  7. Authorization ヘッダーに表示された JWT 署名なしトークンを使用して、/hello API を再度呼び出します。次に例を示します。

    curl http://$HELLOWORLD_URL/hello -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIifQ.eyJhcGlfcHJvZHVjdF9saXN0IjpbImlzdGlvLWhlbGxvIl0sImF1ZGllbmNlIoibWljcm9nYXRld2F5IiwianRpIjoiNDRhNzhhcQtMDVmMC00MTM5LTNjctOWIxZWFkZTA2N2Q2IiwiaXNzIjoiaHR0cHM6Ly93aWxsd2l0bWFuLXc3QuYXBpZ2VlLm5ldC9lZGdlbWljcm8tYXV0aC92ZXJpZnlBcLZXkiLCJhY2Nlc3NfdG9rZW4iOm51bGwsImNsaWVudF9pZCI6IjZVN2kyS0dyaEc4d0FHNkdZMWZ67WtEYmNtdU9RQ3hBIiwibmJmIjoxNTIyNDE4MTY2LA4CdyCJpYXQiOjE1MjI0MTgxNjYsImFwcGxpY2FaW9uX25hbWUiOiJoWxsby1pc3Rpby1hcHAiLCJleHAiOjE1MjI0MTg0Nj9.f9F0w0Z8MYXkKuSIY3UKN2-GyZnEtuz0pV0CNIoc7Op4GKkNN_nvcTmKXe3cadERBULozumfzMGAnjmrazDFkq90ADa2mv78yIBBQeDdMo2STPPIHPEsxre3Ll0mUeE7vvLBv1LC6_PtR79dYzQYGOExGL0hvihLmOLSFDy_qrljO9oR1XbMWGLTNGComYweujqzgHi0ZimgAkPf8Z84ADt07wmJ3N_j1SYmVp38InDrb9361kZIYGs-bz99BKMsEgxlhy5TEr8W7g8auLDbKdcBDTA96kSwihWTEdYJ3r5j2_mBdZxZ9WOxqb_CmIAZPl6Dgtm6xtc4w4EZ"
Hello version: v2, instance: helloworld-v2-6755887594-bnf6q

JWT トークンの検査と JWT トークンのローテーションもご覧ください。

JWT クレームでの Apigee API キーの使用

JWT クレームに渡された Apigee API キーを検証するように Apigee アダプタを構成できます。クレームは、JWT に追加される情報で、名前と値から構成されます。この情報は通常、JWT のサブジェクトに関する情報で、API リクエストの追加検証に使用できます。JWT ベースの認証を使用するもご覧ください。

アダプタの構成

アダプタには、Apigee API キーを含む JWT クレームの名前を通知する必要があります。

  1. samples/apigee/handler.yaml ファイルを開きます。

  2. ハンドラ ファイルの spec セクションに、次の構成属性を追加します。

    api_key_claim: my_apigee_apikey_claim_name

    ここで、my_apigee_apikey_claim_name は JWT クレーム名に有効な文字列です。詳しくは、JSON ウェブトークンの RFC をご覧ください。

    例:

    # istio handler configuration for apigee adapter
# generated by apigee-istio provision on 2018-08-01 16:15:36
apiVersion: config.istio.io/v1alpha2
kind: apigee
metadata:
  name: apigee-handler
  namespace: istio-system
spec:
  apigee_base: https://istioservices.apigee.net/edgemicro
  customer_base: https://myorg-test.apigee.net/istio-auth
  org_name: apigeesearch
  env_name: test
  key: 93b9ba790045250b1949b15731d6e565117ed8dd63afbd461974acaf404771e4
  secret: 5635f82c78af54f52df157d3023edbd3658437b0ca43cef19a988b475257ab0a
  api_key_claim: my_apigee_apikey_claim_name

  3. ハンドラ ファイルを Istio に適用します。

    kubectl apply -f samples/apigee/handler.yaml

アダプタは、リクエストを受け取ると、このクレームが有効な JWT に含まれているかどうか確認します。この名前のクレームが有効な JWT に含まれていることを確認すると、API キーの検証を行います。キーが有効な場合、呼び出しが行われます。無効な場合、呼び出しは拒否されます。

優先ルール

アダプタは、JWT と API キーを評価するときに、次の優先ルールに従います。

  1. 有効な JWT に handler.yaml ファイルで指定された api_key_claim の値と一致するクレーム名があり、そのクレームに Apigee API キーが含まれている場合、アダプタはキーの検証を行います。これ以外の JWT クレームは検証されません。
  2. リクエストに API キーしか含まれていない場合、アダプタはキーの検証を行います。
  3. api_key_claim の値に一致する JWT クレーム名が見つからない場合、アダプタは通常の JWT 検証手順に従います。詳しくは、JWT ベースの認証を使用するをご覧ください。

割り当てについて

割り当てとは、1 時間、1 日、1 週間または 1 か月にアプリが API に送信できるリクエスト メッセージの数を指定したものです。アプリが割り当て制限に達すると、以降の API 呼び出しは拒否されます。

割り当てのユースケース

割り当てを使用すると、一定の期間内にクライアントがサービスに行うリクエスト数を制限できます。割り当ては、運用上のトラフィック管理ではなく、開発者やパートナーとの業務契約または SLA の適用で使用されています。たとえば、無料サービスのトラフィックを制限し、有料のお客様にフルアクセスを許可するために使用されています。

API プロダクトでの割り当ての定義

Quota パラメータは API プロダクトで構成します。たとえば、API プロダクトを作成するときに、割り当て上限、時間単位、間隔を設定できます。

alt_text

API キーは API プロダクトにマッピングされるため、API キーが検証されるたびに、該当する割り当てカウンタの値が減少します（割り当てが関連するプロダクトで定義されている場合）。

割り当てカウントを維持する場所

起動時に、Apigee アダプタは Apigee Edge から構成情報（プロダクトの構成など）を取得します。パフォーマンス上の理由から、Apigee アダプタはローカル キャッシュにカウンタを維持し、値を減らします。アダプタは、割り当てカウントと Apigee Edge で維持されている割り当て状態の同期を定期的に行います。

機密情報のマスキング

Istio にデプロイされているサービスへのリクエストには、機密情報が含まれている可能性があります。Apigee Analytics プラットフォームに送信する前に、このデータをマスキングできます。このセクションでは、次の情報をマスキングする方法を説明します。

  • リクエストパスに表示されるデータ（クエリ パラメータなど）
  • クライアント IP

重要なパスとクライアント IP データをマスキングするには、次の操作を行います。

  1. Apigee 固有の definitions.yaml ファイルを開きます。これは、Apigee 提供のファイルで、Apigee アダプタの基本構造と動作が定義されています。たとえば、Apigee アダプタ ディストリビューションでは samples/apigee/definitions.yaml です。

  2. kind の analytics section で次の属性を探します。

    client_ip: source.ip | ip("0.0.0.0")
request_uri: request.path | ""
request_path: request.path | ""

  3. 次の属性を定数に変更し、マスキングします。例:

    client_ip: ip("0.0.0.0")
request_uri: ""
request_path: ""

マスキングが必要なサービスと、それほど重要でないサービスが混在していることもあります。その場合は、2 つの定義を作成します。たとえば、次の定義を作成します。

kind: analytics

さらに、次の定義を作成します。

kind: maskedanalytics

適切な analytics または maskedanalytics インスタンスを呼び出すためのルールを作成して適用します。

サンプル ファイルについて

サンプルの構成ファイルは samples/apigee ディレクトリにあります。これらのファイルは、Mixer に適用する Apigee 固有のルールと定義を構成する場合に使用されます。

ファイル 説明
handler.yaml 特定の Apigee テナントの Apigee アダプタを定義します。プロビジョニング コマンドで返される値を追加する場合は、このファイルを編集する必要があります。このような値には、キーとシークレット、組織名、環境名、ベース URI などがあります。ハンドラもご覧ください。
rule.yaml Apigee Mixer アダプタをリクエストに適用するためのルールを定義します。ルールはこのファイルに追加します。ルールもご覧ください。
definitions.yaml Apigee Mixer アダプタの基本構造とデータマップを定義します。通常、このファイルを編集する必要はありません。
authentication-policy.yaml Authentication ポリシーを作成してサービスにバインドします。JWT 認証を使用する場合は、このファイルを構成して適用します。
httpapispec.yaml Istio で API を定義します。API は、サービスに対するリクエストを識別し、このリクエストに API 属性と動作をバインドします。通常、このファイルを編集または適用する必要はありません。

ハンドラの構成

ハンドラ ファイルには、複数の構成可能な属性が定義されています。設定例は samples/apigee/handler.yaml ファイルにあります。

属性 説明
temp_dir アダプタが一時ファイルを保存するディレクトリ。現在、このディレクトリには、アップロードの前にバッファに保存された分析レコードが保存されます。
server_timeout_secs Apigee Edge サーバーに対するクライアント リクエストの HTTP タイムアウト。
refresh_rate_mins アダプタが Apigee Edge をポーリングし、API プロダクトに対する変更を確認する間隔。デフォルト: 1
legacy_endpoint Edge Private Cloud を使用している場合は、分析の際に正しい実装が使用されるようにこの値を true に設定します。デフォルト: false
file_limit ローカルに保存できる分析レコード ファイルの数。ファイルがアップロードできない場合、この数を超えていると、最も古いレコードが削除されます。デフォルト: 1024

Apigee アダプタの無効化

Apigee アダプタを無効にするには、適用した構成を削除します。例:

kubectl delete -f samples/apigee/definitions.yaml
kubectl delete -f samples/apigee/handler.yaml
kubectl delete -f samples/apigee/rule.yaml

同じ構成を再度適用すれば、アダプタをいつでも有効にできます。

Istio のアンインストール

Istio ドキュメントで Istio コア コンポーネントのアンインストールをご覧ください。