{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"8ddc19dc-bc5f-47a4-82a9-94640db14a62","name":"FIWARE PEP Proxy","description":"[![FIWARE Security](https://img.shields.io/badge/FIWARE-Security-ff7059.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABsAAAAVCAYAAAC33pUlAAAABHNCSVQICAgIfAhkiAAAA8NJREFUSEuVlUtIFlEUx+eO+j3Uz8wSLLJ3pBiBUljRu1WLCAKXbXpQEUFERSQF0aKVFAUVrSJalNXGgmphFEhQiZEIPQwKLbEUK7VvZrRvbr8zzjfNl4/swplz7rn/8z/33HtmRhn/MWzbXmloHVeG0a+VSmAXorXS+oehVD9+0zDN9mgk8n0sWtYnHo5tT9daH4BsM+THQC8naK02jCZ83/HlKaVSzBey1sm8BP9nnUpdjOfl/Qyzj5ust6cnO5FItJLoJqB6yJ4QuNcjVOohegpihshS4F6S7DTVVlNtFFxzNBa7kcaEwUGcbVnH8xOJD67WG9n1NILuKtOsQG9FngOc+lciic1iQ8uQGhJ1kVAKKXUs60RoQ5km93IfaREvuoFj7PZsy9rGXE9G/NhBsDOJ63Acp1J82eFU7OIVO1OxWGwpSU5hb0GqfMydMHYSdiMVnncNY5Vy3VbwRUEydvEaRxmAOSSqJMlJISTxS9YWTYLcg3B253xsPkc5lXk3XLlwrPLuDPKDqDIutzYaj3eweMkPeCCahO3+fEIF8SfLtg/5oI3Mh0ylKM4YRBaYzuBgPuRnBYD3mmhA1X5Aka8NKl4nNz7BaKTzSgsLCzWbvyo4eK9r15WwLKRAmmCXXDoA1kaG2F4jWFbgkxUnlcrB/xj5iHxFPiBN4JekY4nZ6ccOiQ87hgwhe+TOdogT1nfpgEDTvYAucIwHxBfNyhpGrR+F8x00WD33VCNTOr/Wd+9C51Ben7S0ZJUq3qZJ2OkZz+cL87ZfWuePlwRcHZjeUMxFwTrJZAJfSvyWZc1VgORTY8rBcubetdiOk+CO+jPOcCRTF+oZ0okUIyuQeSNL/lPrulg8flhmJHmE2gBpE9xrJNkwpN4rQIIyujGoELCQz8ggG38iGzjKkXufJ2Klun1iu65bnJub2yut3xbEK3UvsDEInCmvA6YjMeE1bCn8F9JBe1eAnS2JksmkIlEDfi8R46kkEkMWdqOv+AvS9rcp2bvk8OAESvgox7h4aWNMLd32jSMLvuwDAwORSE7Oe3ZRKrFwvYGrPOBJ2nZ20Op/mqKNzgraOTPt6Bnx5citUINIczX/jUw3xGL2+ia8KAvsvp0ePoL5hXkXO5YvQYSFAiqcJX8E/gyX8QUvv8eh9XUq3h7mE9tLJoNKqnhHXmCO+dtJ4ybSkH1jc9XRaHTMz1tATBe2UEkeAdKu/zWIkUbZxD+veLxEQhhUFmbnvOezsJrk+zmqMo6vIL2OXzPvQ8v7dgtpoQnkF/LP8Ruu9zXdJHg4igAAAABJRU5ErkJgggA=)](https://www.fiware.org/developers/catalogue/)\n\n\nThis tutorial uses the FIWARE [Wilma](https://fiware-pep-proxy.rtfd.io/) PEP Proxy combined with **Keyrock** to secure access to endpoints exposed by\nFIWARE generic enablers. Users (or other actors) must log-in and use a token to gain access to services. The application\ncode created in the [previous tutorial](https://github.com/Fiware/tutorials.Securing-Access) is expanded to authenticate\nusers throughout a distributed system. The design of FIWARE Wilma - a PEP Proxy is discussed, and the parts of the\nKeyrock GUI and REST API relevant to authenticating other services are described in detail.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.PEP-Proxy/icon/GitHub-Mark-32px.png) [FIWARE 404: Securing Microservices with a PEP Proxy](https://github.com/Fiware/tutorials.PEP-Proxy)\n\n\n# Securing Microservices with a PEP Proxy\n\n> \"Oh, it's quite simple. If you are a friend, you speak the password, and the doors will open.\"\n>\n>  — Gandalf (The Fellowship of the Ring by J.R.R Tolkien)\n\nThe [previous tutorial](https://github.com/Fiware/tutorials.Securing-Access) demonstrated that it is possible to Permit or Deny access\nto resources based on an authenticated user identifying themselves within an application.  It was simply a matter of the code following\na different line of execution if the `access_token` was not found (Level 1 - *Authentication Access*), or confirming that a given `access_token`\nhad appropriate rights (Level  2 - *Basic Authorization*). The same method of securing access can be applied by placing a Policy Enforcement\nPoint (PEP) in front of other services within a FIWARE-based Smart Solution.\n\nA **PEP Proxy** lies in front of a secured resource  and is an endpoint found at \"well-known\" public location. It serves\nas a gatekeeper for resource access. Users or other actors must supply sufficient information to the **PEP Proxy** to allow their request\nto succeed and pass through the **PEP proxy**. The **PEP proxy** then passes the request on to the real location of the\nsecured resource itself - the actual location of the secured resource is unknown to the outside user - it could be held\nin a private network behind the **PEP proxy** or found on a different machine altogether.\n\nFIWARE [Wilma](https://fiware-pep-proxy.rtfd.io/) is a simple implentation of a **PEP proxy** designed to work with the FIWARE [Keyrock](http://fiware-idm.readthedocs.io/) Generic Enabler. Whenever a user tries to gain access to the resource behind the **PEP proxy**, the\nPEP will describe the user's attributes to the Policy Decision Point (PDP), request a security decision, and enforce the decision.\n(Permit or Deny). There is mimimal disruption of access for authorized users  - the response received is the same as if they had\naccessed the secured service directly. Unauthorized users are simply returned a **401 - Unauthorized** response.\n\n\n## Standard Concepts of Identity Management\n\nThe following common objects are found with the **Keyrock** Identity Management database:\n\n* **User** - Any signed up user able to identify themselves with an eMail and password. Users can be assigned\n rights individually or as a group\n* **Application** -  Any securable FIWARE application consisting of a series of microservices\n* **Organization** - A group of users who can be assigned a series of rights. Altering the rights of the organization\n effects the access of all users of that organization\n* **OrganizationRole** - Users can either be members or admins of an organization - Admins are able to add and remove users\n from their organization, members merely gain the roles and permissions of an organization. This allows each organization\n to be responsible for their members and removes the need for a super-admin to administer all rights\n* **Role** - A role is a descriptive bucket for a set of permissions. A role can be assigned to either a single user\n or an organization. A signed-in user gains all the permissions from all of their own roles plus all of the roles associated\n to their organization\n* **Permission** - An ability to do something on a resource within the system\n\nAdditionally two further non-human application objects can be secured within a FIWARE application:\n\n* **IoTAgent** - a proxy between IoT Sensors and  the Context Broker\n* **PEPProxy** - a middleware for use between generic enablers challenging the rights of a user.\n\n\n The relationship between the objects can be seen below - the entities marked in red are used directly within this tutorial:\n\n![](https://fiware.github.io/tutorials.PEP-Proxy/img/entities.png)\n\n## Video : Introduction to Wilma PEP Proxy\n\n[![](http://img.youtube.com/vi/8tGbUI18udM/0.jpg)](https://www.youtube.com/watch?v=8tGbUI18udM \"Introduction\")\n\nClick on the image above to see an introductory video\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple both components will be run using [Docker](https://www.docker.com). **Docker** is a\ncontainer technology which allows to different components isolated into their respective environments.\n\n* To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n* To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n* To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Identity-Management/master/docker-compose.yml) is used\nconfigure the required services for the application. This means all container services can be brought up in a single\ncommand. Docker Compose is installed by default as part of Docker for Windows and  Docker for Mac, however Linux users\nwill need to follow the instructions found  [here](https://docs.docker.com/compose/install/)\n\n## Cygwin\n\nWe will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/) to provide a\ncommand line functionality similar to a Linux distribution on Windows.\n\n# Architecture\n\n\nThis application protects access to the existing Stock Management and Sensors-based application by adding PEP Proxy instances around the services created in previous tutorials and uses data pre-populated into the **MySQL** database used by **Keyrock**. It\nwill make use of four FIWARE components - the [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/),the [IoT Agent for UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/), the [Keyrock](http://fiware-idm.readthedocs.io/) Generic enabler\nand adds one or two instances [Wilma](https://fiware-pep-proxy.rtfd.io/) PEP Proxy dependent upon which interfaces are to be secured.\nUsage of the Orion Context Broker is sufficient for an application to qualify as *“Powered by FIWARE”*.\n\nBoth the Orion Context Broker and the IoT Agent rely on open source [MongoDB](https://www.mongodb.com/) technology to keep persistence of the information they hold. We will also be using the dummy IoT devices created in the [previous tutorial](https://github.com/Fiware/tutorials.IoT-Sensors/). **Keyrock** uses its own [MySQL](https://www.mysql.com/) database.\n\nTherefore the overall architecture will consist of the following elements:\n\n* The FIWARE [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n* The FIWARE [IoT Agent for UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/) which will receive southbound requests using [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) and convert them to  [UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) commands for the devices\n* FIWARE [Keyrock](http://fiware-idm.readthedocs.io/) offer a complement Identity Management System including:\n    * An OAuth2 authentication system for Applications and Users\n    * A website graphical front-end for Identity Management Administration\n    * An equivalent REST API for Identity Management via HTTP requests\n* FIWARE [Wilma](https://fiware-pep-proxy.rtfd.io/) is a PEP Proxy securing access to the **Orion** and/or **IoT Agent** microservices\n* The underlying [MongoDB](https://www.mongodb.com/) database :\n    * Used by the **Orion Context Broker** to hold context data information such as data entities, subscriptions and registrations\n    * Used by the **IoT Agent** to hold device information such as device URLs and Keys\n* A [MySQL](https://www.mysql.com/) database :\n    * Used to persist user identities, applications, roles and permissions\n* The **Stock Management Frontend** does the following:\n   * Displays store information\n   * Shows which products can be bought at each store\n   * Allows users to \"buy\" products and reduce the stock count.\n   * Allows authorized users into restricted areas\n* A webserver acting as set of [dummy IoT devices](https://github.com/Fiware/tutorials.IoT-Sensors) using the [UltraLight 2.0](http://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual) protocol running over HTTP - access to certain resources is restricted.\n\n\nSince all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports.\n\nThe specific architecture of each section of the tutorial is discussed below.\n\n\n# Start Up\n\nTo start the installation, do the following:\n\n```console\ngit clone git@github.com:Fiware/tutorials.PEP-Proxy.git\ncd tutorials.PEP-Proxy\n\n./services create\n```\n\n>**Note** The initial creation of Docker images can take up to three minutes\n\n\nThereafter, all services can be initialized from the command line by running the [services](https://github.com/Fiware/tutorials.PEP-PRoxy/blob/master/services) Bash script provided within the repository:\n\n```console\n./services <command>\n```\n\nWhere `<command>` will vary depending upon the exercise we wish to activate.\n\n>:information_source: **Note:** If you want to clean up and start over again you can do so with the following command:\n>\n>```console\n>./services stop\n>```\n>\n\n\n## Dramatis Personae\n\nThe following people at `test.com` legitimately have accounts within the Application\n\n* Alice, she will be the Administrator of the **Keyrock** Application\n* Bob, the Regional Manager of the supermarket chain - he has several store managers under him:\n  * Manager1\n  * Manager2\n* Charlie, the Head of Security of the supermarket chain - he has several store detectives under him:\n  * Detective1\n  * Detective2\n\n| Name       |eMail                       |Password |\n|------------|----------------------------|---------|\n| alice      | alice-the-admin@test.com   | `test`  |\n| bob        | bob-the-manager@test.com   | `test`  |\n| charlie    | charlie-security@test.com  | `test`  |\n| manager1   | manager1@test.com          | `test`  |\n| manager2   | manager2@test.com          | `test`  |\n| detective1 | detective1@test.com        | `test`  |\n| detective2 | detective2@test.com        | `test`  |\n\n\nThe following people at `example.com`  have signed up for accounts, but have no reason to be granted access\n\n* Eve - Eve the Eavesdropper\n* Mallory - Mallory the malicious attacker\n* Rob - Rob the Robber\n\n\n| Name       |eMail                       |Password |\n|------------|----------------------------|---------|\n| eve        | eve@example.com            | `test`  |\n| mallory    | mallory@example.com        | `test`  |\n| rob        | rob@example.com            | `test`  |\n\n\nTwo organizations have also been set up by Alice:\n\n| Name       | Description                         | UUID                                 |\n|------------|-------------------------------------|--------------------------------------|\n| Security   | Security Group for Store Detectives |`security-team-0000-0000-000000000000`|\n| Management | Management Group for Store Managers |`managers-team-0000-0000-000000000000`|\n\nOne application, with appropriate roles and permissions has also been created:\n\n| Key           | Value                                  |\n|---------------|----------------------------------------|\n| Client ID     | `tutorial-dckr-site-0000-xpresswebapp` |\n| Client Secret | `tutorial-dckr-site-0000-clientsecret` |\n| URL           | `http://localhost:3000`                |\n| RedirectURL   | `http://localhost:3000/login`          |\n\n\nTo save time, the data creating users and organizations from the [previous tutorial](https://github.com/Fiware/tutorials.Roles-Permissions) has been downloaded and is automatically persisted to the MySQL\ndatabase on start-up so the assigned UUIDs do not change and the data does not need to be entered again.\n\nThe **Keyrock** MySQL database deals with all aspects of application security including storing users, password etc; defining access rights and dealing with OAuth2 authorization protocols.\nThe complete database relationship diagram can be found [here](https://fiware.github.io/tutorials.Securing-Access/img/keyrock-db.png)\n\nTo refresh your memory about how to create users and organizations and applications, you can log in at `http://localhost:3005/idm`\nusing the account `alice-the-admin@test.com` with a password of `test`.\n\n![](https://fiware.github.io/tutorials.PEP-Proxy/img/keyrock-log-in.png)\n\nand look around.\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"513743","team":157450,"collectionId":"8ddc19dc-bc5f-47a4-82a9-94640db14a62","publishedId":"RWaHxUgP","public":true,"publicUrl":"https://documenter-api.postman.tech/view/513743/RWaHxUgP","privateUrl":"https://go.postman.co/documentation/513743-8ddc19dc-bc5f-47a4-82a9-94640db14a62","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF7059"},"documentationLayout":"classic-double-column","version":"8.11.4","publishDate":"2020-01-02T11:02:20.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/d7085d490b9144732c65203aa6e3b68b31884d1c33a86b8a00d15da75147ae33","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/RWaHxUgP"}