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 Insights APIs, they must be authenticated.  Proactive Insights 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:

• In a web browser, navigate to to HP Developers portal at https://developers.hp.com.

• Click Login to login to HP Developers portal using your Proactive Insights 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.

Note: In order to prevent fraudulent transactions during the authentication process, the Proactive Insights 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 Insights 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

For E.U. customers

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

For E.U. customers

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 60 minutes lifespan.
• refresh_token - Refresh token to request new access token when the access token has expired.

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:

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

For E.U. customers

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=

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
}