PingAuthorize

Searching for consent granted by resource owner to requestor

Using the resource owner information from the Users identifier from the URL attribute, we need to determine what consent the owner has granted to a given requestor.

About this task

This task is useful for:

  • Resource sharing or delegation where consent is granted to an individual (based on the collaborator claim)

  • Data sharing where consent is granted to a third party (based on the audience claim)

This task uses the Trust Framework HTTP service to pull a claim from a request.

Steps

  1. Make sure you understand the body of the request that you are pulling a claim from.

    The following Postman image shows a request being made to a directory server. The consent definition is in the request URL and has the form share-meme-game-answers&subject=user.0&collaborator=user.1. The resource owner is given by the subject, and the person being shared with is given by the collaborator.

    We use the Consent Admin account for the service. In Postman, for Authorization, we use Basic Auth with the username Consent Admin and its password.

    The consent record is for the PingDirectory Consent API, but you can use other consent stores. We use this consent record to determine who a resource owner has given consent to.

    Screen capture of Postman that shows a request with a consent in the body

  2. Copy the request URL to use in defining a Trust Framework service in the Policy Editor.

  3. Sign on to the Policy Editor.

  4. Create Trust Framework attributes for the Consent Admin account credentials.

    This is the Consent Admin account we used with Postman. We will create attributes for the username and password and then use those attributes when we define the Trust Framework HTTP service.

    1. Go to Trust Framework and click Attributes.

    2. From the menu, select Add new Attribute.

    3. For the name, replace Untitled with ConsentService and click Save changes.

      This attribute will serve as a parent to the username and password attributes and will help organize the attributes.

    4. From the menu, select Add new Attribute.

      Because the ConsentService attribute is selected, the new attribute is a child to it.

    5. For the name, replace Untitled with Username, set Default value to Consent Admin, select the Secret option, and then click Save changes.

      The following image shows this configuration.

      Screen capture that shows the Username attribute, configured as specified

    6. From the menu, select Add new Attribute.

    7. For the name, replace Untitled with Password, set Default value to Consent Admin, select the Secret option, and then click Save changes. Selecting the Secret option keeps the item out of logs.

  5. Create the HTTP service.

    1. Click Services along the top.

    2. From the menu, select Add new Service.

    3. For the name, replace Untitled with Search for consent to share game answers.

    4. Set Service Type to HTTP.

    5. Set URL to the request URL.

      In this case, the URL is https://pingdirectory:18443/consent/v1/consents?definition=share-meme-game-answers&subject=user.0&collaborator=user.1.

    6. Set Authentication to Basic.

      This setting requires a username and password. We will use the attributes we just created.

      1. Set Username to ConsentService.Username.

      2. Set Password to ConsentService.Password.

    7. This setup uses a self-signed certificate, so set Server (TLS) to No Validation.

      This case is for a development environment only. Do not use this setting for other environments.

    8. Under Value Settings, set Type to JSON.

      The following image shows this configuration.

      Screen capture of the new HTTP service, configured as specified

    9. Click Save changes.

  6. Test the service.

    1. Click Test above the Search for consent to share game answers service name.

    2. Click Execute.

      The results should include a consents array.

      Screen capture that shows a test result that starts with \{

      So the service works with hard-coded values: subject=user.0&collaborator=user.1. We need to use parameters in place of the subject and collaborator values so that the service works for anyone using the API.

  7. Click Details above the service name to update the service definition to replace the values with parameters.

    1. In the URL field, replace the collaborator value, which is user.1. Delete user.1 and type two open curly braces (\{\{). Use the pop-up that appears to choose the HttpRequest.AccessToken.subject attribute. Recall from Getting the requestor identifier from the access token that this attribute specifies the requestor. The resource owner must have a consent record for the requestor to grant access.

      With this change, the URL changes from

      https://pingdirectory:18443/consent/v1/consents?definition=share-meme-game-answers&subject=user.0&collaborator=user.1

      to

      https://pingdirectory:18443/consent/v1/consents?definition=share-meme-game-answers&subject=user.0&collaborator=\{\{HttpRequest.AccessToken.subject}}

    2. Click Save changes.

    3. Test the change by clicking Test, in the Request section, setting Attributes to HttpRequest.AccessToken.subject, specifying a value such as \{"sub":"user.1"}, where user.1 has a consent record in your consent store, and clicking Execute.

      The result should include a consents array. Repeat the step for a user who does not have a consent record to verify that those results do not include a consents array.

    4. Click Details to replace the subject value with a parameter.

      The subject is the resource owner. Recall from Getting a path component from the request URL that we have that information in the Users identifier from the URL attribute. Using curly braces to interpolate that attribute, the URL becomes:

      https://pingdirectory:18443/consent/v1/consents?definition=share-meme-game-answers&subject=\{\{Users identifier from the URL}}&collaborator=\{\{HttpRequest.AccessToken.subject}}

    5. Click Save changes.

    6. Test this change the same way you tested the previous change: using two users, where one has a consent record and one does not.

      In the Overrides section, set Attributes to Users identifier from the URL with the value specifying the resource owner, which is user.0 in this case.

  8. Update the service to pull only the first consent record from the response instead of the entire response.

    The response starts with

    \{"_embedded":\{"consents":[\{_links":"localization":

    We want to pull the first consent record for the user, which starts after the square bracket ([).

    1. Click Details to return to the service definition.

    2. Click the next to Value Processors and click Add Processor.

    3. Set Processor to JSON Path with a value of $._embedded.consents[0].

    4. Set Value type to JSON.

      For an example, see the following image.

      Screen capture that shows the value processor using a JSON Path statement, $._embedded.consents[0,role=

    5. Click Save changes.

    6. Test the change by clicking Test, in the Request section, setting Attributes to HttpRequest.AccessToken.subject, and specifying a value such as {"sub":"user.1"}, where user.1 has a consent record in your consent store. Then in the Overrides section, set Attributes to Users identifier from the URL with the value specifying user.0 again, and click Execute.

Result

The service returns only the user’s first consent record. With the record isolated, you can pull the given requestor’s status from the record.