External Card Integration (Preview Mode)

Note: The External Card integration feature is in “Preview Mode” only. You can request access to this feature by emailing HP.

HP Insights supports integration with third-party card systems. When External Card Integration is configured, printers retrieve and validate card details directly from your organization's identity provider rather than from HP Insights.

HP Insights performs real-time queries to third-party APIs whenever card information is needed. This feature is available from HP Insights 4.1.

Key Behaviors and Limitations

• External Card Integration works with OpenID Connect or SAML authentication providers only. Internal Authentication and Active Directory are not supported.

• When External Card Integration is enabled, any previously stored card data in HP Insights will no longer be used.

• Only one card system can be active at a time. You cannot use HP Insights card management and External Card Integration at the same time.

• This feature is only available on printers connected via Cloud Site Service.

How it works

User Workflow

1. A user swipes their card at a secure printer or enters their card details, the contents of which are encrypted.

2. The encrypted data is sent to HP Insights for verification to generate a temporary access token.

3. HP Insights sends an authentication request to the third-party user identification provider.

4. The third-party provider decrypts, verifies, and identifies the user.

Authentication Methods

External Card Integration secures requests to the Endpoint URL using HTTP signature validation by default. If your external endpoint also requires OAuth bearer token authentication, you can configure additional OAuth credentials.

Method	When to use	Requirements
HTTP signature validation	Always applied. This is the baseline security mechanism	Endpoint URL
OAuth bearer token	When your external endpoint requires bearer token authentication on top of HTTP signature	Endpoint URL Client ID, Client Secret, Client Scopes (can be empty), and Token Endpoint

Configure External Card Integration

1. Navigate to Analysis > API in the web console.

2. In the External Card Integration section, enter the required settings. Refer to the Settings Reference below.

3. Toggle Allow card authentication via external API to ON.

4. Use the Test API Configuration section to verify the integration.

Note: An Endpoint URL must be provided before the toggle can be activated.

Settings Reference

General Settings

Setting	Description
Allow card authentication via external API	This allows card authentication through an external API. To enable it, toggle the switch ON. An Endpoint URL must be provided before activation. Without a valid Endpoint URL, the feature cannot be enabled.
Endpoint URL	Add the API endpoint URL for the third-party card system. HP Insights will use this address to send requests to check user badges or cards using the customer’s own authentication system.

HTTP Signature Validation

Setting	Description
Certificate URL	This certificate is used to establish secure communication between HP Insights and the third-party card system, ensuring the data exchanged is signed or encrypted for security. This value is specific to your environment and is provided by HP. Do not modify this value.

OAuth bearer token authentication (Optional)

These settings are required when the Endpoint URL requires bearer token authentication.

Setting	Description
Client Id	A public identifier that uniquely identifies HP Insights to your OAuth authorization server. Think of it as a "username" for the application. It's issued by your identity provider (e.g. Azure AD, Okta) when you register HP Insights as a client application.
Client Secret	The confidential password paired with the Client ID. It proves to your OAuth server that the token request is genuinely coming from HP Insights and not an imposter. It's issued alongside the Client ID when HP Insights is registered with your identity provider, and must be kept secure.
Client Scopes	A space-separated list of permissions HP Insights is requesting when it asks for a token. Scopes tell the OAuth server what the token should be allowed to do (e.g. read user data, call a specific API). Your identity provider defines the valid scopes for your environment. This field can be left empty if your OAuth server doesn't require specific scopes, but the field itself must exist (it can't be null).
Token Endpoint	The direct URL of your OAuth token endpoint (for example: https://example.com/tokens).

 

Note: Starting with HP Insights 4.4, using OAuth bearer tokens for authentication is supported. This means HP Insights can now fetch a secure token from your organization's OAuth server and use it to authenticate requests.

Testing API Configuration

Before rolling out to users, validate the integration end-to-end:

In the Test API Configuration section, enter a card number that exists in the third-party system. Click the Test button.

• If the card ID exists, the integration will respond successfully.

• If the card ID does not exist, the system will return the following error message:

The external service reported an error: card_not_found