Red Hat サブスクリプション管理で API の使用

Red Hat Subscription Management 2023

Red Hat サブスクリプション管理での API の認可、管理、およびトラブルシューティング

Customer Content Services

概要

Red Hat Subscription Management は、Red Hat 製品に対するサブスクリプションの自動化、管理、追跡に役立つ開発および文書化された API を提供します。

1. Red Hat サブスクリプション管理で API の使用

Red Hat Subscription Management の API を使用すると、Red Hat サブスクリプションおよびエンタイトルメントの使用状況をより効果的に追跡して、それらの管理を自動化しやすくなります。Red Hat Subscription Management の API を使用することで、以下のことが可能になります。

  • 製品に使用するツールの制御
  • システムインベントリーの管理を改善
  • システムのより効率的な更新とセキュリティー保護
  • Red Hat 製品の正式サポートを引き続き受けることが可能

Red Hat Subscription Management API は認可に OAuth 2.0 を使用します。トークンを取得し、API にアクセスするには、以下の情報が必要になります。

2. 認証でのトークンの使用

オフライントークンおよび更新トークンは、シークレットを使用してカスタマーポータルのアカウントを認証した後に、Red Hat サブスクリプション管理によりシステムを認証します。

警告

ネットワークのベストプラクティスに沿ったパスワード管理を使用してください。パスワードや認証情報をプレーンテキストに保存するのは危険です。オフライントークンには、パスワードを不正使用から保護するセキュリティー対策を同じように適用します。

2.1. 新しいオフライントークンの生成

オフライントークンは、30 日ごとに最低 1 回使用し、Red Hat Subscription Management API のアクセストークンを作成する場合に限り、有効期限が切れることはありません。これはパスワードとして機能し、新しい更新トークンを作成せずに引き続きアカウントを認証できます。

手順

  1. Red Hat Subscription Management API Tokens ページ をご覧ください。
  2. Generate Token ボタンをクリックします。

2.2. 新しい更新トークンの生成

オフライントークンを作成したら、そのトークンを使用して新しい更新トークンを作成できます。これには 5 分間有効なアクセストークンが含まれます。アクセストークンは、カスタマーポータルのユーザーを Red Hat Subscription Management API で認証するためにヘッダーに渡されます。

手順

  1. オフラインのトークン値を設定します。この例では、分かりやすくするためにプレーンテキストで設定し、トークンの値を短くしています。 

    # offline_token='eyJhbGciOiJSUzI1NiIsInR5cCIgOiA'

  2. JSON 値にフィルターを簡単に設定する関数を作成します。 

    # function jsonValue() {
KEY=$1
num=$2
awk -F"[,:}]" '{for(i=1;i<=NF;i++){if($i~/'$KEY'\042/){print $(i+1)}}}' | tr -d '"' | sed -n ${num}p
}

# curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id=rhsm-api -d refresh_token=$offline_token

以下のような出力が表示されるはずです。access_token は認可トークンとして使用されるトークンになります。 

{"access_token":"oiZjo1MjhkNzZmZi1mNzA4LTQzZWQtOGNkNS1mZTE2ZjRmZTBjZTY6cmhuLXN1cHBvcnQta3RvcmRldXIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJyaHNtLWFwaSIsImF1dGhfdGltZSI6MTU2NzQwODU5Nywic2Vzc2lvbl9zdGF0ZSI6ImYwZGJiOGQ0LTRlNGUtNDY1NC04NDRjLTZmMzcwNGM4NDQyMiIsImFjciI6IjAiLCJhbGxvd2VkLW9yaWdpbnMiOltdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsicG9ydGFsX21hbmFnZV9zdWJzY3JpcHRpb25zIiwib2ZmbGluZV9hY2Nlc3MiLCJjYW5kbGVwaW5fc3lzdGVtX2FjY2Vzc192aWV3X2VkaXRfYWxsIiwiYWRtaW46b3JnOmFsbCIsInBvcnRhbF9tYW5hZ2VfY2FzZXMiLCJwb3J0YWxfc3lzdGVtX21hbmFnZW1lbnQiLCJwb3J0YWxfZG93bmxvYWQiXX0sInJlc291cmNlX2FjY2VzcyI6e30sImFjY291bnRfaWQiOiIxOTc5NzEwIiwibmFtZSI6Iktlbm55IFRvcmRldXJzIiwicHJlZmVycmVkX3VzZXJuYW1lIjoicmhuLXN1cHBvcnQta3RvcmRldXIiLCJnaXZlbl9uYW1lIjoiS2VubnkiLCJmYW1pbHlfbmFtZSI6IlRvcmRldXJzIiwiZW1haWwiOiJrdG9yZGV1ckByZWRoYXQuY29tIn0.JfStOgLvgFUAlMb7aVfm-dWxd4wN5oqk377Q6oyDe55pM4zDiZ0f1yJfHsWL8RHeb3r0tj8DY_UAyAFkxAnjyWjq52d7h2EfJUPOs1p1P8Yeu5hDwOrA34Es2maN-ZbJCc4sOb7stGhxSCU15CfvPFIRR5tgSQ17-Mx-x4ZnK_fwpOK6DqQpNzZ0Krz3U1a-NH86XJ8dT8lC3o03YrdlcZx_-wv6-PehqNQa2Hb9vt1csX8QlL3PEyBVNPZXaaTHvyFYx0orGyjKA83Qq-LihbWBXzNjf_rIEfsPJYi-uQHIT_zjaOPYo2rXi7VTPJC2qRSxF2yaRGlihZHxkDzMOTITnaDeMhbx1zvRr-R9eXocEUzsU9j-Yx7h3WYCFjb8zdfXTBHV8SCaMdH1u9Eesa5gmHOoki8882RR85i1fjpBayFTS36y4S-yDebUYiukXOnw8mMMKy04NhVpFGfWtJ8--Jy4Ypndqqk_OS_PiWBsFFN6lMv5S6DZWVpjjE-CENHKn9ceA4MlerBBXLY02Xz9h0biiQUZrd-NLy11j4os124Mai1mmlNOLz993hw0gl-vKKno_bYOV8dEEmKtSLlSPVdW5X_0vBU0BtQuSEVctz_8zsRKHpT-YlDdmP0VDuzJjWM0YsGz2W0_tMuLG7NYS_Ia3vWAVuK--Uv5cAQ","expires_in":900,"refresh_expires_in":0,"refresh_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItNGVsY19WZE5fV3NPVVlmMkc0UXhyOEdjd0l4X0t0WFVDaXRhdExLbEx3In0.eyJqdGkiOiJhODZlZDczZS00MmE1LTQzYjUtYjJkYS1iMWM5NzU3OWUyZWMiLCJleHAiOjAsIm5iZiI6MCwiaWF0IjoxNTY3NDEwMDIxLCJpc3MiOiJodHRwczovL3Nzby5yZWRoYXQuY29tL2F1dGgvcmVhbG1zL3JlZGhhdC1leHRlcm5hbCIsImF1ZCI6InJoc20tYXBpIiwic3ViIjoiZjo1MjhkNzZmZi1mNzA4LTQzZWQtOGNkNS1mZTE2ZjRmZTBjZTY6cmhuLXN1cHBvcnQta3RvcmRldXIiLCJ0eXAiOiJPZmZsaW5lIiwiYXpwIjoicmhzbS1hcGkiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJmMGRiYjhkNC00ZTRlLTQ2NTQtODQ0Yy02ZjM3MDRjODQ0MjIiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsicG9ydGFsX21hbmFnZV9zdWJzY3JpcHRpb25zIiwib2ZmbGluZV9hY2Nlc3MiLCJjYW5kbGVwaW5fc3lzdGVtX2FjY2Vzc192aWV3X2VkaXRfYWxsIiwiYWRtaW46b3JnOmFsbCIsInBvcnRhbF9tYW5hZ2VfY2FzZXMiLCJwb3J0YWxfc3lzdGVtX21hbmFnZW1lbnQiLCJwb3J0YWxfZG93bmxvYWQiXX0sInJlc291cmNlX2FjY2VzcyI6e319.S_pmAWzQUc04f0uGHN9rRYd4sH1t4IPnEwCcOH1aBL9Qo4_EbXPWCrtnf84f1pfuKJTQwUS-DldY6eloyVEsGgnqkygBKh270bu_bNXCNAuLJigEMsYx_2VzdnwWLptWS2_FUaNwe7Tai8qXwd8F0ge0Zjoi3P15S_8z4Tp79uD-qKcvwz6NlPKCOZwEbwZqOkJDZ8JKTIK8O0jfqdtHMfaWwlXMXdvx3B70tTOtHjQGAsxZA2dPPvqVGuyMOMmC3bMaISReUbtDwsCV-eAZplDfDZthr4k4JbmG9Iwq1aATaF3aCwfpebcmoIZGHE4_RLZrXCZKapXVVvRxcOrJytxIZrbDHq6ozX7j-j1SE3kuexcSLvlodmfTlxwPX9g7aqJu2ZLno54NxQSgYO8lQqSvScFgLtbX5f_FUS0Iw6yRWWJy2o2fnvfGk83rt5UYTtIb8Xd1GXcpHf8Yl10nVy21BetSQY__VpahF_eZghBNxS689GJnwUqAwlu01pOlb26mmHaydHc3hqUsudZydRbaFfI7nR6gQP8lCtp6b0z5hgVHLG4ZJ7i4MmEL6C5G4xHUaUs6RZgJUSsc2DzLW0b7rSQj41JuvTmSgD8bMrnVokmkAbfvxjKGc7E8n2GyImO7JiKb3RA7_o0xOTRYDIa_Ns-lnigJkUlQZUzt7JI","token_type":"bearer","not-before-policy":0,"session_state":"f0dbb8d4-4e4e-4654-844c-6f3704c84422","scope":"offline_access"}%

access_token は、API 呼び出しを実行するために認可トークンとして設定/使用する必要があるトークンです。 

# token=`curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id=rhsm-api -d refresh_token=$offline_token | jsonValue access_token`

3. 利用できる Red Hat Subscription Management API へのアクセス

Red Hat は、Red Hat Subscription Management API の仕様を記述する Swagger ファイルを提供します。Swagger 仕様には、利用可能な API エンドポイント、入力パラメーター、想定される出力、考えられるエラー応答に関する情報が含まれます。swagger ファイルは、Postman や RESTlet と同様に REST クライアントにインポートでき、API 呼び出しのライブラリーを自動的にビルドします。

4. API エラーのトラブルシューティング

表1 API エラー

コード説明解決方法

400

BadRequest エラー

API 呼び出しを正しく入力し、再度検証。

401

認可されていない

新しい認可トークンを生成。

403

禁止されている

新しい認可トークンを生成。

404

見つからない

リソースが見つからないか、存在しない。

429

要求が多すぎる

要求頻度を減らす。

500

内部サーバーエラー

この問題は、Red Hat サイトで発生。1 分待ってから再要求。

4.1. エラー 403 のトラブルシューティング

403 エラーは認証されていないというエラーで、Red Hat Subscription Management API に使用している認証が失敗したことを意味します。試すことができる解決策は 2 つあります。

手順

  1. Red Hat Subscription Management ゲートウェイ経由で認証を行うには、API 呼び出しを入力する前に、認可ヘッダーに bearer のテキストが含まれるようにします。 

    curl -H "Authorization: Bearer <token>" <api_url>
  2. ヘッダーが正しい場合は、新しいトークンを作成します。更新トークンは 5 分間持続します。

4.2. エラー 429 のトラブルシューティング

エラー 429 は帯域制限エラーです。つまり、お使いのアカウントで 1 秒間で許容される要求の数を超えています。この制限は、1 つの Red Hat アカウントに含まれるすべてのユーザーに適用されます。

手順

レスポンスのヘッダーを抽出します。これには、* X-RateLimit-Limit: (許可される要求の合計/秒) * X-RateLimit-Remaining: (要求の数/残りの秒 (これは負の整数になります)) * X-RateLimit-Delay: (リクエスターが再試行するまで待機する秒数) が含まれます。

X-RateLimit-Limit 値に対する要求の帯域を調整し、X-RateLimit-Delay 時間が経過したら再度開始します。

第1章 付録 A 改訂履歴

表1.1 更新履歴

リビジョン日付作成者作業者

改訂 1.1-0

2019 年 9 月 19 日 (火)

オフライン、更新トークンの手順を変更

Anni Bond

改訂 1.0-1

2019 年 5 月 8 日 (水)

シークレットの取得場所に関する前提条件の詳細を追加

Anni Bond

バージョン 1.0-0

2019 年 5 月 3 日 (金)

初版作成

Anni Bond

法律上の通知

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.