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) connection can use an incoming ID to specify the Subject value in its authentication requests.
  • An OpenID Connect 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 OpenID Connect 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 OpenID Connect authentication request.

  1. Go to Authentication > Policies > Policies. On the Policies window, select the applicable authentication policy.
  2. On the Policy tab, locate the authentication source that you need to provide an incoming user ID 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.
    Note:

    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.
    Note: If you have selected Context in the previous step, select Requested User to derive the incoming user ID from the Subject element, the username parameter, or the login_hint parameter in the SAML 2.0, WS-Federation, or OpenID Connect authentication request, respectively.

    During runtime, if a request does not originate from a SAML 2.0, WS-Federation, or OpenID Connect authentication request, or if the SAML 2.0, WS-Federation, or OpenID Connect authentication request does not 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 User ID Authenticated to add a parameter that indicates whether the mapped user ID has been authenticated by the authentication source and therefore can be trusted by the current adapter. The name of this Boolean parameter is IN_PARAMETER_NAME_USERID_AUTHENTICATED.
    Note: If the login_hint is passed as the user ID, the value of IN_PARAMETER_NAME_USERID_AUTHENTICATED will be FALSE.
  6. On the Incoming User ID dialog, click Done.
  7. On the Policy tab, continue with the rest of your policy configuration.