Rate this page

OAuth 2 Consent

OAuth 2 scopes authorized through the Data Governance Broker’s authorization endpoint may be configured on a per-application basis to require user consent. Consent records and the history of their approval or denial may be viewed and managed through the OAuth 2 consent and consentHistory sub-resources.

The following table describes the fields of a single consent history resource.

Field Type Provided? Description
schemas array always The SCIM schema of the consent history resource. Always has the value urn:pingidentity:scim:api:messages:2.0:consentHistory.
meta complex always Will always contain a resourceType sub-attribute with the value Consent History. Will always contain a location attribute with the consent resource’s canonical URI. Will always contain a created attribute with the time that the consent record was created.
client complex always The client (application) associated with this consent resource. The fields of this object are described below.
scopes array The scopes granted or denied to this application. Fields are described below.

The following table describes the fields of a single consent resource.

Field Type Provided? Description
schemas array always The SCIM schema of the consent resource. Always has the value urn:pingidentity:scim:api:messages:2.0:consent.
meta complex always Will always contain a resourceType sub-attribute with the value Consent. Will always contain a location attribute with the consent resource’s canonical URI. Will always contain a lastModified attribute with the last time that consent was updated for this client.
client complex always The client (application) associated with this consent resource. The fields of this object are described below.
scopes array The scopes granted or denied to this application. Fields are described below.

The following table describes the fields of a client object.

Field Type Provided? Description
name string always The application name.
description string A description of the application.
url string The application URL.
iconUrl string The application icon URL.
emailAddress string The contact address.

The following table describes the fields of a scope object.

Field Type Provided? Description
name string always The scope name.
description string always An administrative description of the scope.
consentPromptText string always A user-facing description of the scope.
consent string always The scope access granted by the end user to this application. Possible values are granted, denied, and revoked.

GET /scim/v2/Users/{id}/consentHistory

GET /scim/v2/Me/consentHistory

The consent history sub-resource provides a log of consent events that have been recorded as a result of client authorization activity with a particular end user.

The response is formatted as a list response containing zero or more matching consent history resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request:

GET /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 1203
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:30:01 GMT

{
    "Resources": [
        {
            "client": {
                "name": "Test1", 
                "url": "https://example.com"
            }, 
            "id": "1465938753280", 
            "meta": {
                "created": "2016-06-14T21:12:33.280Z", 
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory/1465938753280", 
                "resourceType": "Consent History"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consentHistory"
            ], 
            "scopes": [
                {
                    "consent": "granted", 
                    "consentPromptText": "View your email address.", 
                    "description": "OpenID Connect email scope", 
                    "name": "email"
                }, 
                {
                    "consent": "granted", 
                    "consentPromptText": "Manage your OpenID Connect data.", 
                    "description": "OpenID Connect required scope.", 
                    "name": "openid"
                }
            ]
        }, 
        {
            "client": {
                "name": "Test1", 
                "url": "https://example.com"
            }, 
            "id": "1465939750355", 
            "meta": {
                "created": "2016-06-14T21:29:10.355Z", 
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory/1465939750355", 
                "resourceType": "Consent History"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consentHistory"
            ], 
            "scopes": [
                {
                    "consent": "denied", 
                    "consentPromptText": "View your postal address.", 
                    "description": "OpenID Connect address scope", 
                    "name": "address"
                }
            ]
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 2
}

GET /scim/v2/Users/{id}/consentHistory?filter={filter}

GET /scim/v2/Me/consentHistory?filter={filter}

A client may filter for a single user’s matching consent history events by performing a GET and providing a filter query parameter. Pagination parameters may also be provided. The filter format is described in the Searching section.

The response is formatted as a list response containing zero or more matching consent history resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request using the filter scopes.consent eq "denied":

GET /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory?filter=scopes.consent%20eq%20%22denied%22 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT...
Content-Length: 42
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 582
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:50:35 GMT

{
    "Resources": [
        {
            "client": {
                "name": "Test1", 
                "url": "https://example.com"
            }, 
            "id": "1465939750355", 
            "meta": {
                "created": "2016-06-14T21:29:10.355Z", 
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory/1465939750355", 
                "resourceType": "Consent History"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consentHistory"
            ], 
            "scopes": [
                {
                    "consent": "denied", 
                    "consentPromptText": "View your postal address.", 
                    "description": "OpenID Connect address scope", 
                    "name": "address"
                }
            ]
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 1
}

Search a user’s consent history (POST)

POST /scim/v2/Users/{id}/consentHistory/.search

POST /scim/v2/Me/consentHistory/.search

A client may filter for a single user’s matching consent history events by performing a POST against the special .search endpoint and providing a filter value. Pagination directives may also be provided. The filter format is described in the Searching section.

The response is formatted as a list response containing zero or more matching consent history resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request using the filter scopes.consent eq "denied":

POST /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory/.search HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT...
Content-Type: application/scim+json
Host: example.com:443

{
    "filter": "scopes.consent eq \"denied\""
}

Example response:

HTTP/1.1 200 OK
Content-Length: 582
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:50:35 GMT

{
    "Resources": [
        {
            "client": {
                "name": "Test1",
                "url": "https://example.com"
            },
            "id": "1465939750355",
            "meta": {
                "created": "2016-06-14T21:29:10.355Z",
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory/1465939750355",
                "resourceType": "Consent History"
            },
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consentHistory"
            ],
            "scopes": [
                {
                    "consent": "denied",
                    "consentPromptText": "View your postal address.",
                    "description": "OpenID Connect address scope",
                    "name": "address"
                }
            ]
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1
}

GET /scim/v2/Users/{id}/consentHistory/{eventId}

GET /scim/v2/Me/consentHistory/{eventId}

A specific consent history event may be requested by specifying its ID in the request path.

Example request:

GET /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory/1465939750355 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT_FZ...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 484
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:38:53 GMT

{
    "client": {
        "name": "Test1", 
        "url": "https://example.com"
    }, 
    "id": "1465939750355", 
    "meta": {
        "created": "2016-06-14T21:29:10.355Z", 
        "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consentHistory/1465939750355", 
        "resourceType": "Consent History"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:consentHistory"
    ], 
    "scopes": [
        {
            "consent": "denied", 
            "consentPromptText": "View your postal address.", 
            "description": "OpenID Connect address scope", 
            "name": "address"
        }
    ]
}

GET /scim/v2/Users/{id}/consents

GET /scim/v2/Me/consents

The consents sub-resource provides a per-application list of consents that have been recorded for a particular end user. Each consent record details the scopes that have been requested by a particular application and each scope’s current state.

The response is formatted as a list response containing zero or more matching consent resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

A client may also filter for matching consent history events by providing a filter query parameter, as described in the Searching section.

Example request:

GET /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 1235
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:54:20 GMT

{
    "Resources": [
        {
            "client": {
                "name": "Test1", 
                "url": "https://example.com"
            }, 
            "id": "Test1", 
            "meta": {
                "lastModified": "2016-06-14T21:29:10.355Z", 
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/Test1", 
                "resourceType": "Consent"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consent"
            ], 
            "scopes": [
                {
                    "consent": "granted", 
                    "consentPromptText": "View your email address.", 
                    "description": "OpenID Connect email scope", 
                    "name": "email"
                }, 
                {
                    "consent": "granted", 
                    "consentPromptText": "Manage your OpenID Connect data.", 
                    "description": "OpenID Connect required scope.", 
                    "name": "openid"
                }, 
                {
                    "consent": "denied", 
                    "consentPromptText": "View your postal address.", 
                    "description": "OpenID Connect address scope", 
                    "name": "address"
                }
            ]
        }, 
        {
            "client": {
                "name": "Test2"
            }, 
            "id": "Test2", 
            "meta": {
                "lastModified": "2016-06-14T21:54:14.902Z", 
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/Test2", 
                "resourceType": "Consent"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consent"
            ], 
            "scopes": [
                {
                    "consent": "granted", 
                    "consentPromptText": "View your email address.", 
                    "description": "OpenID Connect email scope", 
                    "name": "email"
                }
            ]
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 2
}

GET /scim/v2/Users/{id}/consents?filter={filter}

GET /scim/v2/Me/consents?filter={filter}

A client may filter for a single user’s matching consent records by performing a GET and providing a filter query parameter. Pagination parameters may also be provided. The filter format is described in the Searching section.

The response is formatted as a list response containing zero or more matching consent resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request the filter scopes.consent eq "denied":

GET /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents?filter=scopes.consent%20eq%20%22denied%22 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT_FZ...
Content-Length: 42
Content-Type: application/scim+json

Example response:

HTTP/1.1 200 OK
Content-Length: 818
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:58:13 GMT

{
    "Resources": [
        {
            "client": {
                "name": "Test1", 
                "url": "https://example.com"
            }, 
            "id": "Test1", 
            "meta": {
                "lastModified": "2016-06-14T21:29:10.355Z", 
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/Test1", 
                "resourceType": "Consent"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consent"
            ], 
            "scopes": [
                {
                    "consent": "granted", 
                    "consentPromptText": "View your email address.", 
                    "description": "OpenID Connect email scope", 
                    "name": "email"
                }, 
                {
                    "consent": "granted", 
                    "consentPromptText": "Manage your OpenID Connect data.", 
                    "description": "OpenID Connect required scope.", 
                    "name": "openid"
                }, 
                {
                    "consent": "denied", 
                    "consentPromptText": "View your postal address.", 
                    "description": "OpenID Connect address scope", 
                    "name": "address"
                }
            ]
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 1
}

Search a user’s consent records (POST)

POST /scim/v2/Users/{id}/consents/.search

POST /scim/v2/Me/consents/.search

A client may filter for a single user’s matching consent records by performing a POST against the special .search endpoint and providing a filter value. Pagination directives may also be provided. The filter format is described in the Searching section.

The response is formatted as a list response containing zero or more matching consent resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request the filter scopes.consent eq "denied":

POST /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/.search HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT_FZ...
Content-Type: application/scim+json

{
    "filter": "scopes.consent eq \"denied\""
}

Example response:

HTTP/1.1 200 OK
Content-Length: 818
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:58:13 GMT

{
    "Resources": [
        {
            "client": {
                "name": "Test1",
                "url": "https://example.com"
            },
            "id": "Test1",
            "meta": {
                "lastModified": "2016-06-14T21:29:10.355Z",
                "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/Test1",
                "resourceType": "Consent"
            },
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:consent"
            ],
            "scopes": [
                {
                    "consent": "granted",
                    "consentPromptText": "View your email address.",
                    "description": "OpenID Connect email scope",
                    "name": "email"
                },
                {
                    "consent": "granted",
                    "consentPromptText": "Manage your OpenID Connect data.",
                    "description": "OpenID Connect required scope.",
                    "name": "openid"
                },
                {
                    "consent": "denied",
                    "consentPromptText": "View your postal address.",
                    "description": "OpenID Connect address scope",
                    "name": "address"
                }
            ]
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1
}

GET /scim/v2/Users/{id}/consents/{clientName}

GET /scim/v2/Me/consents/{clientName}

A single consent record may be retrieved by specifying a client name in the request path. Note that this is the client’s configured display name, not its client ID. This record lists the current consent state for all scopes that the client has requested.

Example request:

GET /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/Test2 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 416
Content-Type: application/scim+json
Date: Tue, 14 Jun 2016 21:54:44 GMT
Server: Jetty(9.2.14.v20151106)

{
    "client": {
        "name": "Test2"
    }, 
    "id": "Test2", 
    "meta": {
        "lastModified": "2016-06-14T21:54:14.902Z", 
        "location": "https://example.com/scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/Test2", 
        "resourceType": "Consent"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:consent"
    ], 
    "scopes": [
        {
            "consent": "granted", 
            "consentPromptText": "View your email address.", 
            "description": "OpenID Connect email scope", 
            "name": "email"
        }
    ]
}

DELETE /scim/v2/Users/{id}/consents/{clientName}

DELETE /scim/v2/Me/consents/{clientName}

A single consent record may be deleted by specifying a client name in the request path. Note that this is the client’s configured display name, not its client ID.

For any currently granted scopes, this effectively causes the application’s access to be revoked.

Example request:

DELETE /scim/v2/Users/61feae3f-d03f-42d4-b460-f1e1da9352b5/consents/Test2 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer AXDMUqDPh1gT...
Content-Length: 0
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 204 No Content
Date: Tue, 14 Jun 2016 22:17:02 GMT