PingFederate Server

Defining authentication policies

You can manage authentication policies and settings on the Policies window.

Steps

  1. Go to Authentication → Policies → Policies.

  2. On the Policies tab, select the IdP Authentication Policies check box if you want to enable authentication policies for identity provider (IdP) browser single sign-on (SSO) requests, adapter-to-adapter requests, and browser-based OAuth authorization code and implicit flows.

  3. Select the SP Authentication Policies check box if you want to enable authentication policies for service provider (SP)-initiated browser SSO requests received at the /sp/startSSO.ping endpoint.

    Selecting the SP Authentication Policies check box does not enable authentication policies for IdP browser SSO requests, adapter-to-adapter requests, and browser-based OAuth authorization code and implicit flows.

    Select the Fail if policy engine finds no authentication source check box if you want PingFederate to deny the requests and to return an error message when the policy engine finds no authentication source or authentication policy contract from the applicable policies and none of the default authentication sources are applicable. This check box is not selected by default.

  4. On the Policies window, click Add Policy to create an authentication policy.

    If you want to create a new policy based on an existing policy, then in the policy’s Select Action menu, select Copy.

    1. In the Policy window, enter a name and, optionally, a description of the policy.

    2. Select the Handle Failures Locally check box if you want to keep users on the local IdP instead of returning them to the SP when an SP-initiated SSO request fails.

      When selected, after an SSO failure, the IdP uses the error template to give users more useful contextual information about the error than the SP can provide. The default error template is idp.sso.error.page.template.html.

      The checkbox is cleared by default.

    3. From the Policy list, choose an authentication source, an IdP adapter instance or an IdP connection, a selector instance, or a fragment.

      If you started this new policy by copying an existing policy, your new policy is pre-populated. Modify the policy to suit your new use cases.

      When implementing your authentication requirements, think of authentication sources and selectors as checkpoints.
      Options

      For the PingID Adapter, IdP adapters developed using the IdpAuthenticationAdapterV2 interface from the PingFederate SDK, including the HTML Form Adapter, and SAML 2.0 IdP connections supporting the SP-initiated browser SSO profile, you can specify a user ID to be passed in from an earlier-factor adapter.Click Options and follow the on-screen instructions to select the source and the attribute to be used as the incoming user ID.

      The User ID Authenticated check box must be selected for users to register as a new PingID user. Otherwise, the adapter automatically fails.
      Rules

      For any authentication source, you can optionally create one or more rules to define additional successful results. For example, if you want to deploy multi-factor authentication using the PingID Adapter in stages by groups, you can create a rule to check for group membership information and only apply the PingID authentication flow to users who are members of certain groups.Click Rules and follow the on-screen instructions to manage your rules.

      Copy and Paste

      The Copy and Paste feature lets you copy a policy path and paste it into another place in the same policy, another policy, or a policy fragment. After you copy and paste a path, follow the on-screen instructions to correct any errors.

      One benefit of this feature is that you can easily add a new step at the start or middle of an existing policy. To do that, copy and then remove the existing path below the point where you will define the new step. After you define the new step, paste the copied path back into the policy below the new step.

      All results, including those based on rules, are displayed under the selected authentication source or selector instance. Each result forms a policy path.

    4. For each policy path, select a policy action from the list.

      You can select Fragments as the policy action and then select a policy fragment that you have created. (See Policy fragments for information about creating policy fragments.) When you select a fragment, click Fragment Mapping and use the in-product help links to access the topics that describe how to configure the mapping.

      • If additional processing is required, repeat step 4b.

      • If the policy path is extended from an authentication source and it is the end of the path, select Done or Restart, which marks this policy path a closed-ended path.

        A policy path is closed-ended if it contains one or more authentication sources, with or without any selector instances. A closed-ended path can optionally end with an authentication policy contract or a local identity profile.

        If you need to reuse an authentication policy in multiple use cases, select an authentication policy contract or a local identity profile as the last policy action of a path, configure its contract fulfillment, and map the authentication policy contract to the applicable Browser SSO connections or OAuth grant-mapping configuration. Click …​ Mapping underneath your selection and then follow the on-screen instructions to complete the contract fulfillment configuration.

        A policy path is also closed-ended if it ends with an instance of a custom authentication selector that returns an IdP adapter instance ID or the connection ID of an IdP connection. Because the custom selector returns an authentication source, such a closed-ended path cannot end with an authentication policy contract or a local identity profile. Instead, it must end with an action of Done or Restart.

      The Restart policy action provides users the opportunity to do over. When triggered, the policy engine routes the requests back to the first checkpoint of the invoked authentication policy. It makes most sense to use the Restart policy action for a Fail policy path if the policy engine can route the request differently based on user input prompted by an authentication source. For a sample use case, see step 5 in Enabling third-party identity providers.

    Undesirable looping behaviors can occur if you select Restart for the Fail path at the root of an authentication policy tree. PingFederate mitigates this risk by automatically limiting the number of policy restarts per transaction.

    • If the policy path is extended from a selector instance and it is the end of the path without any prior authentication source, select Continue, which leaves this path as an open-ended path.

      A policy path is open-ended if it contains only selector instances without any authentication sources. In this scenario, the policy engine continues to the next applicable authentication policy, if any.

      1. Click Done to go back to the Policies window.

        Result:

        Your policy is enabled by default. As needed, toggle its status to disable the policy.

  5. Optional: Repeat step 4 to create additional authentication policies.

    The order of authentication policies matters because the policy engine starts from the first policy and works its way down.

    As needed, reorder your policies by using the up and down arrows.

  6. If any individual policy is no longer required, select the Delete action or toggle its status to disable the policy.

  7. Optional: On the Policies → Default Authentication Sources tab, select one or more default authentication sources from the list for the policy engine to fall back on when it finds no authentication source from the applicable policies.

    Order matters because the policy engine starts from the first default authentication source on the list and works its way down. As needed, reorder your authentication sources by using the up and down arrows. There is no default selection.

  8. Optional: On the Policies → Tracked HTTP Parameters tab, add one or more HTTP request parameters to be tracked throughout a request.

    For each instance of the HTTP Request Parameter Authentication Selector that you place in a policy as the second, or subsequent, checkpoint, add its configured HTTP Request Parameter Name value here. By doing so, the policy engine preserves the parameter it receives from the initial request and makes it available to the selector instance throughout the policy. For more information, see Configuring the HTTP Request Parameter Authentication Selector.

  9. Click Save.