PingFederate Server

Fulfilling resource owner credentials grant mapping

On the Contract Fulfillment tab, map authentication source values into persistent grants.

About this task

The USER_KEY attribute is the identifier of the persistent grants.

If extended attributes are defined in System → OAuth Settings → Authorization Server Settings, configure a mapping for each attribute.

The USER_KEY attribute values must be unique across all end users, because the USER_KEY attribute is the user identifier to store and to retrieve persistent grants. For example, the sAMAccountName attribute value of an end user in one domain might match that of another end user in another domain. In this case, you can map the Subject DN attribute to the USER_KEY attribute.

Steps

  1. On the Contract Fulfillment tab, select a source from the Source list, and then select or enter a value for each attribute in the contract.

    Map each attribute from one of the following sources:

    Password Credential Validator

    When selected, the associated Value list populates with attributes associated with the credential-validation instance.

    Context

    Values are returned from the context of the transaction at runtime.

    If PERSISTENT_GRANT_LIFETIME is an extended attribute in System → OAuth Settings → Authorization Server Settings, you can set the lifetime of persistent grants based on the outcome of attribute mapping expressions, or the per-client Persistent Grants Max Lifetime setting.

    • To set lifetime based on the per-client Persistent Grants Max Lifetime setting, select Context from the Source list and Default Persistent Grant Lifetime from the Value list.

    • To set lifetime based on the outcome of attribute mapping expressions, select Expression as the source and enter an OGNL expression in the Value field.

      If the expression returns a positive integer, the value represents the lifetime of the persistent grant in minutes.

      If the expression returns the integer 0, PingFederate does not store the grant and does not issue a refresh token.

      If the expression returns any other value, PingFederate sets the lifetime of the persistent grant based on the per-client Persistent Grants Max Lifetime setting.

    • To set a static lifetime, select Text from the Source list and enter a static value in the Value field.

      This is suitable for testing purposes, or cases where the persistent grant lifetime must always be set to a specific value.

    As the HTTP Request context value is retrieved as a Java object rather than text, OGNL expressions are ideal to evaluate and return values.

    Context

    Values are returned from the context of the transaction at runtime.

    If PERSISTENT_GRANT_LIFETIME is an extended attribute in System → OAuth Settings → Authorization Server Settings, you can set the lifetime of persistent grants based on the outcome of attribute mapping expressions, or the per-client Persistent Grants Max Lifetime setting.

    • To set lifetime based on the per-client Persistent Grants Max Lifetime setting, select Context from the Source list and Default Persistent Grant Lifetime from the Value list.

    • To set lifetime based on the outcome of attribute mapping expressions, select Expression as the source and enter an OGNL expression in the Value field.

      If the expression returns a positive integer, the value represents the lifetime of the persistent grant in minutes.

      If the expression returns the integer 0, PingFederate does not store the grant and does not issue a refresh token.

      If the expression returns any other value, PingFederate sets the lifetime of the persistent grant based on the per-client Persistent Grants Max Lifetime setting.

    • To set a static lifetime, select Text from the Source list and enter a static value in the Value field.

      This is suitable for testing purposes, or cases where the persistent grant lifetime must always be set to a specific value.

    As the HTTP Request context value is retrieved as a Java object rather than text, OGNL expressions are ideal to evaluate and return values.

    Extended Client Metadata

    Values are returned from the client record.

    LDAP/JDBC/Other (when a datastore is used)

    Values are returned from your datastore. When selected, the Value list is populates with attributes from the datastore.

    Expression (when enabled)

    Provides more complex mapping capabilities, such as transforming incoming values into different formats. All of the variables available for text entries are also available for expressions.

    No Mapping

    Ignores the Value field.

    Text

    You can enter a text value only, or you can mix text with references to the unique user ID returned from the credentials validator, using the $attribute syntax. You can also enter values from your datastore, when applicable, using the ${ds.attribute} syntax, where attribute is any of the datastore attributes you have selected.

  2. Click Next.