PingFederate Server

Configuring directories for grant storage

PingFederate requires specific schema objects to store grants, the associated attributes, and their values (if any) on your directory server. LDIF scripts are provided for supported directory servers.

Steps

  1. Review the LDIF scripts for your directory server provided in the <pf_install>/pingfederate/server/default/conf/access-grant/ldif-scripts directory.

  2. Replace placeholder values with relevant information from your directory server.

  3. Run the LDIF scripts to update your LDAP schema.

    For Active Directory, run the script to create the attributes. Then, run the script to create the object class.

    For PingDirectory, run the ldapmodify command. For example:

    $ ldapmodify \
  --defaultAdd \
  --filename "<path to ldif file>\access-grant-attributes-ldap-pingdirectory.ldif" \
  -h <hostname> \
  -p <port> \
  -D "<adminDN>" \
  -w <adminPassword>

    For PingDS, run the ldapmodify command. For example:

    $ ldapmodify \
  --hostname <hostname> \
  --port <port> \
  --bindDn "<adminDN>" \
  --bindPassword <adminPassword> \
  --useSsl \
  --usePkcs12TrustStore /path/to/opendj/config/keystore \
  --trustStorePassword:file /path/to/opendj/config/keystore.pin \
  --no-prompt <path to ldif file>\access-grant-attributes-ldap-pingds.ldif

  4. If you haven’t already done so, create an LDAP datastore for your directory server at System > Data & Credential Stores > Data Stores.

  5. Copy the system ID of the applicable LDAP datastore from System > Data & Credential Stores > Data Stores.

  6. Edit the configuration file relevant to your directory server.

    This configuration file is located in the <pf_install>/pingfederate/server/default/data/config-store directory, as described in the following table.

    Directory server Configuration file

    PingDirectory

    org.sourceid.oauth20.token.AccessGrantManagerLDAPPingDirectoryImpl.xml

    PingDS

    org.sourceid.oauth20.token.AccessGrantManagerLDAPPingDSImpl.xml

    Microsoft Active Directory

    org.sourceid.oauth20.token.AccessGrantManagerLDAPADImpl.xml

    Oracle Unified Directory

    org.sourceid.oauth20.token.AccessGrantManagerLDAPOracleImpl.xml

    For a clustered PingFederate environment, edit this file on the administrative console node first and then replicate to other engine nodes using System > Server > Cluster Management as explained in later steps.

    1. Replace the <c:item name="PingFederateDSJNDIName"/> element value with the system ID of your datastore connection.

      Example:

      If the system ID is LDAP-123456789ABCDEF123456789ABCDEF123456A0A6, update the configuration file as follows.

      ...
<!-- Data store id -->
<c:item name="PingFederateDSJNDIName">LDAP-123456789ABCDEF123456789ABCDEF123456A0A6</c:item>
...

    2. Enter a value for the <c:item name="SearchBase"/> element.

      This is the distinguished name (DN) that points to the access grants location. You can find more information in the inline comment and LDIF scripts in the <pf_install>/pingfederate/server/default/conf/access-grant/ldif-scripts directory.

    3. Update the attribute names only if you have changed attribute names in the LDIF scripts located in the <pf_install>/pingfederate/server/default/conf/access-grant/ldif-scripts directory.

    4. Save the file.

  7. Edit the <pf_install>/pingfederate/server/default/conf/service-points.conf file.

    1. Go to the # Service for storage of access grants section.

      # Service for storage of access grants
# Supported classes:
#    org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl : Use this service-point for a Jdbc implementation
#    org.sourceid.oauth20.token.AccessGrantManagerLDAPADImpl : Use this service-point for a Microsoft Active Directory implementation
#    org.sourceid.oauth20.token.AccessGrantManagerLDAPOracleImpl : Use this service-point for an Oracle Directory Server Enterprise Edition implementation
#    org.sourceid.oauth20.token.AccessGrantManagerLDAPPingDirectoryImpl : Use this service-point for a PingDirectory implementation
#    org.sourceid.oauth20.token.AccessGrantManagerDynamoDBImpl : Use this service-point for an Amazon DynamoDB implementation
access.grant.manager=org.sourceid.oauth20.token.AccessGrantManagerJdbcImpl

    2. Change the value of the access.grant.manager service to one of the following values.

      Directory server Service value

      PingDirectory

      org.sourceid.oauth20.token.AccessGrantManagerLDAPPingDirectoryImpl

      PingDS

      org.sourceid.oauth20.token.AccessGrantManagerLDAPPingDSImpl

      Microsoft Active Directory

      org.sourceid.oauth20.token.AccessGrantManagerLDAPADImpl

      Oracle Unified Directory

      org.sourceid.oauth20.token.AccessGrantManagerLDAPOracleImpl

    For a clustered PingFederate environment, you must edit the service-points.conf file on each node manually because cluster replication can’t replicate this change to other nodes.

  8. Start or restart PingFederate.

    For a clustered PingFederate environment, replicate this new configuration to other engine nodes on System > Server > Cluster Management. Start or restart the PingFederate service on each engine node to activate the change.

  9. In the directory, create indexes for the following OAuth grant attributes. If you’re using Active Directory, skip this step because the script for Active Directory creates these indexes. If you’re using PingDirectory, learn more about indexing OAuth grant attributes in Indexing grant attributes in PingDirectory. If you’re using PingDS, learn more about indexing OAuth grant attributes in Indexing grant attributes in PingDS.

    Attribute name Index type

    accessGrantGuid

    equality

    accessGrantUniqueUserIdentifier

    equality

    accessGrantHashedRefreshTokenValue

    equality

    accessGrantClientId

    equality

    accessGrantExpires

    ordering

    accessGrantGrantType

    equality

Result

PingFederate provides two cleanup tasks for persistent grants. One task manages expired grants while another task caps the number of grants based on a combination of user, client, grant type, and authentication context.## Learn more in OAuth persistent grants cleanup.