This REST-based runtime API facilitates the use case where clients can assume the responsibility of grant management if the users authorize the clients to do so. In this scenario, a client prompts the user to approve a specific scope for managing persistent grants on the user's behalf. If the user approves, the client requests an access token with such scope from PingFederate. As long as the access token remains valid, the client can retrieve and revoke persistent grants and their associated extended attribute names and values (if any) for that user.

The activation of the Persistent Grant Management API requires two settings, the scope required to perform this task and the Access Token Management instance under which the access tokens issued can be used by one or more clients to manage persistent grants. Both settings are found on the OAuth Server > Authorization Server Settings screen. Additionally, clients, which are capable of managing grants on their users' behalves, must be configured to use the selected Access Token Management instance in their client records.

Note:

To use this runtime API, clients must authenticate by presenting a valid access token with the required scope as a bearer token via the HTTP Bearer authentication scheme.

Tip:

Not all OAuth use cases involve persistent grants. For more information, see Persistent versus transient grants.

Endpoint: /pf-ws/rest/oauth/grants[/<grantId>]

This REST resource accepts the GET (for retrieval) and DELETE (for revocation) methods. The results are formatted in JavaScript Object Notation (JSON).

Parameter
Parameter Description
grantId 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 by a previous GET request from this endpoint.

Note:

This parameter is required to revoke a specific grant.
Cross Site Request Forgery Protection
This endpoint requires the X-XSRF-HEADER HTTP Header with any value to prevent cross site request forgery.
Sample request
A request to retrieve all grants: 
GET /pf-ws/rest/oauth/grants/ HTTP/1.1
Host: localhost:9031
Authorization: Bearer eyJhbG...IKqMfg
X-XSRF-HEADER: PingFederate

In this example, the client prompted the resource owner (Joe) to authorize it to manage persistent grants on his behalf. Joe agreed and approved the requested scope (admin). The client then obtained an access token with such scope from PingFederate. The access token issued was a self-contained JWT (JSON Web Token).

This sample request illustrates a GET request from the client when it wants to retrieve a list of grants associated with Joe by presenting the access token to the Persistent Grant Management API for authentication. (The access token is truncated for readability.)

Sample response
{
    "items": [
        {
            "id": "5a4nszZOppgo9RfRtrVXNY0Eq5ka1YZ6",
            "userKey": "joe",
            "grantType": "RESOURCE_OWNER_CREDENTIALS",
            "scopes": [
                "phone"
            ],
            "clientId": "ro_client",
            "issued": "2018-12-15T00:54:30.190Z",
            "updated": "2018-12-15T00:54:30.190Z"
        },
        {
            "id": "PTfURLoaXC97JXU6uilAORSkFQoMOLyV",
            "userKey": "joe",
            "grantType": "AUTHORIZATION_CODE",
            "scopes": [
                "openid",
                "profile",
                "admin"
            ],
            "clientId": "ac_oic_client",
            "issued": "2018-12-15T18:29:26.018Z",
            "updated": "2018-12-15T18:29:26.018Z"
        },
        {
            "id": "k1oFbxujlGHbfEBfVqDj0aIDllFBzghX",
            "userKey": "joe",
            "grantType": "AUTHORIZATION_CODE",
            "scopes": [
                "openid",
                "email",
                "phone"
            ],
            "clientId": "ac_oic_client",
            "issued": "2018-12-15T19:03:29.439Z",
            "updated": "2018-12-15T19:03:29.439Z"
        },
        {
            "id": "EhzZYggNuFT9EWpw9p21SYCddwAPFAKR",
            "userKey": "joe",
            "grantType": "IMPLICIT",
            "scopes": [
                "openid",
                "profile"
            ],
            "clientId": "im_oic_client",
            "issued": "2018-12-15T19:04:05.044Z",
            "updated": "2018-12-15T19:04:05.044Z"
        }
    ]
}

In this example, PingFederate returned four persistent grants associated with the resource owner from three clients.

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

    Returned when revoking a persistent grant.

  • 401 – Invalid Credentials

    The access token is invalid (including the lack of the required scope) or missing.

  • 404 – Not Found

    Returned when the requested persistent grant is not found or a grant ID is missing.

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