PingFederate Server

OAuth Access Grant Management Service

PingFederate includes a REST-based web service to manage OAuth persistent grants administratively.

The OAuth access grant management 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.

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

Applications must authenticate to this web service using HTTP Basic authentication and credentials validated through an instance of a Password Credential Validator (PCV). The PCV instance, in turn, must be selected in the OAuth authorization server (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 methods, and DELETE, for revocation methods. The results are formatted in 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.

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

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.

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. 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 System → OAuth Settings → [.wintitle] Authorization Server Settings** window.

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 Transient grants and persistent 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 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.