Authenticating with OAuth 2.0

Back to top

HP recognizes that privacy is a fundamental human right and further recognizes the importance of privacy, security and data protection to our customers and partners worldwide. Whether you are our Customer or Partner, you can count on HP for the protection of your data across all of our operations. In order for your applications to access Proactive Management APIs, they must be authenticated.  Proactive Management leverages the industry standard OAuth 2.0 protocol for granting access, due to its simplicity and ease of implementation.

Follow these steps to enable your application to make Authenticated API calls using OAuth 2.0:

 

 

Step 1 — Configuring your application

To create an application:

  • Click Login to login to HP Developers portal using your Proactive Management login/password. If you do not yet have an account on HP Developers portal, click the Register link to create an account.
  • Expand the drop-down menu under your email address, and click My Apps.
  • Click Add a new App.
  • In the resulting page, Select Product Name as HP TechPulse Analytics, and fill in the below fields for the new app.

 

Field
Description
Required
Product Scope
Select Read under product scope
Yes
App Name
Name of the client application
Yes
App Unique Name
Unique identifier of the app, it is generated automatically
No
Redirect URI
redirect URI after it authenticates the client
Yes

 

Note: In order to prevent fraudulent transactions during the authentication process, the Proactive Management APis communicate with Redirect URLs that have been identified as trusted endpoints.  Ensure the Redirect URLs field for your application contains a valid callback URL to your server that is listening to complete your portion of the authentication workflow.

Note: HP recommends using HTTPS whenever possible and also to use absolute Redirect URLs (for example,. "https://example.com/auth/callback", and not "/auth/callback").

  • Click Create App. This creates a new application and puts the application request in Pending state until HP approves the application request. Click  My App to review the status of the new application request.
  • Once the new application request is approved by HP, an email is sent to the Proactive Management user. Navigate to  My App and the new application will be in Approved state.
  • Click on the approved application to get the API Key (Client ID) and API Secret (Client Secret) for this new application. .

Note: HP recommends to not share the Client Secret value with anyone; including posting it in support forums for help with your application.

 

⚠ Important: The Client Secret value associated with your Client ID will automatically expire after 365 days. Please record the start and end dates, so that you are aware of the current age of Client Secret value. If the Client Secret value is close to 365 days of life span, please reset the Client Secret value and update your application. For more information on resetting Client Secret value, please refer to Reset the Client Secret associated with your Client ID.

 

 

Step 2 — Request an Authorization Code

 

Once your application is properly configured, it's time to request an authorization code.  The authorization code is not the final token that you use to make calls to Analytics API.  It is used in the next step of the OAuth 2.0 flow to exchange for an actual access token.

 

Redirecting the User

To request an authorization code, you must direct the user's browser to OAuth 2.0 authorization endpoint.  Once the request is made, one of the following two situations will occur:

  • The browser will be redirected to HP DaaS's authorization screen. When the user completes the authorization process, the user is redirected to the URI provided in the redirect_uri query parameter.
  • If the session already exists then the authorization screen is by-passed and the user is immediately redirected to the URI provided in the redirect_uri query parameter.

 

For U.S. customers

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

 

For E.U. customers

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

 

Parameter
Description
Required
client_id
The "API Key" value generated when you registered your application.
Yes
redirect_uri
The URI your users will be sent back to after authorization.
This value must match one of the defined OAuth 2.0 Redirect URLs in your application configuration.
e.g. https://example.com/auth/callback
Yes
response_type
The value of this field should always be: "code"
Yes
scope
scope as "Read"
Yes
state
A string used to maintain state between the request and the redirect response. This is used to prevent CSRF.
e.g. state=DCEeFWf45A53sdfKef424
Yes

 

Sample call

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

 

The User Experience

Once redirected, the user will be presented with HP DAAS authentication page.

After authentication HP DaaS redirects the user to the location specified in the redirect_uri and returns an authorization code and state.

  • code — The OAuth 2.0 authorization code.

  • state — A value used to test for possible CSRF attacks.

The code is a value that you will exchange with HP DaaS for an actual OAuth 2.0 access token in the next step of the authentication process.  For security reasons, the authorization code has a very short lifespan and must be used within moments of receiving it - before it expires and you need to repeat all of the previous steps to request another.

Before you accept the authorization code, your application should ensure that the value returned in the state parameter matches the state value from your original authorization code request. This ensures that you are dealing with the real original user and not a malicious script that has somehow slipped into the middle of your authentication flow.  If the state values do not match, you are likely the victim of a CSRF attack and you should throw an HTTP 401 error code in response.

 

 

Step 3 — Exchange Authorization Code for an Access Token

 

The final step towards obtaining an Access Token is for your application to ask for one using the Authorization Code it just acquired. This is done by making the following "x-www-form-urlencoded" HTTP POST request:

 

For U.S. customers

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

 

For E.U. customers

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

 

Parameter
Description
Required
grant_type
The value of this field should always be: authorization_code
Yes
code
The authorization code you received from Step 2.
Yes
redirect_uri
The same 'redirect_uri' value that you passed in the previous step.
Yes
client_id
The "API Key" value generated Step 1.
Yes
client_secret
The "Secret Key" value generated in Step 1.
Yes

 

Sample call

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

 

Access Token Response

A successful Access Token request will return a JSON object containing the following fields:

  • access_token — The access token for the user.  This value must be kept secure, as per your agreement to the API Terms of Use.
  • expires_in — The number of seconds remaining, from the time it was requested, before the token will expire.  Currently, all access tokens are issued with a 30 minutes lifespan.
  • refresh_token - Refresh token to request new access token when the access token has expired.

 

The length of Access Tokens is ~30 characters. We recommend that you plan for your application stack to handle tokens with length of at least 100 characters in order to accommodate current and any future expansion plans. This applies to both Access Tokens as well as Refresh Tokens.

 

Access Token Lifetime

Access Tokens stay valid until the number of seconds returned in the expires_in field in the API response.  A user can go through the OAuth flow on multiple clients (browsers or devices) and simultaneously hold multiple valid access tokens.  

 

 

Step 4 — Make authorized requests

 

Once you've obtained an Access Token, you can start making authorized API requests on behalf of the user. This is accomplished by including an "Authorization" header in your HTTP call to HP TechPulse Analytics API.  Here is a sample HTTP request including the header value that includes the token:

 

Sample call

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

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

Connection: Keep-Alive

Authorization: Bearer 9vVLTv496kRmIAkfRwDvAUAr271T

 

Invalid Tokens

If you make an API call using an invalid token, you will receive a "401 Unauthorized" response back from the server.  A token could be invalid and in need of regeneration because:

  • It has expired.
  • A subsequent OAuth2 flow that generated a new access token. The previous token will be invalidated.

Since a predictable expiry time is not the only contributing factor to token invalidation, it is very important that you code your applications to properly handle an encounter with a 401 error by redirecting the user back to the start of the authorization workflow.

Note: In case of downstream failures in verification of the access token, you will receive either a 500 or 503 error response back.

 

 

Step 5 — Refresh your Access Tokens

 

To protect our member's data, HP DaaS does not generate excessively long-lived access tokens.  You should ensure your application is built to handle refreshing user tokens before they expire, to avoid having to unnecessarily send the users through the authorization process to re-gain access to a DaaS profile.

Refreshing a token

To refresh an Access Token,

  • The refresh token obtained from the Authorization Code flow can be used in Refresh Token flow to get a new access token. The Refresh Token flow does not involve end user interaction. 
  • Now submit a POST request to the /oauth/v1/token endpoint to exchange the refresh token for an access token.
  • HTTP Basic authentication is to be used while making this request along with the request header and body as explained below.

 

For U.S. customers

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

 

For E.U. customers

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

 

Parameter
Description
Required
grant_type
To refresh the token this value should be: refresh_token
Yes
refresh_token
The refresh token returned to you when authenticating originally
Yes

 

Authenticating with Basic Auth

For Refreshing the token you must use HTTP Basic Authentication, provide the API Key and Secret concatenated together with a : separating them, and encode that resulting string in base64.

Example Auth Header:

Authorization: Basic OTZDbml6gragegrmmWVHRnFHSjlRZ0FtQzRGRFE6TGdWTElrQXdCdG=


Sample call

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

 

Sample response

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

 

 

 

Step 6 - Understanding application permissions

Below are the roles that can access the HP TechPulse Analytics and HP TechPulse Incident Integration APIs.

  • Customer – IT Admin, Report Admin
  • MSP – Support Specialist, Support Admin
  • Partner – Partner Admin