PingOne Privilege

Registering non-human identities

Non-Human Identities (NHIs) are workloads that authenticate to PingOne Privilege with a signed token issued by a trusted platform, workload identity system, or host-held signing key instead of a stored credential. Registration tells PingOne Privilege which issuer to trust, which subject to expect from the workload, and what the identity is allowed to do.

For the PingOne Privilege node sensor, registering its identity is what enables the sensor to authenticate and report the AI workloads it discovers. Learn more in Discover and manage NHI agents.

When to register an NHI

Register an NHI when you onboard a workload that authenticates to PingOne Privilege with a signed token. The most common cases are:

  • The PingOne Privilege node sensor. Register the sensor’s identity before you deploy the sensor, so it can authenticate its reports. Learn more in Deploying the node sensor.

  • AI workloads whose findings you want to associate with an identity, or match in identity-based policy. Registration is optional for discovery: the sensor reports workloads whether their identities are registered.

  • NHI custodians for registered agents in Agent Registry. During the registration process for agents, you can select a configured NHI as the custodian. The NHI’s key acts as the identity for the agent and inherits its policy. Learn more in Agent registry.

Registering an NHI

You can register an NHI on the Non-Human Identities page. During configuration, you identify the NHI in PingOne Privilege, provide the details from a platform that issues tokens, define its permission scopes, and optionally configure advanced parameters for the NHI.

Before you begin

Ensure you have the following:

  • The details of the platform that issues the workload’s tokens, such as its issuer URL and the subject its tokens carry.

  • The verification keys the platform publishes, or the URL they are published at.

Step 1: Start the registration

  1. In the PingOne Privilege admin console, go to Directory > Non-Human Identities.

  2. Click Register Identity.

  3. Enter a Name and Description to identify the NHI.

Step 2: Select the token issuer type

In the Token issuer type list, select the platform that mints the workload’s tokens. PingOne Privilege accepts signed tokens from the following sources:

  • Kubernetes service-account tokens.

  • Docker host self-signed tokens.

  • GitHub Actions and GitLab CI/CD job tokens.

  • SPIFFE/SPIRE JWT-SVIDs.

  • Tokens from any OpenID Connect (OIDC) issuer with published keys.

On Kubernetes, the token source is the service account. Learn more in Deploying the node sensor.

Option 1: Kubernetes - ServiceAccount token

  1. To get the Issuer (iss) URL, run the following command:

    $ kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

  2. Choose the ServiceAccount the tokens are minted for:

    • A new service account, which the deployment creates. When you register the node sensor’s identity, the Helm chart creates it.

    • An existing service account, entering the namespace and serviceaccount exactly as they exist in the cluster.

      The resulting subject, system:serviceaccount:<namespace>:<service-account>, must match the deployed namespace and service account exactly. PingOne Privilege refuses a mismatch rather than mis-attributing it.

      Decide the namespace and service-account name before you register: the deployment must use the same values. For the node sensor, the Helm installation names them. Learn more in Deploying the sensor on Kubernetes.

Option 2: Docker host - self-signed token

  1. On the Docker host, create the signing key and generate the registration values:

    • For the node sensor, run the -mint-jwks command in Registering the host identity. The command returns the Issuer, Subject, and JWKS values to use for registration.

    • For another workload, obtain the public half of the host’s signing key and the issuer and subject values from the tooling that mints the host’s tokens.

  2. Enter the Issuer (iss), Subject (sub), and JWKS URL generated from the host key.

Option 3: GitHub Actions tokens

  1. Enter the Issuer (iss) for GitHub Actions.

  2. Provide a Subject (sub).

    The subject varies by trigger, for example: :ref:refs/heads/main, :environment:production, :pull_request.

Option 4: SPIFFE / SPIRE JWT-SVIDs

  1. Enter the required platform information:

    • Issuer (iss): Your SPIRE server’s configured JSON Web Token (JWT) issuer.

    • Subject (sub): The SPIFFE ID of the workload.

Option 5: Other OIDC issuers

  1. Enter the required platform information:

    • Issuer (iss): Decode one of your tokens and copy its iss claim exactly.

    • Subject (sub): The sub claim your tokens carry, matched exactly.

Step 3: Configure verification keys

For every token source, provide the keys PingOne Privilege uses to verify the token’s signature. Click one of the following options for the Key source:

  • Fetch from URL: Provide the JWKS URL published by your identity platform, such as the keys your managed Kubernetes cluster publishes.

  • Paste keys: Paste the full JWK Set JSON. Only asymmetric public keys (RSA/EC/OKP) are accepted.

  • URL + Pinned Fallback: Provide the JWKS URL as well as the Pinned JWKS JSON.

Step 4: Configure permissions and end users

  1. To configure what the NHI can reach, select any of the following permissions:

    • shadowai:write: Report discovered AI workloads (agents, LLMs, and MCP servers).

    • policy:read: Fetch enforcement policy.

    • llm: Call LLM providers through the AI gateway, as an access key custodian.

    • mcp: Reach MCP tool servers, as an access key custodian.

    • a2a: Reach peer agents over HTTP, as an access key custodian.

      At least one permission is required. Grant permissions for what the workload is for. For example, an identity that only reports discovery findings needs only the shadowai:write permission.

  2. In the End user in a presented token list, select one of the following options:

    • None - the identity is the only principal

    • Opaque - record the end user, never look them up. For this option, you must provide an End-user claim formatted as a dotted path of the claim naming the end user, such as email or act.sub. Leave empty to use the default sub, which is the workload’s own subject.

If you’re registering the identity for the node sensor, the sensor is the only principal: select None. Grant only shadowai:write unless the sensor also fetches enforcement policy. Learn more in Deploying the node sensor.

Step 5: Optional advanced configurations

  1. (Optional) Expand Advanced to configure the following additional fields:

    • Expires: The identity stops authenticating after this date and time. Leave empty for no expiry.

    • Allow any subject: Click the checkbox to let one identity cover every workload matching the subject pattern.

    • Max token lifetime (seconds): Rejects tokens that exceed this lifetime. The default 0 entry uses the controller default of 3600 seconds.

    • Required claims: Click Add claim to add a claim that is checked after the signature.

Step 6: Register and validate the NHI

  1. Ensure you fill in all the required configuration fields.

  2. Click Register.

    Result:

    PingOne Privilege registers the identity under Directory > Non-Human Identities and generates an Audience for it.

  3. Copy the audience. You supply it when you configure the workload to authenticate:

    • For the node sensor on Kubernetes, the audience is the Helm installation’s auth.audience value.

    • For the node sensor on Docker, the audience is the sensor container’s -mint-audience flag.

In the list of registered identities, you should see the NHI you configured.

Next steps

After registering NHIs, you can assign them as custodians when registering an agent in Agent Registry. Learn more in Agent registry.

Managing NHIs

The Non-Human Identities page shows the NHIs your directory knows about.

Reviewing registered NHIs

  1. In the PingOne Privilege admin console, go to Directory > Non-Human Identities.

  2. Review the following information for your NHIs:

    • The identity name, its owning platform, and its subject.

    • Any end user claims and their status.

    • The scopes granted to the identity.

    • Whether its status is currently Enabled or Disabled.

Remediation actions for NHIs

In the list of registered NHIs, each item has buttons you can click for different remediation actions:

The Disable, Edit, and Delete remediation actions available for a registered NHI.

  • Disable or Enable: Disable or enable an NHI.

  • Edit: Update the configuration of the NHI.

  • Delete: Permanently delete the registered NHI in PingOne Privilege.