--- title: Registering federated identities description: Register the Federated Identities that authenticate to Agent Privilege with signed tokens instead of stored credentials. component: privilege page_id: privilege:agent-privilege:configuration/federated-identities canonical_url: https://docs.pingidentity.com/privilege/agent-privilege/configuration/federated-identities.html llms_txt: https://docs.pingidentity.com/privilege/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: October 21, 2026 page_aliases: ["agent-privilege:configuration/non-human-identities.adoc"] section_ids: when-to-register-a-federated-identity: When to register a Federated Identity registering-a-federated-identity: Registering a Federated Identity before-you-begin: Before you begin step-1-start-the-registration: "Step 1: Start the registration" step-2-select-the-token-issuer-type: "Step 2: Select the token issuer type" option-1-kubernetes-serviceaccount-token: "Option 1: Kubernetes - ServiceAccount token" option-2-docker-host-self-signed-token: "Option 2: Docker host - self-signed token" option-3-github-actions-tokens: "Option 3: GitHub Actions tokens" option-4-spiffe-spire-jwt-svids: "Option 4: SPIFFE / SPIRE JWT-SVIDs" option-5-other-oidc-issuers: "Option 5: Other OIDC issuers" step-3-configure-verification-keys: "Step 3: Configure verification keys" step-4-configure-permissions-and-end-users: "Step 4: Configure permissions and end users" step-5-optional-advanced-configurations: "Step 5: Optional advanced configurations" step-6-register-and-validate-the-federated-identity: "Step 6: Register and validate the federated identity" result: Result: next-steps: Next steps managing-federated-identities: Managing federated identities reviewing-registered-federated-identities: Reviewing registered federated identities remediation-actions-for-federated-identities: Remediation actions for federated identities --- # Registering federated identities Federated Identities 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 *(tooltip: \
\

Information used to identify a subject for access purposes (for example, username and password). A credential can also be a certificate.\

\
)*. 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 self-hosted agents](../use-cases/self-hosted-agents.html). ## When to register a Federated Identity Register a Federated Identity 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](node-sensor.html). * 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. * Federated Identity custodians for registered agents in **Agent Registry**. During the registration process for agents, you can select a configured Federated Identity as the custodian. The Federated Identity's key acts as the identity for the agent and inherits its policy. Learn more in [Agent registry](agent-registry.html). ## Registering a Federated Identity You can register a Federated Identity on the **Federated Identities** page. During configuration, you identify the Federated Identity in PingOne Privilege, provide the details from a platform that issues tokens, define its permission scopes, and optionally configure advanced parameters. ### 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 > Federated Identities**. 2. Click **[icon: plus, set=fa]Register Identity**. 3. Enter a **Name** and **Description** to identify the federated identity. ### 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 *(tooltip: \
\

An open-source system for automating deployment and management of containerized applications.\

\
)* 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) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* issuer with published keys. On Kubernetes *(tooltip: \
\

An open-source system for automating deployment and management of containerized applications.\

\
)*, the token source is the service account. Learn more in [Deploying the node sensor](node-sensor.html). #### Option 1: Kubernetes - ServiceAccount token[]() 1. To get the **Issuer (iss)** URL, run the following command: ```bash $ 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::`, 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](node-sensor.html#node-sensor-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](node-sensor.html#node-sensor-register-host). 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) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* 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 federated identity 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](node-sensor.html). ### 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 federated identity 1. Ensure you fill in all the required configuration fields. 2. Click **Register**. ### Result: PingOne Privilege registers the identity under **Directory > Federated 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 federated identity you configured. ### Next steps After registering federated identities, you can assign them as custodians when registering an agent in Agent Registry. Learn more in [Agent registry](agent-registry.html). ## Managing federated identities The **Federated Identities** page shows the federated identities your directory knows about. ### Reviewing registered federated identities 1. In the PingOne Privilege admin console, go to **Directory > Federated Identities**. 2. Review the following information for your federated identities: * 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 federated identities In the list of registered federated identities, each item has buttons you can click for different remediation actions: ![The Disable, Edit, and Delete remediation actions available for a registered Federated Identity.](../_images/p1p_nhi_remediation_actions.png) * **Disable** or **Enable**: Disable or enable a federated identity. * **Edit**: Update the configuration of the federated identity. * **Delete**: Permanently delete the registered federated identity in PingOne Privilege.