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」を選択し、新しいアプリの以下のフィールドに入力します。
フィールド
|
説明
|
必須
|
---|---|---|
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 — アクセストークンの有効期限が切れた場合に、新しいアクセストークンをリクエストするための更新トークン。
アクセストークンの有効期限
アクセストークンは、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 – サポートスペシャリスト、サポート管理者
- パートナー様 – パートナー管理者