カスタム・ドメインおよびTLS証明書の設定

APIゲートウェイ・サービスを使用して作成したAPIゲートウェイはTLS対応であるため、それを保護するには認証局によって発行されたTLS証明書(以前のSSL証明書)が必要です。APIゲートウェイに特定のカスタム・ドメイン名を指定するには、APIゲートウェイ・サービスでTLS証明書を自動取得するのではなく、自分で認証局からカスタムTLS証明書を取得する必要があります。

APIゲートウェイを作成するときには、APIゲートウェイで次のいずれかを使用することを指定します:

  • APIゲートウェイ・サービスにより自動取得されたTLS証明書(デフォルトの動作)。この場合、APIゲートウェイ・サービスによって、Oracle指定の認証局にTLS証明書がリクエストされます。
  • 選択した認証局から自分で取得したカスタムTLS証明書。認証局へのリクエストにはカスタム・ドメイン名が含まれます。認証局はカスタムTLS証明書を含むファイルを返し、また通常は、TLS証明書から認証局に戻る証明書チェーンを形成する、中間証明書を含む1つ以上のファイルを返します。

APIゲートウェイでカスタムTLS証明書を使用できるようにするには、カスタムTLS証明書、中間証明書、およびTLS証明書の生成に使用される秘密キーを含むAPIゲートウェイ証明書リソースを作成します。その後、新しいAPIゲートウェイの作成時に、そのAPIゲートウェイ証明書リソースを指定します。

TLS証明書を取得した方法によって、APIゲートウェイのドメイン名をどの程度制御できるかが決まります:

  • APIゲートウェイ・サービスでTLS証明書を自動取得した場合は、APIゲートウェイ・サービスによって、自動生成されたドメイン名がAPIゲートウェイに付与されます。自動生成されたドメイン名は、ランダムな文字列の後に.apigateway.<region-identifier>.oci.customer-oci.comを付けて構成されます。たとえば、laksjd.apigateway.us-phoenix-1.oci.customer-oci.comです。
  • カスタムTLS証明書を自分で取得した場合は、認証局へのリクエストで指定したカスタム・ドメイン名がAPIゲートウェイ・サービスによってAPIゲートウェイに付与されます。

TLS証明書を取得した方法によって、DNSプロバイダでAPIゲートウェイのドメイン名とそのパブリックIPアドレスとの間のマッピングを記録する担当も決まります:

  • APIゲートウェイ・サービスでTLS証明書を自動取得した場合は、APIゲートウェイが、Oracle Cloud Infrastructure DNSサービスでAPIゲートウェイの自動生成ドメイン名とそのパブリックIPアドレスとの間のマッピングを記録します。
  • カスタムTLS証明書を自分で取得した場合は、Aレコードとして選択したDNSプロバイダで、APIゲートウェイのカスタム・ドメイン名とそのパブリックIPアドレスの間のマッピングを自分で記録する必要があります。

同様に、TLS証明書の有効期限と更新の処理も、最初にTLS証明書を取得した方法によって決まります:

  • APIゲートウェイ・サービスでTLS証明書を自動取得した場合は、TLS証明書が期限切れになる前に、APIゲートウェイ・サービスによってOracle指定の認証局で自動更新されます。
  • カスタムTLS証明書を自分で取得した場合は、TLS証明書が期限切れになる前に、選択した認証局で自分で更新する必要があります。認証局から新しいカスタムTLS証明書を受け取ったら、新しいカスタムTLS証明書の詳細を使用して新しいAPIゲートウェイ証明書リソースを作成します。その後、元のAPIゲートウェイ証明書リソースを使用していたAPIゲートウェイを、新しい証明書リソースを使用するように更新します。

カスタム・ドメインおよびカスタムTLS証明書の使用が必須となる場合もあります。たとえば、Oracle Cloud Infrastructure Government Cloudを使用している場合は、次のことが必要になります:

  • 特定の承認済認証局からのTLS証明書のみを取得する
  • 特定の承認済DNSプロバイダのみを使用する

また、商業的な要件によってカスタム・ドメインの使用が必要になる場合もあります。たとえば、自動生成されたランダムな文字列に続く.apigateway.<region-identifier>.oci.customer-oci.coの部分を会社名に置き換えてAPIゲートウェイのドメイン名に含めることがよくあります。

次に注意してください:

  • 現在APIゲートウェイによって使用されているAPIゲートウェイ証明書リソースを削除することはできません。APIゲートウェイ証明書リソースを削除するには、まず、それを使用しているAPIゲートウェイから削除する必要があります。
  • 1つのAPIゲートウェイに指定できるAPIゲートウェイ証明書リソースは、1つのみです。
  • いったん作成したAPIゲートウェイ証明書リソースは更新できません。
  • 最初にAPIゲートウェイを作成したときにAPIゲートウェイ証明書リソースを指定した場合、その既存のAPIゲートウェイのAPIゲートウェイ証明書リソースは変更できます。
重要

パブリック・システムまたは本番システムには、カスタムTLS証明書を使用することをお薦めします。APIゲートウェイ・サービスによって取得されたTLS証明書は、(たとえば、開発およびテスト用の)プライベート・システムまたは非本番システムでのみ使用することをお薦めします。

APIゲートウェイのカスタム・ドメイン名およびTLS証明書の設定

APIゲートウェイのカスタム・ドメイン名およびTLS証明書を設定するには:

ステップ1: 選択した認証局からのTLS証明書の取得

TLS証明書を取得する正確なステップは、使用するように選択した認証局によって異なります。大まかなステップは次のようになりますが、詳細情報については必ず認証局のドキュメントを参照してください:

  1. 選択した認証局の証明書署名リクエストを作成します。

    通常は、証明書署名リクエストに組織名、地域、国などの情報を含めます。

    また、証明書署名リクエストに、保護するサイトの完全修飾ドメイン名としての共通名も含めます。通常、この共通名によってTLS証明書が特定のドメインと接続されます。このドメイン名は、APIゲートウェイのカスタム・ドメイン名として使用されます。

    証明書署名リクエストを作成すると、公開キーがリクエストに追加され、対応する秘密キーも生成されてローカル・ファイルに格納されます。この秘密キーはAPIゲートウェイ証明書リソースの設定時に使用するため、その場所をノートにとっておきます。TLS証明書の取得に使用する秘密キーは:

    • RSAキーである必要があります
    • PEMでエンコードされたX.509フォーマットである必要があります
    • -----BEGIN RSA PRIVATE KEY-----で始まっている必要があります
    • -----END RSA PRIVATE KEY-----で終わっている必要があります
    • パスフレーズで保護しないでください
    • 最小長は2048ビットで、4096ビット以内にする必要があります
  2. 証明書署名リクエストを認証局に送信します。

    認証局は次のものを返します:

    • APIゲートウェイ自体のカスタムTLS証明書(「リーフ証明書」または「エンドエンティティ証明書」と呼ばれる)を含むファイル
    • 通常、リーフ証明書から認証局に戻る証明書チェーンを形成する中間証明書を含む1つ以上のファイル

これで、これらの証明書ファイルを使用してAPIゲートウェイ証明書リソースを作成できるようになります。

ステップ2: APIゲートウェイ証明書リソースの作成

APIゲートウェイ証明書リソースとは、APIゲートウェイ・サービスを使用してAPIゲートウェイを作成または更新するときに使用できる、TLS証明書の名前付き定義のことです。

APIゲートウェイの証明書リソースには、次のものが含まれます:

  • 証明書リソース自体の任意の名前
  • 認証局から返されたAPIゲートウェイのカスタムTLS証明書(「リーフ証明書」または「エンドエンティティ証明書」)
  • リーフ証明書から認証局に戻る証明書チェーンを形成する中間証明書
  • 元の証明書署名リクエストに含まれていた公開キーとペアになっている秘密キー

いったん作成したAPIゲートウェイ証明書リソースは更新できません。

APIゲートウェイ証明書リソースは、コンソールまたはCLIを使用して作成できます。

コンソールの使用

コンソールを使用してAPIゲートウェイ証明書リソースを作成するには:

  1. コンソールナビゲーション・メニューを開き、「開発者サービス」をクリックします。「API管理」で、「ゲートウェイ」をクリックします。
  2. 作業する権限があるコンパートメントを選択します。
  3. 「証明書」ページで、「証明書の追加」をクリックし、次を指定します:

    • 名前: 新しいAPIゲートウェイ証明書リソースの名前。機密情報の入力は避けてください。
    • 証明書: 認証局から返されたカスタムTLS証明書(「リーフ証明書」または「エンドエンティティ証明書」)。有効なTLS証明書をドラッグ・アンド・ドロップするか、選択するか、貼り付けます。指定するTLS証明書は:
      • PEMでエンコードされたX.509フォーマットである必要があります
      • -----BEGIN CERTIFICATE-----で始まっている必要があります
      • -----END CERTIFICATE-----で終わっている必要があります
      • 長さを4096ビット以内にする必要があります
    • 中間証明書: (オプション) TLS証明書から認証局に戻る証明書チェーンを形成する中間証明書が1つ以上ある場合は、中間証明書ファイルの内容を正しい順序で含めます。正しい順序は、最下部の信頼されたルート認証局が直接署名した証明書が最初で、その他の証明書はそれを署名した認証局のすぐ上です。例:

      -----BEGIN CERTIFICATE-----
      <PEM_encoded_certificate>
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      <PEM_encoded_certificate>
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      <PEM_encoded_certificate>
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      <PEM_encoded_certificate>
      -----END CERTIFICATE-----

      中間証明書ファイルの内容を連結して正しい順序で1つの証明書チェーン・ファイルにした場合は、そのファイルをドラッグ・アンド・ドロップするか、そのファイルを選択するか、そのファイルの内容を貼り付けます。

      連結された証明書チェーン・ファイルがない場合は、個々の証明書ファイルの内容を正しい順序で貼り付けます。

      指定する中間証明書を結合した長さが10240ビット以内になる必要があります。

    • 秘密キー: 認証局からTLS証明書を取得するために使用される秘密キー。このフィールドで、有効な秘密キーをドラッグ・アンド・ドロップするか、選択するか、貼り付けます。指定するキーは:
      • RSAキーである必要があります
      • PEMでエンコードされたX.509フォーマットである必要があります
      • -----BEGIN RSA PRIVATE KEY-----で始まっている必要があります
      • -----END RSA PRIVATE KEY-----で終わっている必要があります
      • パスフレーズで保護しないでください
      • 最小長は2048ビットで、4096ビット以内にする必要があります
  4. 「作成」をクリックして、APIゲートウェイ証明書リソースを作成します。

CLIの使用

CLIを使用してAPIゲートウェイ証明書リソースを作成するには:

  1. CLIを使用するためにクライアント環境を構成します(APIゲートウェイ開発用のCLIを使用するためのクライアント環境の構成)。
  2. コマンド・プロンプトを開き、oci api-gateway certificate createを実行して、APIゲートウェイ証明書リソースを作成します:

    oci api-gateway certificate create --display-name "<certificate-name>" --compartment-id <compartment-ocid> --certificate-file <certificate-file-path> --intermediate-certificates-file <intermediate-certificates-file-path> --private-key-file <private-key-file-path>

    ここでは:

    • <certificate-name>は、新しいAPIゲートウェイ証明書リソースの名前です。機密情報の入力は避けてください。
    • <compartment-ocid>は、新しいAPIゲートウェイ証明書リソースが属するコンパートメントのOCIDです。
    • <certificate-file-path>は、認証局から返されたリーフ証明書を含むファイルのパスと名前です。たとえば、~/.certs/cert.pemです。指定するファイル内のリーフ証明書は:

      • PEMでエンコードされたX.509フォーマットである必要があります
      • -----BEGIN CERTIFICATE-----で始まっている必要があります
      • -----END CERTIFICATE-----で終わっている必要があります
      • 長さを4096ビット以内にする必要があります
    • <intermediate-certificates-file-path>は、リーフ証明書から認証局に戻る証明書チェーンを形成する中間証明書を1つ以上含むファイルのパスと名前であり、オプションです。たとえば、~/.certs/int_cert.pemです。ファイルに複数の中間証明書が含まれている場合、それらの中間証明書を正しい順序で並べる必要があります。正しい順序は、信頼されたルート認証局が直接署名した証明書が最後で、その他の証明書はそれを署名した認証局の直前です。例:

      -----BEGIN CERTIFICATE-----<PEM_encoded_certificate>-----END CERTIFICATE----------BEGIN CERTIFICATE-----<PEM_encoded_certificate>-----END CERTIFICATE----------BEGIN CERTIFICATE-----<PEM_encoded_certificate>-----END CERTIFICATE----------BEGIN CERTIFICATE-----<PEM_encoded_certificate>-----END CERTIFICATE-----

      指定する中間証明書を結合した長さが10240ビット以内になる必要があります。

    • <private-key-file-path>は、認証局からTLS証明書を取得するために使用される秘密キーを含むファイルのパスと名前です。たとえば、~/.certs/key.pemです。指定するファイル内の秘密キーは:

      • RSAキーである必要があります
      • PEMでエンコードされたX.509フォーマットである必要があります
      • -----BEGIN RSA PRIVATE KEY-----で始まっている必要があります
      • -----END RSA PRIVATE KEY-----で終わっている必要があります
      • パスフレーズで保護しないでください
      • 最小長は2048ビットで、4096ビット以内にする必要があります

    例:

    oci api-gateway certificate create --display-name "Acme gateway certificate" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --certificate-file ~/.certs/cert.pem --private-key-file ~/.certs/key.pem

    コマンドへのレスポンスには、次が含まれます:

    • 新しいAPIゲートウェイ証明書リソースのOCID。
    • ライフサイクルの状態(たとえば、ACTIVE、FAILED)。
    • APIゲートウェイ証明書リソースを作成する作業リクエストのID (作業リクエストの詳細は、完了、取消または失敗の後の7日間利用可能です)。

    APIゲートウェイ証明書リソースがアクティブになる(またはリクエストが失敗する)までコマンドが制御を返すのを待機する場合は、次のいずれかまたは両方のパラメータを含めます:

    • --wait-for-state ACTIVE
    • --wait-for-state FAILED

    例:

    oci api-gateway certificate create --display-name "Acme gateway certificate" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --certificate-file ~/.certs/cert.pem --private-key-file ~/.certs/key.pem --wait-for-state ACTIVE

CLIの使用の詳細は、コマンドライン・インタフェース(CLI)を参照してください。CLIコマンドで使用可能なフラグおよびオプションの完全なリストについては、コマンドライン・リファレンスを参照してください。

ステップ3: APIゲートウェイ作成時のAPIゲートウェイ証明書リソースの指定

APIゲートウェイの作成時にAPIゲートウェイ証明書リソースを指定するには:

  1. APIゲートウェイの作成の手順に従って、コンソールまたはCLIを使用してAPIゲートウェイを作成します。
  2. 手順の説明に従って、APIゲートウェイ証明書リソースを指定します:

    • コンソールを使用する場合: 「証明書」フィールドを使用します。
    • CLIを使用する場合: --certificate-id <certificate-ocid>プロパティを設定します。

    APIゲートウェイ・サービスによって、新しいAPIゲートウェイが作成され、カスタムTLS証明書と秘密キーがインストールされます。

  3. APIゲートウェイのパブリックIPアドレスを取得します。
ステップ4: 選択したDNSプロバイダでのAPIゲートウェイのカスタム・ドメイン名とパブリックIPアドレスの間のマッピングの記録

APIゲートウェイのカスタム・ドメイン名とそのパブリックIPアドレスの間のマッピングを記録する正確なステップは、使用するように選択したDNSプロバイダによって異なります。通常は、DNSプロバイダの構成内で新しいレコード(具体的には新しいAレコード)を作成します。このレコードにより、選択した認証局にTLS証明書をリクエストするときに構成したドメイン名が、APIゲートウェイ・サービスで新しいAPIゲートウェイに割り当てられたパブリックIPアドレスに関連付けられます。詳細は、選択したDNSプロバイダのドキュメントを参照してください。

APIゲートウェイで使用されるカスタムTLS証明書の更新

TLS証明書は、期限切れになるまでの一定期間(通常は1~2年)有効です。APIゲートウェイで使用されるTLS証明書が期限切れになった場合、APIゲートウェイにデプロイされたAPIをコールすると警告メッセージが返されます。警告メッセージが表示されないようにするには、期限切れになる前にTLS証明書を更新する必要があります(証明書の「ローテーション」と呼ばれることもあります)

APIゲートウェイ・サービスで元のTLS証明書を自動取得した場合は、期限切れになる前に、APIゲートウェイ・サービスによってOracle指定の認証局でTLS証明書が自動更新されます。ただし、カスタムTLS証明書を自分で取得した場合は、期限切れになる前に、選択した認証局でカスタムTLS証明書を自分で更新する必要があります(ただし、TLS証明書の期限切れが近づいている場合は、コンソールに警告が表示されます)。

TLS証明書の更新をリクエストすると、認証局から完全に新しいTLS証明書が返されます。既存のAPIゲートウェイ証明書リソースを新しいTLS証明書で更新するだけでは不十分です。正しくは、新しいAPIゲートウェイ証明書リソースを作成し、新しいTLS証明書を新しい証明書リソースに追加してから、以前の証明書リソースを使用していたAPIゲートウェイを、新しい証明書リソースを使用するように更新します。

APIゲートウェイで使用されるカスタムTLS証明書を更新するには:

  1. 最初にTLS証明書を取得した認証局にTLS証明書更新リクエストを送信します。TLS証明書を更新する正確なステップは、使用する認証局によって異なるため、詳細は必ず認証局のドキュメントを参照してください。

    証明書更新リクエストを作成すると、公開キーがリクエストに追加され、対応する秘密キーも生成されてローカル・ファイルに格納されます。この秘密キーは新しいAPIゲートウェイ証明書リソースの設定時に使用するため、その場所をノートにとっておきます。

    認証局は新しいカスタムTLS証明書を含むファイルを返し、また通常は、TLS証明書から認証局に戻る証明書チェーンを形成する、中間証明書を含む1つ以上のファイルを返します。

  2. 新しいAPIゲートウェイ証明書リソースを作成し、新しいTLS証明書、中間証明書および新しい秘密キーをそれに追加します(ステップ2: APIゲートウェイ証明書リソースの作成を参照)。
  3. 元のAPIゲートウェイ証明書リソースを使用していたすべての既存のAPIゲートウェイを、新しいAPIゲートウェイ証明書リソースを使用するように更新します(APIゲートウェイおよびAPIデプロイメントの更新を参照)。
  4. 元のAPIゲートウェイ証明書リソースをまだ使用しているAPIゲートウェイがない場合は、元の証明書リソースを削除します:
    • コンソールを使用している場合: 「証明書」ページで、削除する元のAPIゲートウェイ証明書リソースの横にある「アクション」アイコン(3つのドット)をクリックし、「削除」をクリックします。
    • CLIを使用している場合: 次のコマンドを使用して、元のAPIゲートウェイ証明書リソースを削除します:
      oci api-gateway certificate delete --certificate-id <certificate-ocid>

    APIゲートウェイ証明書リソースは、まだそれを使用しているAPIゲートウェイがある場合は削除できません。

APIの使用

APIの使用およびリクエストの署名の詳細は、REST APIおよびセキュリティ資格証明を参照してください。SDKの詳細は、ソフトウェア開発キットとコマンドライン・インタフェースを参照してください。

次を使用します:

  • 新しいAPIゲートウェイ証明書リソースを作成するCreateCertificate操作
  • 既存のAPIゲートウェイ証明書リソースを削除するDeleteCertificate操作
  • 既存のAPIゲートウェイ証明書リソースの詳細を変更するUpdateCertificate操作
  • 既存のAPIゲートウェイ証明書リソースの詳細を表示するGetCertificate操作
  • コンパートメント内のすべての証明書をリストするListCertificates操作
  • 既存のAPIゲートウェイ証明書リソースが属するコンパートメントを変更するChangeCertificateCompartment操作