Skip to content
This repository has been archived by the owner on Dec 5, 2023. It is now read-only.

Integration Guide

Jump to bottom
Alvaro Villanueva edited this page Nov 29, 2021 · 20 revisions

The following Wiki page serves as an Integration Guide for Client Applications willing to utilize the proxy protection and resource platform for the policy enforcement point.

Concepts and Approach

All endpoints described in this Integration Guide can be found in the following available discovery documents:

  • OIDC Endpoints
https://<HOSTNAME>/.well-known/openid-configuration
  • UMA Endpoints:
https://<HOSTNAME>/.well-known/uma2-configuration

Proxy and UMA Flows Endpoint

In order to interact with this service, it is necessary to first register a resource, with the content of the resource url to protect, through the resource registration endpoint. The proxy afterwards will automatically check the existence of that resource in the Mongo database and decide whether or not the user has access to it. The proxy maps all possibe REST methods redirecting its call to the protected service

.Example:

curl https://<HOSTNAME> -d <data> -H 'Content-Type: application/json, Authorization: Bearer <id_token>'

Authorize Endpoint

Introduced with v1.0, the PEP can be configured as solely an authorization API, intended to be called by an external nginx instance. In this mode, the PEP will validate rpt in received calls and generate ticket responses for UMA flow, but will defer the proxying functions to the nginx instance.

.Example:

curl https://<HOSTNAME>/authorize -d <data> -H 'Content-Type: application/json, Authorization: Bearer <id_token>'

Resources Endpoint

In order to interact with the resources, it is mandatory to provide an Authenticated user by giving an ID_TOKEN. The endponint will recive any REST request in order to insert, delete, update resources and some mandatory parameters such as:

Resources Endpoint/resources

Resources Endpoint (GET): /resources

  • Parameters:
  • headers: The response will be a json format so the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 200: List of resources stored and which the user has access.
  • Example:
curl -XGET https://<HOSTNAME>/resources -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint (HEAD): /resources

  • Parameters:
  • headers: The response will only contain headers, but the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 200: Headers returned from the service, no body included.
  • Example:
curl -I https://<HOSTNAME>/resources -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint (GET): /resources?path=

  • Parameters:
  • headers: The response will be a json format so the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Args:
  • path: The reverse match url can be specified as an argument in the url to return the matched resource of that value.
  • Response:
  • 200: List of resources stored and which the user has access.
  • Example:
curl -XGET https://<HOSTNAME>/resources?path=<PATH> -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint (POST): /resources

In order to register new resources the registrator must be Operator, otherwise the decision will be based on which is the owner of the resource with the previous subpath of the 'icon_uri' value. (i.e. As user I want to register /user/my/resource, I will be allowed only if /user/my is registered to my UID or just /user)

  • Parameters:
  • payload: JSON format with resource content
  • headers: The response will be a json format so the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 200: JSON format with resource data
  • Example:
curl -XPOST https://<HOSTNAME>/resources -d '{ "resource_scopes":[ "Authenticated"], "icon_uri": "/test", "name":"Test Service"}' -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint/resources/<resource_id>

Resources Endpoint (GET): /resources/<resource_id>

  • Parameters:
  • headers: The response will be a json format so the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 200: JSON format of the resource asked
  • Example:
curl -XGET https://<HOSTNAME>/resources/<resource_id> -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint (HEAD): /resources/<resource_id>

  • Parameters:
  • headers: The response will only contain headers, but the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 200: Headers returned from the service, no body included.
  • Example:
curl -I https://<HOSTNAME>/resources/<resource_id> -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint (POST): /resources/<resource_id>

The resource specified will be updated with the content within the payload

  • Parameters:
  • payload: JSON format with resource content
  • headers: The response will be a json format so the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 200: JSON format with resource data
  • Example:
curl -XPOST https://<HOSTNAME>/resources/<resource_id> -d '{ "resource_scopes":[ "Authenticated"], "icon_uri": "/test", "name":"Test Service"}' -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint (PATCH): /resources/<resource_id>

The resource specified will be updated with the content within the payload. Currently, PATCH works the same as POST, with same call requirements.

  • Parameters:
  • payload: JSON format with resource content
  • headers: The response will be a json format so the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 200: JSON format with resource data
  • Example:
curl --request PATCH https://<HOSTNAME>/resources/<resource_id> -d '{ "resource_scopes":[ "Authenticated"], "icon_uri": "/test", "name":"Test Service"}' -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

Resources Endpoint (DELETE): /resources/<resource_id>

  • Parameters:
  • headers: The response will be a json format so the Content-Type must be set to application/json and the Authorization must include an ID_TOKEN from the user
  • Response:
  • 204
  • Example:
curl -XDELETE https://<HOSTNAME>/resources/<resource_id> -H 'Content-Type: application/json, Authorization: Bearer <ID_TOKEN>'

⏭️ Next step: Access Enforcement

Clone this wiki locally