PingFederate Server

Defining authentication policies

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

Steps

  1. Go to Authentication > Policies > Policies.

  2. On the Policies tab, select the IdP Authentication Policies checkbox 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 checkbox to enable authentication policies for service provider (SP)-initiated browser SSO requests received at the /sp/startSSO.ping endpoint.

    Selecting the SP Authentication Policies checkbox doesn’t enable authentication policies for IdP browser SSO requests, adapter-to-adapter requests, and browser-based OAuth authorization code and implicit flows.

  4. Select the Fail if policy engine finds no authentication source checkbox for PingFederate to deny the requests and 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 checkbox is cleared by default.

  5. On the Policies page, click Add Policy to create an authentication policy.

    To create a new policy based on an existing policy, select Copy in the policy’s Select Action menu.

    1. On the Policy page, enter a name and, optionally, a description of the policy.

    2. Select the Handle Failures Locally checkbox 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. In the Policy list, select an authentication source, IdP adapter instance or IdP connection, selector instance, or 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 checkbox 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 (MFA) 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 in the list.

      You can select Fragments as the policy action and, then, select a policy fragment that you have created. 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. Learn about creating policy fragments in Policy fragments.

      • If additional processing is required, repeat step 5c.

      • 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 as 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, refer to 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 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.

    5. Click Done to go back to the Policies page.

      Result:

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

  6. (Optional) Repeat step 5 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.

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

  8. (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.

  9. (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. Learn more in Configuring the HTTP Request Parameter Authentication Selector.

  10. Click Save.