PingFederate includes a REST-based web service to manage OAuth persistent grants administratively. This service enables retrieval and revocation of persistent grants and their associated extended attribute names and values (if any) on a per-client or per-resource owner basis.

Important:

Client records must be stored in an external client data store.

Note:

Applications must authenticate to this web service using HTTP Basic authentication and credentials validated through an instance of a Password Credential Validator. The Password Credential Validator instance, in turn, must be selected in the OAuth AS configuration.

Endpoints

Manage by client
/pf-ws/rest/oauth/clients/<clientId>/grants[/<grantId>]
Manage by user (based on the USER_KEY value)
/pf-ws/rest/oauth/users/<userKey>/grants[/<grantId>]

Both REST resources accept the GET (for retrieval) and DELETE (for revocation) methods. The results are formatted in JavaScript Object Notation (JSON).

Parameters
Parameter Description
clientId The client ID for which to retrieve or revoke grants.

Required to manage grants for a specific client.

userKey The USER_KEY value for which to retrieve or revoke grants.

Required to manage grants for a specific resource owner.

Tip:

The USER_KEY value varies, depending on its fulfillment based on the mapping configuration defined in the IdP Adapter Mapping, Authentication Policy Contract Mapping, or Resource Owner Credentials Mapping wizard.

grantId

(Optional)

The persistent grant identifier for which to retrieve or revoke a specific grant.

The value corresponds to the value of the id field found in the JSON array of grants returned from a previous GET /oauth/clients/<clientId>/grants or GET /oauth/users/<userKey>/grants request.

Note: If this parameter is not specified, the request applies to all grants for the client or user.
Cross Site Request Forgery Protection
Both endpoints require the X-XSRF-HEADER HTTP Header with any value to prevent cross site request forgery.
Example 1
Sample request
A request to retrieve all grants for client with an ID value of ac_client. Note that this client is configured with Allowed Grant Types values of Authorization Code and Refresh Token.
GET /pf-ws/rest/oauth/clients/ac_client/grants HTTP/1.1
Host: localhost:9031
Authorization: Basic YWRtaW46MkZlZGVyYXRl
X-XSRF-HEADER: PingFederate
Sample response
{
    "items": [
        {
            "id": "ixqWL3k9ZnPxjTaphcFLrVqwdrtvc6tV",
            "userKey": "asmith",
            "grantType": "AUTHORIZATION_CODE",
            "scopes": [],
            "clientId": "ac_client",
            "issued": "2019-03-15T20:00:27.343Z",
            "updated": "2019-03-15T20:00:27.343Z",
            "grantAttributes": [
                {
                    "name": "pgeaAttrMulti",
                    "values": [
                        "CN=group1,OU=Resources,DC=example,DC=local",
                        "CN=group2,OU=Resources,DC=example,DC=local"
                    ]
                },
                {
                    "name": "pgeaAttrSingle",
                    "values": [
                        "asmith@example.local"
                    ]
                }
            ]
        }
    ]
}
Example 2
Sample request
A request to retrieve all grants for client with an ID value of im_client. Note that this client is configured with an Allowed Grant Types value of Implicit, and PingFederate is configured to reuse existing persistent access grants for the implicit grant type on the OAuth Server > Authorization Server Settings screen.
GET /pf-ws/rest/oauth/clients/im_client/grants HTTP/1.1
Host: localhost:9031
Authorization: Basic YWRtaW46MkZlZGVyYXRl
X-XSRF-HEADER: PingFederate
Sample response
{
    "items": [
        {
            "id": "G7fV0HVALkplTl1Hdw109DYzlLNPXXIt",
            "userKey": "asmith",
            "grantType": "IMPLICIT",
            "scopes": [],
            "clientId": "im_client",
            "issued": "2019-03-15T18:20:39.652Z",
            "updated": "2019-03-15T18:20:39.652Z"
        }
    ]
}

(For more information, about persistent grants and their relationship with various grant types, see Persistent versus transient grants.)

Return codes
  • 200 – Success
  • 204 – Success with no content returned

    Returned when revoking a persistent grant.

  • 401 – Invalid Credentials

    The user does not exist, the password is incorrect, or the user account is locked.

  • 404 – Not Found

    Returned when the requested persistent grant or client is not found.

  • 500 – Internal Server Error

    An unknown error has occurred.

Logging

PingFederate records the actions performed via this endpoint in the runtime-api.log file. While the events themselves are not configurable, you may adjust the log4j2.xml configuration settings to alter the format and desired level of detail surrounding each event.

Each log entry contains information relating to the event, including:

  • Time the event occurred on the PingFederate server
  • Administrator username performing the action
  • Authentication method
  • Client IP
  • HTTP method
  • REST endpoint
  • HTTP status code

Each of the above fields is separated by a vertical pipe (|) for ease of parsing.