PingFederate Server

OAuth Persistent Grant Management API

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

  • The Access Token Management instance under which the access tokens issued can be used by clients to manage persistent grants

You can find both settings from the System tab on the System → OAuth Settings → Authorization Server Settings window. Additionally, clients that are capable of managing grants on their users' behalf must be configured to use the selected Access Token Management instance in their client records.

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

Not all OAuth use cases involve persistent grants. For more information, see Transient grants and persistent grants.

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

This REST resource accepts the GET for retrieval methods, and DELETE for revocation methods. The results are formatted in JSON.

Parameter
Parameter Description

grantId

The persistent grant identifier 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.
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 adminscope. The client then obtained an access token with the scope from PingFederate. The issued access token is a self-contained JSON web token (JWT).

This sample request illustrates a GET request from the client. The client 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.

To use a demonstrating proof-of-possession (DPoP)-bound access token, use the DPoP authentication scheme in the Authorization header and include a DPoP Proof JWT in the DPoP header. For more information, see the OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer specification and the description of the PingFederate DPoP settings in Configuring authorization server settings.
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 through this endpoint in the runtime-api.log file. While the events themselves are not configurable, you can 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.