PingAccess

Adding web session attribute rules

Use a web session attribute rule to examine a request and determine whether to grant access to a target site based on a match found between the attribute values in the PingAccess token and the attribute values that you specify with this rule.

About this task

Use this rule to test if an attribute in a web session contains a specific value, then grant or deny access to a target site based on whether a match is found.

Steps

  1. Click Access and then go to Rules → Rules.

  2. Click Add Rule.

  3. In the Name field, enter a unique name up to 64 characters long.

    Special characters and spaces are allowed.

  4. In the Type list, select Web Session Attribute.

  5. To grant the client access, select the Attribute Name that you want to match, such as Group.

  6. In the Matching Strategy list, select the context that you want PingAccess to evaluate requests with when looking for a match.

    Choose from:

    • Case-Sensitive: To register as a match, the attribute value in the request must be written in the same case as the attribute value that you specify in step 7. By default, PingAccess uses this matching strategy.

    • Case-Insensitive: Case doesn’t matter when looking for a match. Select this option for more flexibility if you might make changes to the attribute source that don’t alter it semantically.

    • DN Matching: Normalizes both the attribute value that you specify in step 7 and any attribute value that PingAccess gathers at runtime from the user identity attributes as an X.500 distinguished name (DN). PingAccess then looks for a match between the distinguished names.

      • If you select DN Matching, make sure to select an Attribute Name in step 5 that can contain a DN. The administrative console doesn’t provide a warning if you select an invalid attribute type, but you can check your log files to confirm that you don’t have any DN-related errors.

      • PingAccess validates the Attribute Value that you specify in step 7 to make sure that it’s a valid X.500 DN that follows RFC-1779 or RFC-2253. Copy-paste the attribute value to ensure accuracy.

      • Relative DNs that have non-printable or non-UTF-8 string values, such as email and domain component (DC) relative DNs, are case sensitive. Otherwise, relative DN values are case-insensitive.

      • If you have a relative DN with multiple attribute-value pairs separated by a plus sign (+) delimiter, order doesn’t matter because of normalization. For example, if you define part of a relative DN in the order CN=Engineering+OU=Groups, then a request containing those same attribute-value pairs in reverse order OU=Groups+CN=Engineering still returns a match.

      • The normalization process also replaces semicolon delimiters with commas, removes leading and trailing white spaces, and replaces hexadecimal values with their associated characters.

  7. Enter the Attribute Value for the attribute name, such as Sales.

    Copy-paste the attribute value to ensure accuracy.

    If the attribute has multiple values at runtime, the attribute value you specify here must match one of those values.

    If you are using PingFederate as the token provider, PingAccess obtains token attributes from the PingFederate OpenID Connect (OIDC) policy attribute contract. For more information, see Configuring OpenID Connect Policies.

  8. Optional: To add more attributes, click Add Row.

  9. Optional: To remove a row, click the Delete icon.

  10. Optional: To disallow access when a match is found, click Negate.

    Ensure the attribute name is spelled correctly and exists. If you enter an attribute that does not exist and you select Negate, the rule will always succeed.

  11. To configure rejection handling, click Show Advanced Settings, then select a rejection handling method.

    Choose from:

    • If you select Default, use the Rejection Handler list to select an existing rejection handler that defines whether to display an error template or redirect to a URL.

    • If you select Basic, you can customize an error message to display as part of the default error page rendered in the end user’s browser if rule evaluation fails. This page is among the templates you can modify with your own branding or other information. If you select Basic, provide the following:

      1. In the Error Response Code field, enter the HTTP status response code to send if rule evaluation fails.

        The default is 403.

      2. In the Error Response Status Message field, enter the HTTP status response message to send if rule evaluation fails.

        The default is Forbidden.

      3. In the Error Response Template File field, enter the HTML template page for customizing the error message that displays if rule evaluation fails. This template file is located in the <PA_HOME>/conf/template/ directory.

      4. From the Error Response Content Type list, select the type of content for the error response.

        This lets the client properly display the response.

  12. Click Save.

    To use this rule, select the Request Profile check box, indicating that you want PingAccess to request additional profile attributes from PingFederate when requesting the ID token.