OAuth Consent Management Service

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

The OAuth consent management service enables retrieval and revocation of consent and their associated attributes on a per-client or per-resource owner basis.

Beginning with PingFederate 12.1, the authorizationDetails JSON field in responses from this endpoint has been deprecated in favor of the authorizationDetail and authroizationDetailDescription fields.

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.

Before using this endpoint, go to System → OAuth Settings → Authorization Server Settings and select the Bypass Authorization for Previously Approved Consents check box.

The endpoint will not return consents unless this option is enabled.

Endpoints

Manage by client: /pf-ws/rest/oauth/clients/<clientId>/consents<consentId>]
Manage by user (based on the USER_KEY value): /pf-ws/rest/oauth/users/<userKey>/consents<consentId>]
Parameters

Parameter Description

clientId

The client ID for which to retrieve or revoke consents.

Required to manage consents for a specific client.

userKey

The USER_KEY value for which to retrieve or revoke consents.

Required to manage consents for a specific resource owner.

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

consentId (optional)

The consentId of the consent to revoke or for which to retrieve the specific details.

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

If this parameter is not specified, the request applies to all consents 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

Sample request

A request to retrieve all consents for a client with an ID value of ac_oic_client.

GET /pf-ws/rest/oauth/clients/ac_oic_client/consents HTTP/1.1
Host: localhost:9031
Authorization: Basic YWRtaW46MkZlZGVyYXRl
X-XSRF-HEADER: PingFederate

Sample response

{
  "items": [
    {
      "id": "JDu17McN2ZFDANnHKtpATmrKjHISDVpW",
      "userKey": "asmith",
      "scope": "openid",
      "clientId": "ac_oic_client",
      "created": "2023-12-04T20:05:10.000Z",
      "updated": "2023-12-04T20:05:10.000Z"
    },
    {
      "id": "d1fGI9yFwRJrsxurEw0fX7WMFX22uoEW",
      "userKey": "asmith",
      "scope": "profile",
      "clientId": "ac_oic_client",
      "created": "2023-12-04T20:05:10.000Z",
      "updated": "2023-12-04T20:05:10.000Z"
    }
  ]
}

Return codes
Code	Description
`200`	Success
`204`	Success with no content returned Returned when revoking a consent.
`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 consent 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.

PingFederate Server

OAuth Consent Management Service

Endpoints

Logging