PingFederate Server

Configuring a REST API datastore

Create a REST API datastore to interact with a REST API.

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 checkbox.

  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 can’t 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 aren’t 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.

    If you leave the JSON Response Attribute Path field blank, the local attribute maps to the full JSON response document.

    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 an Authentication Method:

    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 using the HTTP Basic authentication scheme. Enter the required credentials in the Username and Password fields.

    Client TLS Certificate

    To support mutual TLS (mTLS), PingFederate authenticates by presenting the client transport layer security (TLS) certificate that you select in the Client TLS Certificate list.

    If you haven’t yet created or imported a client certificate, click SSL Client Keys & Certificates to do so. Learn more in Manage SSL client keys and certificates.

    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 or private key JWT grant type to obtain an access token from an authorization server and presents the access token to the data source for authentication.

  11. Select the HTTP Method to call the REST API service: GET, POST, PUT, PATCH or DELETE.

    All request 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 requests to the REST API data store.

  12. The required authentication fields depend on which Authentication Method you selected. The following table describes the fields required for each authentication method:

    Field Description

    Basic Authentication

    Username

    Enter the username for basic authentication

    Password

    Enter the password for basic authentication

    Password Reference

    If you’re using a configured password manager, enter the secret reference. The format is OBF:MGR:{secretManagerId}:{secretId}. Learn more in Secret managers.

    Client TLS Certificate

    Client TLS Certificate

    Select a certificate in the list. You can manage certificates in the SSL Client Keys & Certificates menu. Learn more in Manage SSL client keys and certificates.

    OAuth 2.0 Bearer Token

    OAuth Authentication Method

    Select one:

    Client Credentials

    PingFederate obtains a token using a client ID and client secret pair.

    Private Key JWT

    PingFederate obtains a token using a client assertion.

    The subsequent fields required depend on which OAuth authentication method you choose.

    Client Credentials

    OAuth Token Endpoint

    Enter a valid URL for the authorization server endpoint.

    OAuth Scope (optional)

    Enter the scopes to request from the authorization endpoint. Separate scopes with a space.

    Client ID

    Enter the ID of the client created in the authorization server for authentication.

    Client Secret

    Enter the secret for the client created in the authorization server for authentication.

    Secret Reference

    If you’re using a configured secret manager, enter the secret reference for the client created in the REST service. The format is OBF:MGR:{secretManagerId}:{secretId}. Learn more in Secret managers.

    Private Key JWT

    OAuth Token Endpoint

    Enter a valid URL for the authorization server endpoint.

    OAuth Scope (optional)

    Enter the scopes to request from the authorization endpoint. Separate scopes with a space.

    Client ID

    Enter the ID of the client created in the authorization server for authentication.

    Use Centralized Signing Key

    Select if you want to use centralized PingFederate signing keys when signing JWT client assertions.

    When you use this option, the authorization server can retrieve the key it needs to validate the digital signature using the PingFederate /pf/JWKS endpoint.

    This is the recommended approach and is selected by default. Learn more about Centralized Signing Key in Keys for OAuth and OpenID Connect.

    JWT Signing Key (optional)

    Select a specific certificate from the PingFederate certificate store to use for signing JWT client assertions. Only do this if you didn’t select Use Centralized Signing Key. If you haven’t created or imported a certificate into PingFederate, click Manage Signing Certificates at the bottom of the menu to do so.

    If you use this option, the authorization server requires the specified JWT signing key to validate the digital signature.

    JWT Signing Algorithm

    Select an algorithm in the list to use for signing the client assertion.

    JWT Audience

    Enter an audience claim for the JWT client assertion.

    The recommended value is the issuer identifier of the client authorization server.

    JWT Lifetime (Minutes)

    Enter an integer for the lifetime of the JWT client assertion. Default value is 5. Maximum value is 1440.

    JWT Type Header

    Enter the type header value for the JWT client assertion.

    Not Before Claim (optional)

    When enabled, the JWT client assertion includes an nbf (Not Before) claim backdated by 5 seconds. This provides a buffer to account for clock skew between systems.

  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 host name of the data source matches the subject (CN) or one of the subject alternative names (SANs) from the certificate.

    You should verify the host name for all connections.

    This checkbox 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 checkbox 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.

    Maximum Connections

    An integer that defines the maximum number of connections that can be open for this datastore.

    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.

    Test Connection Body

    The request body to include in the connection test request.

    Exclude Default Content-Type From GET Request

    When selected, the default Content-Type header is excluded from GET requests. Custom headers are still included. This checkbox is selected by default.

  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 might contain additional messages as well.

  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 and make the full JSON response available for additional processing, create a REST API datastore with the following attributes.

Local Attribute JSON Response Attribute Path

Dept

/department

Telephone

/telephoneNumbers/0

Zip

/office/zipCode

FullResponse

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