Authenticating with OAuth 2.0

トップに戻る

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

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

 

 

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

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

  • [Login] (ログイン) をクリックし、プロアクティブ管理のログイン/パスワードを使用して、HP Developersポータルにログインします。HP Developersポータルのアカウントをまだお持ちでない場合は、[Register] (登録) リンクをクリックして、アカウントを作成します。
  • メールアドレスの下にあるドロップダウンメニューを展開し、[My Apps] (マイアプリ) をクリックします。
  • [Add a new App] (新しいアプリを追加) をクリックします。
  • これによって表示されるページで、[Product Name] (製品名) に「HP TechPulse Analytics」を選択し、新しいアプリの以下のフィールドに入力します。

 

フィールド
説明
必須
Product Scope (製品範囲)
[Product Scope] で [Read] (読み取り) を選択
はい
App Name (アプリ名)
クライアントアプリケーションの名前
はい
App Unique Name (アプリの一意の名前)
アプリの一意の識別子 (自動的に生成されます)
いいえ
Redirect URI (リダイレクトURI)
クライアントを認証した後のリダイレクトURI
はい

 

: 認証プロセスでの不正トランザクションを防ぐため、プロアクティブ管理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に直ちにリダイレクトされます。

 

米国のお客様

GET https://daas.api.hp.com/oauth/v1/authorize

 

EUのお客様

GET https://eu.daas.api.hp.com/oauth/v1/authorize

 

パラメーター
説明
必須
client_id
アプリケーションを登録した際に生成された「APIキー」値。
はい
redirect_uri
承認後にユーザーがリダイレクトされるURI。
この値は、アプリケーションの構成で定義されたOAuth 2.0のリダイレクトURLのいずれかと一致する必要があります。
例: https://example.com/auth/callback
はい
response_type
このフィールドの値は常に「code」です。
はい
scope
[Read] の範囲
はい
state
リクエストを行ってから、リダイレクトのレスポンスがあるまでのステータスを保持するために使用される文字列。これは、CSRFを防ぐために使用されます。
例: state=DCEeFWf45A53sdfKef424
はい

 

呼び出しのサンプル

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リクエストを行います。

 

米国のお客様

POST https://daas.api.hp.com/oauth/v1/token

 

EUのお客様

GET https://daas.api.hp.com/oauth/v1/token

 

パラメーター
説明
必須
grant_type
このフィールドの値は常にauthorization_codeです。
はい
code
ステップ2で受け取った承認コード。
はい
redirect_uri
前のステップで渡したものと同じ「redirect_uri」の値。
はい
client_id
ステップ1で生成された「APIキー」値。
はい
client_secret
ステップ1で生成された「シークレットキー」値。
はい

 

呼び出しのサンプル

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 — アクセストークンの有効期限が切れた場合に、新しいアクセストークンをリクエストするための更新トークン。

 

アクセストークンの長さは約30文字です。弊社では、現在および今後の拡張プランに対応するため、100文字以上の長さのトークンを処理できるようにアプリケーションスタックをプランニングすることを推奨しています。これは、アクセストークンと更新トークンの両方に適用されます。

 

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

アクセストークンは、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認証が使用され、リクエストのヘッダーと本文は以下のようになります。

 

米国のお客様

POST https://daas.api.hp.com/oauth/v1/token

 

EUのお客様

GET https://daas.api.hp.com/oauth/v1/token

 

パラメーター
説明
必須
grant_type
トークンを更新するには、この値はrefresh_tokenにする必要があります。
はい
refresh_token
当初の認証時にお客様に返された更新トークン。
はい

 

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
}

 

 

 

ステップ6 - アプリケーションの権限を理解する

HP TechPulse AnalyticsおよびHP TechPulse Incident IntegrationのAPIにアクセスできる役割は以下のとおりです。

  • お客様 – IT管理者、レポート管理者
  • MSP – サポートスペシャリスト、サポート管理者
  • パートナー様 – パートナー管理者