The USER_KEY attribute is the identifier of the persistent grants. The USER_NAME attribute presents the name shown to the resource owner on OAuth user-facing pages. If extended attributes are defined in System > OAuth Settings > Authorization Server Settings, configure a mapping for each attribute.

Important:

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, if you are configuring an OAuth attribute mapping on a SAML 2.0 identity provider (IdP) connection and the SAML_SUBJECT attribute uniquely identifies all end users, you can map the SAML_SUBJECT attribute to the USER_KEY attribute.

  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:
    • Authentication Policy Contract

      Populates the associated Value list with attributes associated with the APC.

    • Context

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

      Note:

      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 you make this selection, the Value list 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.