PingFederate Server

Configuring a REST API datastore

To retrieve attribute data from a JSON-based REST API, you must first create a REST API datastore.

Steps

  1. Go to System → Data & Credential Stores → Data Stores.

  2. On the Data Stores window, click Add New Data Store.

  3. On the Data Store Type tab, type a name for the datastore.

  4. From the Type list, select Rest API.

  5. Optional: To mask attribute values returned from this datastore in PingFederate logs, select the Mask Values in Log check box.

  6. Click Next.

  7. On the Configure Data Store Instance tab, click Add a new row to 'Base URLS and Tags'.

    1. Enter the Base URL of the data source offering REST API access to its data. You can enter multiple base URLs.

      If you configure multiple URLs, nodes use the first URL with a tag that matches one of the node.tags in the run.properties file.

    2. Optional: Enter one or more tags per base URL.

      Tags are defined in the node.tags property in the <pf_install>/pingfederate/bin/run.properties file. For a description of the node.tags property, see Deploying cluster servers.

      In PingFederate deployments that are regional, you can enter one or more tags for a Base URL, which specifies the PingFederate node the datastore should communicate with. If none of the tags match what is defined for the node.tags property, the default node is used.

      The following rules apply to tags:

      • You must separate multiple tags specified for one node with spaces.

      • Tags must unique per base datastore.

      • You cannot use a tag more than once per datastore.

      • Tags are optional. If needed, you can configure a non-default node without tags. Doing this is useful if you are not yet ready to tag the node, or if you are still in the planning stage but want to enter the address for the node now.

    3. Click Update under Action.

    4. Select Set as Default under Action beside the Base URL and Tags that you want to use as the default. The first Base URL and Tags configured is set as the default automatically.

      If the data source exposes multiple paths or requires specific query parameters to retrieve user records, enter the base URL here and then specify the path and query parameters in the attribute source configuration.

      For more information, see Specifying data source filters for REST API datastores.

  8. If the data source requires specific HTTP request headers, click Add a new row to 'HTTP Request Headers'.

    If configured, PingFederate includes the configured HTTP request headers and their values when contacting the data source.

    1. Enter the applicable name and value under Header Name and Header Value.

    2. Click Update under Action.

      Repeat these steps to define additional HTTP request headers and their values.

  9. Click Add a new row to 'Attributes' to define local attribute names and map them to the data returned by the data source.

    Map each attribute to a path representing an attribute in the JSON response. This path follows the syntax defined in the JavaScript Object Notation (JSON) Pointer specification at tools.ietf.org/html/rfc6901.

    You must define at least one attribute.

    1. Enter the Local Attribute name and JSON Response Attribute Path.

    2. Click Update under Action.

      Repeat these steps to define additional attributes.

      Define only the attributes required by other configuration items, such as contract fulfillment or token authorization. Provide meaningful attribute names so that you can easily recognize them at a later time.

  10. Select one of the following authentication methods:

    Option Description

    None

    PingFederate makes unauthenticated REST API requests to the data source. No credential information is required. This is the default setting.

    Basic Authentication

    PingFederate authenticates via the HTTP Basic authentication scheme. Enter the required credentials in the Username and Password fields.

    OAuth 2.0 Bearer Token

    PingFederate authenticates by presenting an OAuth 2.0 access token. In this scenario, PingFederate is an OAuth client, specifically a client that uses the client credential grant type to obtain access token from an authorization server and presents the access token to the data source for authentication. Enter the client credentials in the Client ID and Client Secret fields. Then enter the token endpoint URL at the authorization server and the applicable scope (or scopes) in the OAuth Token Endpoint and OAuth Scope fields.

  11. Select the HTTP Method to call the REST API service: GET or POST.

    Both methods support the JSON and x-www-form-urlencoded body types, among others, but PingFederate can parse only JSON responses.

    When configuring data source filters for attribute sources and user lookup, you can define the body sent in GET or POST requests to the REST API data store.

  12. Optional: To mask attribute values returned through this datastore in the PingFederate log, select the Mask Values in Log check box.

    This check box is visible only when editing an existing datastore and is not checked by default.

  13. Optional: Click Show Advanced Fields to configure additional settings.

    The following table describes the advanced fields.

    Field Description

    Enable HTTPS Hostname Verification

    Indicates whether to verify that the hostname of the data source matches the subject (CN) or one of the subject alternative names (SANs) from the certificate.

    You should verify the hostname for all connections.

    This check box is selected by default.

    Read Timeout (MS)

    Defines the socket timeout in milliseconds.

    Enter 0 to set an infinite timeout.

    Enter a negative integer to use the default value set by the operating system.

    The default value is 10000 in milliseconds, which is 10 seconds.

    Connection Timeout (MS)

    Determines the timeout in milliseconds until a connection is established.

    Enter 0 to set an infinite timeout.

    Enter -1 to use the default value set by the operating system.

    The default value is 10000 in milliseconds, which is 10 seconds.

    Max Payload Size (KB)

    Defines the maximum allowed size in kilobytes (KB) of the returned JSON response payload.

    Enter 0 to configure an unrestricted payload size.

    The default value is 1024 in KB.

    Retry Request

    Determines whether to retry a user data retrieval request if the data source returns an HTTP status code found in the Retry Error Codes.

    This check box is selected by default.

    Maximum Retries Limit

    Defines the maximum number of retry attempts if the data source returns an HTTP status code found in the Retry Error Codes.

    The default value is 5.

    Retry Error Codes

    Enter a comma-separated list of HTTP status codes, for which if received from the data source, PingFederate might retry the request.

    For example, you can enter 429 for "Too Many Request" or 503 for "Service Unavailable".

    The default value is 429.

    Test Connection URL

    Determines the URL to which PingFederate sends requests to test the datastore connection on the Actions tab.

    When not specified (the default), PingFederate sends requests to the base URL of the datastore.

  14. On the Actions tab, verify the datastore configuration.

    1. Click Test Connection to test the connectivity between PingFederate and the data source.

      Result:

      The administrative console displays the results returned by the data source. The PingFederate server log may contain additional messages as well.

    2. Review the results.

    3. Optional: Click Reset and repeat the test.

  15. On the Summary tab, review your configuration, amend as needed, click Save to keep your configuration or click Cancel to discard it.

Example

You have two use cases that can leverage user attributes obtained through REST APIs. The data source returns user records in JSON:

{
  "uid": "asmith",
  "office": {
    "city": "Denver",
    "state": "CO",
    "zipCode": 80202
  },
  "telephoneNumbers": [
    "+1 303-555-1234",
    "+1 303-555-5678"
  ],
  "department": "Engineering"
}

The first use case requires the user’s department, while the second use case requires the first telephone number and the ZIP code.

To address both use cases, create a REST API datastore with the following attributes.

Local Attribute JSON Response Attribute Path

Dept

/department

Telephone

/telephoneNumbers/0

Zip

/office/zipCode

Once set up, you can fulfill various contracts or configure issuance criteria based on the attribute data from the data source.