操作ガイド

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

スタートアップ時に、Apigee アダプタが Edge 組織 / 環境から API プロダクトの定義をダウンロードします。アダプタは、この情報を使用して、Edge 環境内の API プロダクトにバインドした Istio サービスにポリシー(API キー検証など)を適用します(バインドの詳細については、API プロダクトを作成するをご覧ください)。

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

  • 対象のサービス名が API プロダクトにバインドされていない場合、ポリシーは適用されません。バインド コマンドもご覧ください。
  • パスの照合は、Istio リクエストパスに対して行われます。
  • パスの照合は、Apigee プロダクトのドキュメントに記載されているワイルドカードのセマンティクスに似ていますが、ベースパスがないため、次のようにまとめることができます。
    • 1 個のスラッシュ(/)だけの場合は、すべてのパスに一致します。
    • * は任意の場所に使用でき、スラッシュで囲まれたセグメント内の文字列に一致します。
    • ** は文字列の末尾にのみ使用できます。行末までの任意の文字列に一致します。
  • 対象のサービスが 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 は、organization-environment のホスト名のエイリアスで置き換えます。仮想ホストの詳細については、Edge のドキュメントをご覧ください。

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

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

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

    メッシュで mTLS を有効にしていない場合は、認証ポリシーで有効にしないでください。単に mtls 行をコメントアウトします。ポリシーが一致しないと、upstream connect errordisconnect/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. handler.yaml ファイルの api_key_claim の値に一致するクレーム名が有効な JWT に含まれ、クレームに 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. 種類 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 for 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 コア コンポーネントのアンインストールをご覧ください。