Authenticating with OAuth 2.0

トップに戻る

HPでは、プライバシーが基本的人権であること、および世界中のお客様およびパートナー様にとってのプライバシー、セキュリティ、データ保護の必要性を認識しています。弊社のお客様またはパートナー様は、HPのすべての事業にわたって、皆様のデータが保護されることを信頼していただけます。お客様のアプリケーションからプロアクティブ管理APIにアクセスするには、認証が必要になります。プロアクティブ管理では、シンプルかつ実装しやすい、業界標準のOAuth 2.0プロトコルを活用してアクセスを付与します。

以下の手順に沿って、OAuth 2.0を使用し、アプリケーションで認証されたAPI呼び出しを実行できるようにしてください。

ステップ1 — アプリケーションを構成する

アプリケーションを作成するには:

• Webブラウザで、HP Developersポータル (https://developers.hp.com) に移動します。

• [Login] (ログイン) をクリックし、プロアクティブ管理のログイン/パスワードを使用して、HP Developersポータルにログインします。HP Developersポータルのアカウントをまだお持ちでない場合は、[Register] (登録) リンクをクリックして、アカウントを作成します。

• メールアドレスの下にあるドロップダウンメニューを展開し、[My Apps] (マイアプリ) をクリックします。

• [Add a new App] (新しいアプリを追加) をクリックします。

• これによって表示されるページで、[Product Name] (製品名) に「HP TechPulse Analytics」を選択し、新しいアプリの以下のフィールドに入力します。

注: 認証プロセスでの不正トランザクションを防ぐため、プロアクティブ管理APIは、信頼されるエンドポイントとして特定されたリダイレクトURLと通信します。アプリケーションの [Redirect URLs] (リダイレクトURL) フィールドには、認証ワークフローの処理を完了するためにリスンするサーバーへの、有効なコールバックURLを必ず入力してください。

注: HPでは、可能な限りHTTPSを使用し、絶対的なリダイレクトURL (例: 「/auth/callback」ではなく、「https://example.com/auth/callback」) を使用することを推奨しています。

• [Create App] (アプリを作成) をクリックします。これで、新しいアプリケーションが作成され、HPがアプリケーションリクエストを承認するまで、アプリケーションリクエストのステータスが「Pending」(保留中) になります。新しいアプリケーションリクエストのステータスを確認するには、[My App] (マイアプリ) をクリックしてください。

• HPが新しいアプリケーションリクエストを承認すると、プロアクティブ管理ユーザーにメールが送信されます。[My App] (マイアプリ) に移動すると、新しいアプリケーションのステータスが [Approved] (承認済み) になっています。

• 承認済みのアプリケーションをクリックして、この新しいアプリケーションのAPIキー (クライアントID) とAPIシークレット (クライアントシークレット) を取得します 。

注: HPでは、クライアントシークレット値を他者と共有しないことを推奨します。これには、アプリケーションについて支援を受けるために、サポートフォーラムで投稿することなどが含まれます。

⚠重要: クライアントIDに関連付けられたクライアントシークレット値は、365日後に自動的に有効期限が切れます。 開始日と終了日を記録して、クライアントシークレット値の経過日数を確認できるようにしてください。クライアントシークレット値の365日の有効期限が近づいたら、クライアントシークレット値をリセットして、アプリケーションを更新してください。クライアントシークレット値のリセットに関する詳細については、次を参照してください：「クライアントIDに関連付けられたクライアントシークレットをリセットする」

ステップ2 — 承認コードをリクエストする

アプリケーションを適切に構成できたら、承認コードをリクエストします。承認コードは、Analytics APIに呼び出しを行うために使用する最終的なトークンではありません。これは、OAuth 2.0フローの次のステップで、実際のアクセストークンと交換するために使用されます。

ユーザーのリダイレクト

承認コードをリクエストするには、ユーザーのブラウザをOAuth 2.0承認エンドポイントに誘導する必要があります。リクエストが完了したら、以下の2つの状況のうち、いずれかが発生します。

• ブラウザがHP DaaSの承認画面にリダイレクトされる。ユーザーが承認プロセスを完了すると、「redirect_uri」クエリパラメーターで指定されたURIにリダイレクトされます。

• このセッションがすでに存在する場合には、承認画面がバイパスされ、ユーザーは「redirect_uri」クエリパラメーターで指定されたURIに直ちにリダイレクトされます。

米国のお客様

EUのお客様

https://daas.api.hp.com/oauth/v1/authorize?client_id=VkGp3021j8m3l6vwz6AEr08lDxrAHdxi&redirect_uri=http://localhost&response_type=code&scope=Read&state=DCEeFWf45A53sdfKef424

ユーザーエクスペリエンス

リダイレクトされたユーザーには、[HP DAAS authentication] (HP DAAS認証) ページが表示されます。

認証後、HP DaaSはredirect_uriで指定された場所にユーザーをリダイレクトし、承認コードとステータスを返します。

• code — OAuth 2.0承認コード。

• state — 可能性のあるCSRF攻撃についてテストするために使用される値。

このコードは、認証プロセスの次のステップで、HP DaaSで実際のOAuth 2.0アクセストークンと交換するために使用する値です。セキュリティ上の理由から、承認コードの有効期限は非常に短く設定されており、受け取ってからすぐに使用する必要があります。有効期限が切れた場合には、これまでのステップすべてを繰り返し、別のコードをリクエストする必要があります。

承認コードを許可する前に、アプリケーションでは、stateパラメーターで返された値が、元の承認コードリクエストのstate値と一致することを確認する必要があります。これにより、認証フローに何らかの方法で紛れ込んだ悪意のあるスクリプトではなく、実際の元のユーザーとやり取りしていることを確認できます。state値が一致しない場合は、CSRF攻撃を受けている可能性があり、レスポンスでHTTP 401エラーコードを表示する必要があります。

ステップ3 — 承認コードをアクセストークンに交換する

アクセストークンを取得する最後のステップは、先程取得した承認コードを使用して、アプリケーションでアクセストークンを要求することです。このためには、以下の「x-www-form-urlencoded」HTTP POSTリクエストを行います。

米国のお客様

EUのお客様

POST: /oauth/v1/token HTTP/1.1

Host: https://daas.api.hp.com

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=cF5faYzL&redirect_uri=http://localhost&client_id=123456789&client_secret=shhdonottell

アクセストークンのレスポンス

アクセストークンのリクエストに成功すると、以下のフィールドが含まれたJSONオブジェクトが返されます。

• access_token — ユーザーのアクセストークン。この値は、お客様が同意するAPI利用規約に基づき、安全に保管してください。
• expires_in — トークンがリクエストされた時点から、有効期限が切れるまでの残り秒数。現在、すべてのアクセストークンの有効期限は30分です。
• refresh_token — アクセストークンの有効期限が切れた場合に、新しいアクセストークンをリクエストするための更新トークン。

アクセストークンの有効期限

アクセストークンは、APIレスポンスのexpires_inフィールドで返された秒数の間、有効です。ユーザーは複数のクライアント (ブラウザやデバイス) でOAuthフローを実行し、複数の有効なアクセストークンを同時に保持することができます。

ステップ4 — 承認されたリクエストを行う

アクセストークンを取得すると、ユーザーに代わって、承認されたAPIリクエストを行うことができるようになります。このためには、HP TechPulse Analytics APIへのHTTP呼び出しに「Authorization」ヘッダーを含めます。以下は、トークンを含んだヘッダー値が記載されたサンプルのHTTPリクエストです。

POST: /analytics/v1/reports/hwinv/deviceType/type/graph HTTP/1.1

Host: https://daas.api.hp.com

Connection: Keep-Alive

Authorization: Bearer 9vVLTv496kRmIAkfRwDvAUAr271T

無効なトークン

無効なトークンを使用してAPI呼び出しを行うと、サーバーから「401 Unauthorized」のレスポンスが返されます。以下の場合には、トークンが無効になり、再度生成する必要があります。

• 有効期限が切れた。
• OAuth2フローが再度実行され、新しいアクセストークンが生成された。これにより、以前のトークンは無効になります。

有効期限が予測可能であるため、トークンが無効になる時期は把握しやすくなりますが、401エラーが表示された場合に、ユーザーを承認ワークフローの最初にリダイレクトすることで適切に処理できるよう、アプリケーションをコーディングすることが非常に重要です。

注: アクセストークンの検証プロセスの下流で障害が発生した場合には、500または503エラーのレスポンスが返されます。

ステップ5 — アクセストークンを更新する

弊社のメンバーのデータを保護するため、HP DaaSでは長期間有効なアクセストークンは生成しません。DaaSプロファイルへのアクセスを再取得するために、不必要にユーザーを承認プロセスに転送することを避けるべく、ユーザーのトークンの有効期限が切れる前に更新を処理できるように、アプリケーションを構築するようにしてください。

トークンを更新する

アクセストークンを更新するには

• 承認コードのフローで取得した更新トークンを、更新トークンのフローで使用して、新しいアクセストークンを取得することができます。更新トークンのフローでは、エンドユーザーの操作は必要ありません。
• POSTリクエストを/oauth/v1/tokenエンドポイントに送信して、更新トークンをアクセストークンと交換します。
• このリクエストを行う際には、HTTP Basic認証が使用され、リクエストのヘッダーと本文は以下のようになります。

米国のお客様

EUのお客様

Basic認証による認証

トークンの更新には、HTTP Basic認証を使用する必要があります。その際には、APIキーとシークレットを:で区切って入力し、この文字列をBase64でエンコードします。

認証ヘッダーの例:

Authorization: Basic OTZDbml6gragegrmmWVHRnFHSjlRZ0FtQzRGRFE6TGdWTElrQXdCdG=

POST /oauth/v1/token HTTP/1.1
Accept: application/json
Authorization: Basic OTZDbml6ZUJoTXdQR1RXXXVHRnFFE6TGdWTElrQXdCdGFMenEzVFZqNkFkUUR0a0xWRXFNcnQ=
Content-Type: application/x-www-form-urlencoded
Host: daas.api.hp.com

grant_type=refresh_token&refresh_token=HZQlf0Bxc2gaergkQUYVjtoCaCwsTp

{
    "access_token": "9vVLTv496kRmIAkfRwDvAUAr271T",
    "scope": "Read",
    "token_type": "Bearer",
    "refresh_token": "D9HhoBelDMPizflefEMRNztIlrnEflUP",
    "expires_in": 1799999
}