Getting started


Authentication and authorization

Requesters can authenticate using any of two authentication types, and the requester may have either a privileged or unprivileged identity that determines the activity scope.

Authentication types

The Consent API supports the following authentication types:

  • Basic authentication

    Requests are authenticated using encoded user credentials contained in the Authorization header. The user credentials may be collected interactively from the user, or they may represent the client itself. Here is a sample:

    GET /consent/v1/definitions/cats?expand=localizations HTTP/1.1
    Authorization: Basic dWlkPXVzZXIuMCxvdT1wZW9wbGUsZGM9ZXhhbXBsZSxkYz1jb206cGFzc3dvcmQ=
  • Bearer token

    Requests are authenticated using an access token contained in the Authorization header. The access token is obtained through an authorization server, such as PingFederate. Here is a sample:

    GET /consent/v1/definitions/cats?expand=localizations HTTP/1.1
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtp...

When bearer token authentication is used, the access token used must include a scope that the Consent Service is configured to accept. Additionally, the Consent Service may be configured to require that the access token include a specific audience claim.

Identity types

When a request uses basic authentication, the Consent Service maps the basic authentication username to a user DN in the directory. It then uses this DN, called the request DN or auth DN, to determine whether the client should be considered privileged or unprivileged.

When a request uses bearer token authentication, the Consent Service maps the access token’s subject claim to a user DN in the directory. This DN is called the request DN or auth DN. The Consent Service then checks the scopes contained in the bearer token to determine whether the client should be considered privileged or unprivileged.

  • Privileged

    The requester can create, search, read, modify, or delete any consent record. A privileged requester is typically an administrator or an application service account, therefore it is not expected to match the subject or actor of the consent. For cases in which the actor and the subject differ, a privileged requester must be used. The Consent Service does not have the ability to determine the relationships between different subjects and actors.

  • Unprivileged

    The requester can only create, search, read, or modify consent records where the auth DN matches the DN of the consent record’s subject. An unprivileged requester is always assumed to be the subject or an agent acting directly on the subject’s behalf. The subject and actor must be identical.

The privileged versus unprivileged identity types are used to prevent individuals from acting against any consent record but their own. It is important to note that how these identity types are configured determines the types of operations that the requester can perform. The following table summarizes common operations associated with identity types.

Operation Notes
Read, search, create, modify, and delete any consent record. Requester must be privileged.
Operate against a consent record whose subject or actor cannot be mapped to a DN. Requester must be privileged.
Set an actor value that differs from the subject value Requester must be privileged.
Create, read, search, or modify one’s own consent records. Requester can be unprivileged. The administrator must configure the Consent Service with a consent record identity mapper to support access by unprivileged requesters.

Test your authorization type

The following information illustrates how to construct a typical Consent API request.

Create the API request header

The API request header contains the authentication information you must provide to make a call to any Consent API resource. The Authorization parameter takes the user credentials or the full bearer token as its value, which contains the authorization information needed to access the requested resource.

The following sample shows the API request header (-H 'Authorization: Bearer) with a base64url-encoded bearer token as its parameter value.

curl -X "GET" "https://<server>/consent/v1/definitions" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

This request header also shows an additional parameter of note:

  • Content-Type

    In the header of a PUT or POST request, this parameter identifies the media type of the request data sent to the server. For most Consent API calls, the Content-Type is application/json.

Create the API request body

The API request body for POST, PATCH, or PUT requests provides the attribute values needed to complete the create or update operation. For example, to update a consent record, the PUT operation requires values for the attr1 and attr2 attributes in the request body:

{
  "attr1": "value1",
  "attr2": "value2"
}

Run the API test

You can use the Consent API to return a list of consent definitions.

The following sample shows the GET /definitions operation to return a list of all consent definitions and their attributes.

curl -X GET "https://<server>/consent/v1/definitions" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

In the request header, the Bearer jwtToken value is your full base64url-encoded token generated by the authentication service. If your token is valid, the API request returns a 200: Successful operation message, and the response data lists all consent definitions.

This GET request does not require a request body. The response returns the list of consent definitions.

{
  "_links": {
    "self": {
      "href": "https://<server>/consent/v1/definitions"
    }
  },
  "_embedded": {
    "definitions": [
      {
        "id": "share-my-email",
        "displayName": "ShareEmail"
        "_links": {
          "self": {
            "href": "https://<server>/consent/v1/definitions/share-my-email"
         }
        }
      }
    ]
  }
  "size": 1,
  "count": 1,
}