Claim Mapping for SAML and OpenID (Preview)

When a user authenticates with HP Insights through an external identity provider (OpenID Connect or SAML), the identity provider sends a set of claims — pieces of information about the user such as their email address, display name, and username. HP Insights uses these claims to identify and provision users.

Claim Mapping allows administrators to control how the claims sent by the identity provider are mapped to the user attributes HP Insights uses internally. This is useful when the identity provider sends claims using non-standard names, or when you need to specify which claim should be used as the user’s email address.

For example, some organizations configure their identity provider to send the email address under a claim called mail or preferred_username rather than the standard email claim.

When to Use Claim Mapping

In most cases the default claim mapping works without any changes. You need to configure claim mapping when:

Your identity provider sends the email address under a non-standard claim name (e.g. mail, upn, preferred_username, or a custom name).
Your organization uses a different identifier as the primary user attribute than the standard claim name.
Authentication or user provisioning is failing and the identity provider is sending claims with unexpected names.

Note: When to leave defaults - If your identity provider sends standard claim names (email, sub, name, given_name, family_name), no changes are needed. The dialog instruction says: “Keep the default Source values if unsure.”

The Claim Mapping Dialog

The Claim Mapping dialog is accessible when configuring your identity provider. It shows a simple two-column form:

Target — the claim name HP Insights uses internally. These are fixed and always the same regardless of which authentication provider is configured.
Source — the claim name your identity provider sends. This is what you edit. The default Source values are pre-populated based on the authentication provider selected — OIDC providers use short names, SAML providers use full XML namespace URIs.

Source defaults depend on your authentication provider

The Claim Mapping dialog pre-populates the Source fields differently depending on which authentication provider tab is selected. If OpenID Connect is selected, Sources default to short names (e.g. email). If SAML is selected, Sources default to full XML namespace URIs (e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). The Target column is always the same. It represents HP Insights’s internal standard names, not the IdP’s.

The five Target claims are:

Target	What it represents
sub	The unique identifier for the user in the identity provider. Used as the primary key for user matching.
email	The user’s email address. Used for user identification and provisioning in HP Insights.
name	The user’s full display name.
given_name	The user’s first name.
family_name	The user’s last name / family name.

For each Target, enter the claim name that your identity provider uses in the Source field. If your identity provider uses the same name as the Target, leave the Source field as-is.

SAML and OIDC use different formats

OIDC providers use short claim names (e.g. email, sub). SAML providers use full XML namespace URIs (e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). HP Insights pre-populates the Source fields with the correct format for your provider type. You only need to change a Source value if your identity provider uses a different claim name than the default shown.

Navigating to Claim Mapping

Go to Account Settings > Settings > User Authentication Providers
Select the provider you are configuring (for example OpenID Connect or SAML2.0) under Provider Type.
Enter the required provider settings (for example Well-Known Endpoint / Client ID / Client Secret for OIDC, or the required SAML settings) if not already configured.
Click Advanced to open the Claim Mapping dialog.

Note: The Advanced (Claim Mapping) option is intended to be available only after a valid authentication provider configuration exists.

Configuring Claim Mapping

In the Claim Mapping dialog, review each Source field and update any that do not match the claim names your identity provider sends.

For each Target claim, check whether your identity provider sends that claim under the same name.
If the names differ, clear the Source field and type the claim name your identity provider uses.
Leave any Source fields unchanged if your identity provider already uses the standard name.
Click Close to dismiss the dialog, then click Save on the identity provider configuration page to apply your changes.

Note: Closing the Claim Mapping dialog does not save your changes. You must click Save on the identity provider configuration page after closing the dialog for the mapping to take effect.

Examples

Example 1 — OIDC: Email Sent as ‘mail’

Your OpenID Connect identity provider sends the email address under the claim name mail instead of the standard email. In the Claim Mapping dialog, change the Source for the email Target from email to mail.

Example 2 — UPN Used Instead of Email

Your organization wants to use the User Principal Name (upn) as the primary identifier rather than the email address claim. This applies to both OIDC and SAML configurations.

In the Claim Mapping dialog, change the Source for the email Target to upn (OIDC) or the full URI for UPN if using SAML.

Target	Source (OIDC)
email	upn

Target	Source (OIDC)
email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

Note: Claim names are case-sensitive. Ensure the Source value you enter exactly matches the claim name sent by your identity provider. If unsure, check the raw claims in your identity provider’s test or diagnostic tools.

Default Claim Sources by Provider Type

HP Insights pre-populates the Source fields with different default values depending on the identity provider type. OpenID Connect providers use short claim names. SAML providers use full XML namespace URIs. If the defaults match what your identity provider sends, no changes are needed.

OpenID Defaults

For OpenID Connect providers (including Microsoft, Google, and Okta OIDC), the default Source values use short claim names:

Target	Default Source
sub	sub
email	email
name	name
given_name	given_name
family_name	family_name

SAML Defaults

For SAML providers (including Entra ID / Azure AD SAML, Okta SAML, and Active Directory Federation Services), the default Source values use the full XML namespace URI format:

Target	Default Source
sub	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
given_name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
family_name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

If your SAML identity provider sends claims using different attribute names — for example, sending the email address as mail rather than the full URI — enter the name exactly as your identity provider sends it in the Source field. You can use either the short name (mail) or the full URI format, whichever matches what your identity provider actually sends.

If your environment uses non-standard claim names for any of the five Target claims, update the corresponding Source field in the Claim Mapping dialog.

How to test your configuration

After clicking Save, click Test on the provider configuration screen.
Sign in with a known test user from your IdP.
Confirm the user can sign in successfully and that key fields (especially email) are being populated correctly.

Common configuration tips

If users can authenticate but Pharos can’t identify or provision them correctly, check the email mapping first.
For OIDC, if your IdP uses a non-standard email field (like upn or mail), map Target email to that Source.
For SAML, use the attribute URI your IdP is sending (often WS-FED claim URIs), not a friendly display name.