PingFederate Server

Troubleshooting authentication policy issues

Authentication policies, an optional configuration in PingFederate, help implement complex authentication requirements. Having a complex policy or multiple policies can result in unintended runtime behaviors. The org.sourceid.util.log.PolicyTreeLogger logger makes it easier to troubleshoot such issues.

About this task

Identify and resolve authentication policy issues.

Steps

  1. Enable debug messages for the org.sourceid.util.log.PolicyTreeLogger class.

    If you have enabled debug messages for the org.sourceid logger, you have already enabled debug messages for the org.sourceid.util.log.PolicyTreeLogger class. Skip to step 3.

    1. Edit the <pf_install>/pingfederate/server/default/conf/log4j2.xml file.

    2. Look for Limit categories inside the Loggers element, as shown in bold in the following example.

      ...
<Loggers>

    <!-- ================ -->
    <!-- Limit categories -->
    <!-- ================ -->

    ...
     <!--
    <Logger name="org.sourceid.util.log.PolicyTreeLogger" level="DEBUG" />
     -->
    ...
</Loggers>
...

    3. Uncomment the org.sourceid.util.log.PolicyTreeLogger logger, as shown in the following example. Note that the <!-- and -→ markers have been removed.

      Example:

      ...
<Loggers>

    <!-- ================ -->
    <!-- Limit categories -->
    <!-- ================ -->

    ...

    <Logger name="org.sourceid.util.log.PolicyTreeLogger" level="DEBUG" />

    ...
</Loggers>
...

    This change is activated within a minute. No restart of PingFederate is required.

  2. Save any changes made.

    For a clustered PingFederate environment, repeat these steps on each applicable node.

  3. Repeat the request that demonstrates the authentication policy issue.

    It is most useful to initiate this request in a browser without any cookies from prior sessions.

  4. After you have replicated the issue, correlate server log messages using the PF cookie and tracking ID values. For more information, see Troubleshooting runtime errors.

    Look for DEBUG messages from the org.sourceid.util.log.PolicyTreeLogger class.

    Example:

    For example, suppose the tracking ID value is wXzQbS8MfHG40wpsQPiREIenJjc for a given request. The following server log messages demonstrate the authentication flow.

    DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Selector | generalClients | Yes
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Authn Source | idFirst
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Authn Source | idFirst
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Authn Source | idFirst | Rule | Alpha
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Authn Source | idFirst | Alpha
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Authn Source | https://sso.alpha.local:8031
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Authn Policy Tree setting User ID from attribute 'subject' from Source type 'Adapter' and source ID 'idFirst'
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Authn Source | https://sso.alpha.local:8031 | Success
DEBUG [org.sourceid.util.log.PolicyTreeLogger] Policy 'General clients policy' | Authentication Policy Contract | APC | Finished

    For readability, this sample ignores the time stamp and the tracking ID information. In other troubleshooting scenarios, such information can be valuable.

Log messages are interpreted as follows:

  1. PingFederate finds an applicable policy named General clients policy. The first checkpoint is an OAuth Client Set Authentication Selector instance generalClients. PingFederate routes this request to the Yes policy path because the client that submits the authorization request matches one of the clients defined authentication selector instance.

  2. PingFederate routes this request to an instance of the Identity First Adapter idFirst because that adapter instance is the next authentication source of the Yes policy path.

  3. Based on the user’s provided user identifier, PingFederate determines that the Alpha rule applies and routes this request to the Alpha policy path.

  4. PingFederate routes this request to an identity provider (IdP) connection https://sso.alpha.local:8031 because that IdP connection is the next authentication source of the Alpha policy path. PingFederate also populates the subject attribute in the AuthnRequest message with the user identifier obtained from the Identity First Adapter instance.

  5. PingFederate receives a valid security token from the IdP https://sso.alpha.local:8031. PingFederate routes the request to the Success policy path, which ends with an authentication policy contract APC and concludes the authentication flow.