--- title: Specifying incoming user IDs description: Configure authentication policies to use incoming user identifiers at request time. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_specify_incoming_user_ids canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_specify_incoming_user_ids.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: August 29, 2025 section_ids: about-this-task: About this task steps: Steps result: Result: --- # Specifying incoming user IDs You can configure authentication policies to use incoming user identifiers at request time. ## About this task Some authentication sources make use of a user identifier at request time. For example: * The PingID Adapter requires a user ID to be passed in from an earlier authentication step to perform multi-factor authentication. * The HTML Form Adapter and custom IdP adapters developed using the `IdpAuthenticationAdapterV2` interface from the PingFederate SDK can pre-populate username information based on an incoming user ID. * A SAML 2.0 identity provider (IdP) *(tooltip: \
\

A service that manages identity information and provides authentication services to relying clients or SPs within a federated or distributed network.\

\
)* connection can use an incoming ID to specify the `Subject` value in its authentication requests. * An 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.\

\
)* IdP connection can leverage an incoming user ID to specify a `login_hint` parameter value in its OAuth authorization requests. To address these use cases, specify the source and the attribute of the incoming user ID in an authentication policy. You can select any IdP adapter instance or IdP connection that has been placed in the same policy path ahead of the current authentication source to be the source of the incoming user ID. After you select a source, choose an attribute from the selected IdP adapter contract or IdP connection. At runtime, the attribute value becomes the incoming user ID. Alternatively, you can use the originating SAML 2.0, WS-Federation, or OIDC authentication request as the source. In this scenario, the incoming user ID is derived from the `Subject` element in a SAML 2.0 authentication request, the `username` parameter in a WS-Federation authentication request, or the `login_hint` parameter in an OIDC authentication request. ## Steps 1. Go to **Authentication > Policies > Policies**. On the **Policies** window, select the applicable authentication policy. 2. On the **Policy** tab, locate the authentication source you need to provide an incoming user ID for and then click **Options** underneath it. 3. On the **Incoming User ID** dialog, select the source of the incoming user ID from the **Source** list. | | | | - | ----------------------------------------------------------------------- | | | Fragments without an output contract will not be available as a source. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you want the policy engine to derive the incoming user ID from the originating SAML 2.0 or WS-Federation authentication request, select **Context**. | 4. Select an attribute of the incoming user ID from the **Attribute** list. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you selected **Context** in the previous step, select **Requested User** to derive the incoming user ID from the `Subject` element in the SAML 2.0 authentication request, or the `username` parameter in the WS-Federation authentication request.If the `login_hint` parameter is provided for the OIDC authentication request, then it will be used as the incoming user ID regardless of this configuration. | ### Result: During runtime, if a request doesn't originate from a SAML 2.0, WS-Federation, or OIDC authentication request, or if the SAML 2.0, WS-Federation, or OIDC authentication request doesn't include the optional `Subject` element, `username` parameter, or `login_hint` parameter, the policy engine advances without providing username information to the authentication source. 5. (Optional) Select the **User ID Authenticated** checkbox to signal to the adapter that the value of the incoming user ID has been authenticated by a previous authentication source. Adapters can choose to enable certain functionality, such as registering new MFA devices, only when the user ID value has previously been authenticated. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------- | | | Don't enable **User ID Authenticated** for a self-service password reset authentication policy. Doing so can create a security vulnerability. | 6. On the **Incoming User ID** dialog, click **Done**. 7. On the **Policy** tab, continue with the rest of your policy configuration.