PingFederate Server

Defining issuance criteria for token creation

About this task

On the Issuance Criteria tab, define the criteria that must be satisfied for PingFederate to process a request further. This token authorization feature can conditionally approve or reject requests based on individual attributes.

Begin this optional configuration by adding a criterion. Choose the source that contains the attribute to be verified. Some sources, such as Mapped Attributes, are common to almost all use cases. Other sources, such as JDBC, depend on the type of configuration. PingFederate automatically hides irrelevant sources. After you select a source, choose the attribute to be verified. Depending on the selected source, the available attributes or properties vary. Finally, specify the comparison method and the desired comparison value.

If you define multiple criteria, all criteria must be satisfied for PingFederate to move a request to the next phase. A criterion is satisfied when the runtime value of the selected attribute matches or does not match the specified value depending on the chosen comparison method. The multi-value contains and multi-value does not contain comparison methods are intended for attributes that might contain multiple values. A criterion using these methods is considered satisfied if one of the multiple values matches or does not match the specified value. Values are compared verbatim. If you require complex evaluations, including conditional criteria or partial matching, define them using attribute mapping expressions.

When you multiplex one connection for multiple environments, consider using attribute mapping expressions to verify the virtual server ID in conjunction with other conditions, such as group membership information, to protect against unauthorized access. Learn more in Multiple virtual server IDs and Issuance criteria and multiple virtual server IDs.

All criteria defined must be satisfied or evaluated as true for a request to move forward. As soon as one criterion fails, PingFederate rejects the request and returns an error message.

Steps

  1. On the Token Generator Mapping & User Lookup configuration page, go to the Issuance Criteria tab.

  2. In the Source list, select the attribute’s source.

  3. Depending on the selection, the Attribute Name list populates with associated attributes. The following table describes the available attributes or properties.

    Attributes or properties and descriptions
    Source Description

    Context

    Select to evaluate properties returned from the context of the transaction at runtime.

    Because the HTTP Request and STS SSL Client Certificate Chain context values are retrieved as a Java object rather than text, use attribute mapping expressions to evaluate and return values.

    JDBC, LDAP, or other types of datastore (if configured)

    Select to evaluate attributes returned from a data source.

    Mapped Attributes

    Select to evaluate the mapped attributes.

    Token

    Select to evaluate attributes from the token processor instance.

  4. Select the attribute to evaluate under Attribute Name.

    To evaluate the STS Basic Authentication Username, STS SSL Client Certificate Chain, or STS SSL Client Certificate’s Subject DN context value, ensure that the associated authentication is enabled and configured on System > Server > Protocol Settings to open the WS-Trust STS Settings page.

  5. In the Condition list, select the comparison method.

    Available methods:

    • equal to

    • equal to (case insensitive)

    • equal to DN

    • not equal to

    • not equal to (case insensitive)

    • not equal to DN

    • multi-value contains

    • multi-value contains (case insensitive)

    • multi-value contains DN

    • multi-value does not contain

    • multi-value does not contain (case insensitive)

    • multi-value does not contain DN

    The first six conditions are intended for single-value attributes. Use one of the multi-value …​ conditions for PingFederate to validate whether one of the attribute values matches the specified value. When an attribute has multiple values, using a single-value condition causes the criteria to fail.

    To evaluate the STS SSL Client Certificate’s Subject DN context value, select one of the …​ DN conditions. These methods normalize the distinguished name (DN) before comparison to accommodate different string representations that are still considered equivalent, such as case sensitivity or white space.

  6. In the Value field, enter the comparison value.

    Values are compared verbatim. If you require complex evaluations, including conditional criteria or partial matching, define them using attribute mapping expressions. Learn more in Attribute mapping expressions.

  7. In the Error Result field, enter a custom error message.

    The faultstring element for SOAP 1.1 and the Reason/Text element for SOAP 1.2 use the Error Result field. Learn more in Simple Object Access Protocol.

    Using an error code in the Error Result field let an application process the code in a variety of ways, such as displaying an error message or emailing an administrator.

    To use localized descriptions, enter a unique alias in the Error Result field, such as someIssuanceCriterionFailed. Insert the same alias with the desired localized text in the applicable language resource files, located in the <pf_install>/pingfederate/server/default/conf/language-packs directory.

    If not defined, PingFederate returns ACCESS_DENIED when the criterion fails at runtime.

  8. Click Add.

  9. Optional: Repeat to add more criteria.

  10. If you require complex evaluations, including conditional criteria or partial matching, define them using attribute mapping expressions. Learn more in Attribute mapping expressions.

    1. Click Show Advanced Criteria.

    2. In the Expression field, enter the required expressions.

    3. In the Error Result field, enter an error code or message.

      If the expressions resolve to a string value instead of true or false, the returned value overrides the Error Result field value.

    4. Click Add.

    5. Click Test, enter values in the applicable fields, and verify the results.

    6. Repeat to add multiple criteria using attribute mapping expressions.