FIWARE PEP Proxy.postman_collection.json

{
	"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.1.0/collection.json"
	},
	"item": [
		{
			"name": "Logging In to Keyrock",
			"item": [
				{
					"name": "Create token with Password",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Accept",
								"value": "application/json",
								"disabled": true
							},
							{
								"key": "Content-Type",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n  \"name\": \"alice-the-admin@test.com\",\n  \"password\": \"test\"\n}"
						},
						"url": {
							"raw": "http://{{keyrock}}/v1/auth/tokens",
							"protocol": "http",
							"host": [
								"{{keyrock}}"
							],
							"path": [
								"v1",
								"auth",
								"tokens"
							]
						},
						"description": "The following example logs in using the Admin Super-User - it is the equivalent of using the log-in screen of the GUI.\n\nThe response header returns an `X-Subject-token` which identifies who has logged on the application.\nThis token is required in all subsequent requests to gain access."
					},
					"response": []
				},
				{
					"name": "Get token info",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							},
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "X-Auth-token",
								"value": "{{X-Auth-token}}"
							},
							{
								"key": "X-Subject-token",
								"value": "{{X-Subject-token}}"
							}
						],
						"url": {
							"raw": "http://{{keyrock}}/v1/auth/tokens",
							"protocol": "http",
							"host": [
								"{{keyrock}}"
							],
							"path": [
								"v1",
								"auth",
								"tokens"
							]
						},
						"description": "You can use the long-lasting  `X-Auth-token=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa` to pretend to be Alice throughout this\ntutorial. \n\nThe presence of a (time-limited) token is sufficient to find out more information about the user.\nTo find information about Bob, use the long-lasting token `X-Subject-token=bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb`\n\nThis request indicates that *the\nuser authorized with the token `{{X-Auth-token}}` (i.e Alice) is enquiring about the user holding the token  `{{X-Subject-token}}`* i.e Bob \n\nThe response will return the details of the associated user. As you can see Bob holds a long-lasting token until 2026."
					},
					"response": []
				}
			],
			"description": "Enter a username and password to enter the application. The default super-user has the values `alice-the-admin@test.com` and `test`. The URL `https://localhost:3443/v1/auth/tokens` should also work in a secure system.",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		},
		{
			"name": "Managing PEP Proxies and IoT Agents",
			"item": [
				{
					"name": "PEP Proxy CRUD Actions",
					"item": [
						{
							"name": "Create a PEP Proxy",
							"request": {
								"method": "POST",
								"header": [
									{
										"key": "Accept",
										"value": "application/json"
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"body": {
									"mode": "formdata",
									"formdata": []
								},
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/pep_proxies",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"pep_proxies"
									]
								},
								"description": "To create a new PEP Proxy account within an application , send a POST request to the `//v1/applications/{{application-id}}/pep_proxies` endpoint  along with the `X-Auth-token` header from a previously logged in administrative user.\n\nProvided there is no previously existing PEP Proxy account associated with the application, a new account will be created with a unique `id` and `password` and the values will be returned in the response."
							},
							"response": []
						},
						{
							"name": "Read PEP Proxy Details",
							"request": {
								"method": "GET",
								"header": [
									{
										"key": "Accept",
										"value": "application/json",
										"disabled": true
									},
									{
										"key": "Content-Type",
										"value": "application/json",
										"disabled": true
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/pep_proxies/",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"pep_proxies",
										""
									]
								},
								"description": "Making a GET request the `/v1/applications/{{application-id}}/pep_proxies/` endpoint will return the details of the associated PEP Proxy Account. The `X-Auth-token` must be supplied in the headers."
							},
							"response": []
						},
						{
							"name": "Reset Password of PEP Proxy",
							"request": {
								"method": "PATCH",
								"header": [
									{
										"key": "Accept",
										"value": "application/json",
										"disabled": true
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"body": {
									"mode": "formdata",
									"formdata": []
								},
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/pep_proxies",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"pep_proxies"
									]
								},
								"description": "To renew the password of a PEP Proxy Account, make a PATCH request to the  `/v1/applications/{{application-id}}/pep_proxies` endpoint will return the details of the associated PEP Proxy Account. The `X-Auth-token` must be supplied in the headers.\n\nThe response returns a new password."
							},
							"response": []
						},
						{
							"name": "Delete PEP Proxy",
							"request": {
								"method": "DELETE",
								"header": [
									{
										"key": "Accept",
										"value": "application/json"
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "Content-Type",
										"value": "{{Content-Type}}"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"body": {
									"mode": "formdata",
									"formdata": []
								},
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/pep_proxies",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"pep_proxies"
									]
								},
								"description": "An existing PEP Proxy Account can be deleted by making a DELETE request to the  `/v1/applications/{{application-id}}/pep_proxies` endpoint. The `X-Auth-token` must be supplied in the headers."
							},
							"response": []
						}
					],
					"description": "#### GUI\n\nOnce signed-in, users are able to create and update PEP Proxies associated to their applications for themselves.\n\n![](https://fiware.github.io/tutorials.PEP-Proxy/img/create-pep-proxy.png)\n\n#### REST API\n\nAlternatively, the standard CRUD actions are assigned to the appropriate HTTP verbs (POST, GET, PATCH and DELETE) under the `/v1/applications/{{application-id}}/pep_proxies` endpoint.\n",
					"event": [
						{
							"listen": "prerequest",
							"script": {
								"type": "text/javascript",
								"exec": [
									""
								]
							}
						},
						{
							"listen": "test",
							"script": {
								"type": "text/javascript",
								"exec": [
									""
								]
							}
						}
					]
				},
				{
					"name": "IoT Agent CRUD Actions",
					"item": [
						{
							"name": "Create an IoT Agent",
							"request": {
								"method": "POST",
								"header": [
									{
										"key": "Accept",
										"value": "application/json"
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "Content-Type",
										"value": "{{Content-Type}}"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"body": {
									"mode": "formdata",
									"formdata": []
								},
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/iot_agents",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"iot_agents"
									]
								},
								"description": "To create a new IoT Agent account within an application, send a POST request to the `/v1/applications/{{application-id}}/iot_agents` endpoint  along with the `X-Auth-token` header from a previously logged in administrative user.\n\nA new account will be created with a unique `id` and `password` and the values will be returned in the response."
							},
							"response": []
						},
						{
							"name": "Read IoT Agent details",
							"request": {
								"method": "GET",
								"header": [
									{
										"key": "Accept",
										"value": "application/json"
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/iot_agents/{{iot-agent-id}}",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"iot_agents",
										"{{iot-agent-id}}"
									]
								},
								"description": "Making a GET request the `/v1/applications/{{application-id}}/iot_agents/{{iot-agent-id}}` endpoint will return the details of the associated IoT Agent Account. The `X-Auth-token` must be supplied in the headers."
							},
							"response": []
						},
						{
							"name": "List of IoT Agents",
							"request": {
								"method": "GET",
								"header": [
									{
										"key": "Accept",
										"value": "application/json"
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/iot_agents",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"iot_agents"
									]
								},
								"description": "A list of all IoT Agents associated with an application can be obtained by making a GET request the `/v1/applications/{{application-id}}/iot_agents` endpoint. The `X-Auth-token` must be supplied in the headers."
							},
							"response": []
						},
						{
							"name": "Reset Password of IoT Agent",
							"request": {
								"method": "PATCH",
								"header": [
									{
										"key": "Accept",
										"value": "application/json",
										"disabled": true
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"body": {
									"mode": "formdata",
									"formdata": []
								},
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/iot_agents/{{iot-agent-id}}",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"iot_agents",
										"{{iot-agent-id}}"
									]
								},
								"description": "To renew the password of an individual IoT Agent Account, make a PATCH request to the  `/v1/applications/{{application-id}}//iot_agents/{{iot-agent-id}}` endpoint. \nThe `X-Auth-token` must be supplied in the headers.\n\nThe response returns a new password."
							},
							"response": []
						},
						{
							"name": "Delete an IoT Agent",
							"request": {
								"method": "DELETE",
								"header": [
									{
										"key": "Accept",
										"value": "application/json",
										"disabled": true
									},
									{
										"key": "Content-Type",
										"value": "application/json"
									},
									{
										"key": "X-Auth-token",
										"value": "{{X-Auth-token}}"
									}
								],
								"body": {
									"mode": "formdata",
									"formdata": []
								},
								"url": {
									"raw": "http://{{keyrock}}/v1/applications/{{application-id}}/iot_agents/{{iot-agent-id}}",
									"protocol": "http",
									"host": [
										"{{keyrock}}"
									],
									"path": [
										"v1",
										"applications",
										"{{application-id}}",
										"iot_agents",
										"{{iot-agent-id}}"
									]
								},
								"description": "An existing IoT Agent Account can be deleted by making a DELETE request to the  `/v1/applications/{{application-id}}/iot_agents/{{iot-agent-id}}` endpoint. \nThe `X-Auth-token` must be supplied in the headers."
							},
							"response": []
						}
					],
					"description": "#### GUI\n\nIn a similar manner to PEP Proxy creation, signed-in, users are able to create and update IoT Sensor Accounts associated to their \napplications.\n\n![](https://fiware.github.io/tutorials.PEP-Proxy/img/create-iot-sensor.png)\n\n#### REST API\n\nAlternatively, the standard CRUD actions are assigned to the ",
					"event": [
						{
							"listen": "prerequest",
							"script": {
								"type": "text/javascript",
								"exec": [
									""
								]
							}
						},
						{
							"listen": "test",
							"script": {
								"type": "text/javascript",
								"exec": [
									""
								]
							}
						}
					]
				}
			],
			"description": "User accounts have been created in a [previous tutorial](https://github.com/Fiware/tutorials.Identity-Management). Non-human\nactors such as a PEP Proxy can be set up in the same manner. The account for each PEP Proxy, IoT Agent or IoT Sensor will \nmerely consist of a Username and password linked to an application within Keyrock. PEP Proxy and IoT Agents accounts can\nbe created by using either the Keyrock GUI or by using the REST API.\n\n## Video : Wilma PEP Proxy Configuration\n\n[![](http://img.youtube.com/vi/b4sYU78skrw/0.jpg)](https://www.youtube.com/watch?v=b4sYU78skrw \"PEP Proxy Configuration\")\n\nClick on the image above to see a video about configuring the Wilma PEP Proxy using the **Keyrock** GUI\n\n## Managing PEP Proxies and IoT Agents - Start Up\n\nTo start the system run the following command:\n\n```console\n./services orion\n```\n\nThis will start up **Keyrock** with a series of users. There are already two existing applications \nand an existing PEP Proxy Account associated with the application.\n",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		},
		{
			"name": "Securing the Orion Context Broker",
			"item": [
				{
					"name": "PEP Proxy - No Access to Orion without an Access Token",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "X-Auth-Token",
								"value": "{{X-Access-token}}"
							}
						],
						"url": {
							"raw": "http://localhost:1027/v2/entities/",
							"protocol": "http",
							"host": [
								"localhost"
							],
							"port": "1027",
							"path": [
								"v2",
								"entities",
								""
							]
						},
						"description": "Secured Access can be ensured by requiring all requests to the secured service are made indirectly via a PEP Proxy (in this case the PEP Proxy is found in front of the Context Broker). Requests must include an `X-Auth-Token`, failure to present a valid token results in a denial of access.\n\nif a request to the PEP Proxy is made without any access token as shown, the response is a **401 Unauthorized** error code, with a text explanation."
					},
					"response": []
				},
				{
					"name": "Keyrock - User Obtains an Access Token",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Authorization",
								"value": "Basic {{Authorization}}",
								"description": "base64 concatenation of Client Id and Client Secret"
							},
							{
								"key": "Content-Type",
								"value": "application/x-www-form-urlencoded"
							},
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "username=alice-the-admin@test.com&password=test&grant_type=password"
						},
						"url": {
							"raw": "http://{{keyrock}}/oauth2/token",
							"protocol": "http",
							"host": [
								"{{keyrock}}"
							],
							"path": [
								"oauth2",
								"token"
							]
						},
						"description": "To log in to an application using the user-credentials flow send a POST request to the `oauth2/token` endpoint with the `grant_type=password`\n\nThe response returns an `access_code` to identify the user.\n\nAn `access_code` can also be done by entering the Tutorial Application on http:/localhost and logging in using any of the OAuth2 grants\non the page. A successful log-in will return an access token."
					},
					"response": []
				},
				{
					"name": "PEP Proxy - Accessing Orion with an Access Token",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "X-Auth-Token",
								"value": "{{X-Access-token}}"
							}
						],
						"url": {
							"raw": "http://localhost:1027/v2/entities/",
							"protocol": "http",
							"host": [
								"localhost"
							],
							"port": "1027",
							"path": [
								"v2",
								"entities",
								""
							]
						},
						"description": "If a request to the PEP Proxy is made including a valid access token in the `X-Auth-Token` header as shown, the request\nis permitted and the service behind the PEP Proxy (in this case the Orion Context Broker) will return the data as\nexpected."
					},
					"response": []
				},
				{
					"name": "PEP Proxy - Accessing Orion with a Bearer Auth Token",
					"request": {
						"auth": {
							"type": "bearer",
							"bearer": [
								{
									"key": "token",
									"value": "{{X-Access-token}}",
									"type": "string"
								}
							]
						},
						"method": "GET",
						"header": [
							{
								"key": "X-Auth-Token",
								"value": "{{X-Access-token}}",
								"disabled": true
							}
						],
						"url": {
							"raw": "http://localhost:1027/v2/entities/",
							"protocol": "http",
							"host": [
								"localhost"
							],
							"port": "1027",
							"path": [
								"v2",
								"entities",
								""
							]
						},
						"description": "The standard  `Authorization: Bearer` header can also be used to identity the user,\nthe request from an authorized user is permitted and the service behind the PEP Proxy (in this case the Orion Context Broker) will return the data as\nexpected."
					},
					"response": []
				},
				{
					"name": "PEP Proxy - Accessing Orion with an Access Token Copy",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "X-Auth-Token",
								"value": "{{X-Access-token}}"
							}
						],
						"url": {
							"raw": "http://localhost:1027/v2/entities/",
							"protocol": "http",
							"host": [
								"localhost"
							],
							"port": "1027",
							"path": [
								"v2",
								"entities",
								""
							]
						},
						"description": "If a request to the PEP Proxy is made including a valid access token in the `X-Auth-Token` header as shown, the request\nis permitted and the service behind the PEP Proxy (in this case the Orion Context Broker) will return the data as\nexpected."
					},
					"response": []
				}
			],
			"description": "![](https://fiware.github.io/tutorials.PEP-Proxy/img/pep-proxy-orion.png)\n\n## Securing Orion - PEP Proxy Configuration\n\nThe `orion-proxy` container is an instance of FIWARE **Wilma** listening on port `1027`, it is configured to forward traffic to\n`orion` on port `1026`, which is the default port that the Orion Context Broker is listening to for NGSI Requests.\n\n```yaml\n  orion-proxy:\n    image: fiware/pep-proxy\n    container_name: fiware-orion-proxy\n    hostname: orion-proxy\n    networks:\n      default:\n        ipv4_address: 172.18.1.10\n    depends_on:\n      - keyrock\n    ports:\n      - \"1027:1027\"\n    expose:\n      - \"1027\"\n    environment:\n      - PEP_PROXY_APP_HOST=orion\n      - PEP_PROXY_APP_PORT=1026\n      - PEP_PROXY_PORT=1027\n      - PEP_PROXY_IDM_HOST=keyrock\n      - PEP_PROXY_HTTPS_ENABLED=false\n      - PEP_PROXY_AUTH_ENABLED=false\n      - PEP_PROXY_IDM_SSL_ENABLED=false\n      - PEP_PROXY_IDM_PORT=3005\n      - PEP_PROXY_APP_ID=tutorial-dckr-site-0000-xpresswebapp\n      - PEP_PROXY_USERNAME=pep_proxy_00000000-0000-0000-0000-000000000000\n      - PEP_PASSWORD=test\n      - PEP_PROXY_PDP=idm\n      - PEP_PROXY_MAGIC_KEY=1234\n```\n\nThe `PEP_PROXY_APP_ID` and `PEP_PROXY_USERNAME` would usually be obtained by adding new entries to the application in **Keyrock**,\nhowever, in this tutorial, they have been pre-defined by populating the **MySQL** database with data on start-up.\n\nThe `orion-proxy` container is listening on a single port:\n\n* The PEP Proxy Port - `1027` is exposed purely for tutorial access - so that cUrl or Postman can requests directly to the **Wilma** instance\n  without being part of the same network. \n\n\n| Key |Value|Description|\n|-----|-----|-----------|\n| PEP_PROXY_APP_HOST |`orion` | The hostname of the service behind the PEP Proxy |\n| PEP_PROXY_APP_PORT |`1026` | The port of the service behind the PEP Proxy |\n| PEP_PROXY_PORT |`1027` | The port that the PEP Proxy is listening on |\n| PEP_PROXY_IDM_HOST | `keyrock`| The hostname for the Identity Manager |\n| PEP_PROXY_HTTPS_ENABLED | `false`| Whether the PEP Proxy itself is running under HTTPS |\n| PEP_PROXY_AUTH_ENABLED | `false`| Whether the PEP Proxy is checking for Authorization |\n| PEP_PROXY_IDM_SSL_ENABLED | `false`| Whether the Identity Manager is running under HTTPS |\n| PEP_PROXY_IDM_PORT | `3005`|  The Port for the Identity Manager instance|\n| PEP_PROXY_APP_ID | `tutorial-dckr-site-0000-xpresswebapp`| |\n| PEP_PROXY_USERNAME | `pep_proxy_00000000-0000-0000-0000-000000000000`|  The Username for the PEP Proxy |\n| PEP_PASSWORD | `test`|  The Password for the PEP Proxy |\n| PEP_PROXY_PDP | `idm`| The Type of service offering the Policy Decision Point|\n| PEP_PROXY_MAGIC_KEY | `1234` | |\n\nFor this example, the PEP Proxy is checking for Level 1 - *Authentication Access* not  Level 2 - *Basic Authorization* or \nLevel 3 - *Advanced Authorization*. \n\n\n\n## Securing Orion - Application Configuration\n\nThe tutorial application has already been registered in **Keyrock**, programmatically the tutorial application will\nbe making requests to the **Wilma** PEP Proxy in front of the **Orion Conext Broker**. Every request must now include\nan additional `access_token` header.\n\n```yaml\n  tutorial-app:\n    image: fiware/tutorials.context-provider\n    hostname: iot-sensors-app\n    container_name: tutorial-app\n    depends_on:\n        - orion-proxy\n        - iot-agent\n        - keyrock\n    networks:\n      default:\n        ipv4_address: 172.18.1.7\n        aliases:\n          - tutorial\n    expose:\n        - \"3000\"\n        - \"3001\"\n    ports:\n        - \"3000:3000\"\n        - \"3001:3001\"\n    environment:\n        - \"WEB_APP_PORT=3000\"\n        - \"SECURE_ENDPOINTS=true\"\n        - \"CONTEXT_BROKER=http://orion-proxy:1027/v2\"\n        - \"KEYROCK_URL=http://localhost\"\n        - \"KEYROCK_IP_ADDRESS=http://172.18.1.5\"\n        - \"KEYROCK_PORT=3005\"\n        - \"KEYROCK_CLIENT_ID=tutorial-dckr-site-0000-xpresswebapp\"\n        - \"KEYROCK_CLIENT_SECRET=tutorial-dckr-site-0000-clientsecret\"\n        - \"CALLBACK_URL=http://localhost:3000/login\"\n```\n\nAll of the `tutorial` container settings have been described in previous tutorials. One important change is necessary however,\nrather than accessing **Orion** directly on the default port `1026` as shown in all previous tutorials, all context broker\ntraffic is now sent to `orion-proxy` on port `1027`. As a reminder, the relevant settings are detailed below:\n\n| Key |Value|Description|\n|-----|-----|-----------|\n|WEB_APP_PORT|`3000`|Port used by web-app which displays the login screen & etc.|\n|KEYROCK_URL|`http://localhost`| This is URL of the **Keyrock** Web Front-End itself, used for redirection when forwarding users |\n|KEYROCK_IP_ADDRESS|`http://172.18.1.5`| This is URL of the **Keyrock** OAuth Communications |\n|KEYROCK_PORT|`3005` | This is the port that **Keyrock** is listening on.|\n|KEYROCK_CLIENT_ID|`tutorial-dckr-site-0000-xpresswebapp`| The Client ID defined by Keyrock for this application |\n|KEYROCK_CLIENT_SECRET|`tutorial-dckr-site-0000-clientsecret`| The Client Secret defined by Keyrock for this application |\n|CALLBACK_URL|`http://localhost:3000/login`| The callback URL used by Keyrock when a challenge has succeeded.|\n\n## Securing Orion - Start up\n\nTo start the system with a PEP Proxy protecting  access to **Orion**, run the following command:\n\n```console\n./services orion\n```\n\n\n### Video : Securing A REST API\n\n[![](http://img.youtube.com/vi/coxFQEY0_So/0.jpg)](https://www.youtube.com/watch?v=coxFQEY0_So \"Securing a REST API\")\n\nClick on the image above to see a video about securing a REST API using the Wilma PEP Proxy\n\n\n\n## Securing Orion - Sample Code\n\nWhen a User logs in to the application using the User Credentials Grant, an `access_token` is obtained which identifies the User.\nThe  `access_token`  is stored in session:\n\n```javascript\nfunction userCredentialGrant(req, res){\n    debug('userCredentialGrant');\n\n    const email = req.body.email;\n    const password = req.body.password;\n\n    oa.getOAuthPasswordCredentials(email, password)\n    .then(results => {\n        req.session.access_token =  results.access_token;\n        return;\n    })\n}\n```\n\nFor each subsequent request, the `access_token` is supplied in the `X-Auth-Token` Header\n\n```javascript\nfunction setAuthHeaders(req){\n  const headers = {};\n  if (req.session.access_token) {\n    headers['X-Auth-Token'] = req.session.access_token;\n  }\n  return headers;\n}\n```\n\nFor example, when buying an item, two requests are made, the same  `X-Auth-Token` Header must be added to each request - therefore\nthe User can be identified and access granted.\n\n```javascript\nasync function buyItem(req, res) {\n\n  const inventory = await retrieveEntity(req.params.inventoryId, {\n    options: 'keyValues',\n    type: 'InventoryItem',\n  }, setAuthHeaders(req));\n  const count = inventory.shelfCount - 1;\n\n  await updateExistingEntityAttributes(\n    req.params.inventoryId,\n    { shelfCount: { type: 'Integer', value: count } },\n    {\n      type: 'InventoryItem',\n    }, setAuthHeaders(req)\n  );\n  res.redirect(`/app/store/${inventory.refStore}/till`);\n}\n```",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		},
		{
			"name": "Securing an IoT Agent South Port",
			"item": [
				{
					"name": "Keyrock - IoT Sensor Obtains an Access Token",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Authorization",
								"value": "Basic {{Authorization}}",
								"description": "base64 concatenation of Client Id and Client Secret"
							},
							{
								"key": "Content-Type",
								"value": "application/x-www-form-urlencoded"
							},
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "username=iot_sensor_00000000-0000-0000-0000-000000000000&password=test&grant_type=password"
						},
						"url": {
							"raw": "http://{{keyrock}}/oauth2/token",
							"protocol": "http",
							"host": [
								"{{keyrock}}"
							],
							"path": [
								"oauth2",
								"token"
							]
						},
						"description": "Logging in as an IoT Sensor follows the same  user-credentials flow as for a User.\nTo log in and identify the sensor `iot_sensor_00000000-0000-0000-0000-000000000000` with password `test`\n\nThe response returns an access code to identify the IoT Device"
					},
					"response": []
				},
				{
					"name": "PEP Proxy - Accessing IoT Agent with an Access Token",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "X-Auth-Token",
								"value": "{{X-Access-token}}"
							}
						],
						"body": {
							"mode": "formdata",
							"formdata": []
						},
						"url": {
							"raw": "http://localhost:7897/iot/d?k=4jggokgpepnvsb2uv4s40d59ov&i=motion001",
							"protocol": "http",
							"host": [
								"localhost"
							],
							"port": "7897",
							"path": [
								"iot",
								"d"
							],
							"query": [
								{
									"key": "k",
									"value": "4jggokgpepnvsb2uv4s40d59ov"
								},
								{
									"key": "i",
									"value": "motion001"
								}
							]
						},
						"description": "This example simulates a secured request coming from the device `motion001`\n\nThe POST request to a PEP Proxy in front to the Ultralight IoT Agent identifies\na previously provisioned resource `iot/d`endpoint and passes a measurement for\ndevice `motion001`. The addition of the `X-Auth-Token` Header identifies the source\nof the request as being registered in Keyrock, and therefore the measurement will \nbe passed on to the IoT Agent itself."
					},
					"response": []
				}
			],
			"description": "![](https://fiware.github.io/tutorials.PEP-Proxy/img/pep-proxy-south-port.png)\n\n\n## Securing an IoT Agent South Port - PEP Proxy Configuration\n\nThe `iot-agent-proxy` container is an instance of FIWARE **Wilma** listening on port `7897`, it is configured to forward traffic to\n`iot-agent` on port `7896`, which is the default port that the Ultralight agent is listening to for HTTP Requests.\n\n```yaml\n  iot-agent-proxy:\n    image: fiware/pep-proxy\n    container_name: fiware-iot-agent-proxy\n    hostname: iot-agent-proxy\n    networks:\n      default:\n        ipv4_address: 172.18.1.11\n    depends_on:\n      - keyrock\n    ports:\n      - \"7897:7897\"\n    expose:\n      - \"7897\"\n    environment:\n      - PEP_PROXY_APP_HOST=iot-agent\n      - PEP_PROXY_APP_PORT=7896\n      - PEP_PROXY_PORT=7897\n      - PEP_PROXY_IDM_HOST=keyrock\n      - PEP_PROXY_HTTPS_ENABLED=false\n      - PEP_PROXY_AUTH_ENABLED=false\n      - PEP_PROXY_IDM_SSL_ENABLED=false\n      - PEP_PROXY_IDM_PORT=3005\n      - PEP_PROXY_APP_ID=tutorial-dckr-site-0000-xpresswebapp\n      - PEP_PROXY_USERNAME=pep_proxy_00000000-0000-0000-0000-000000000000\n      - PEP_PASSWORD=test\n      - PEP_PROXY_PDP=idm\n      - PEP_PROXY_MAGIC_KEY=1234\n```\n\nThe `PEP_PROXY_APP_ID` and `PEP_PROXY_USERNAME` would usually be obtained by adding new entries to the application in **Keyrock**,\nhowever, in this tutorial, they have been pre-defined by populating the **MySQL** database with data on start-up.\n\nThe `iot-agent-proxy` container is listening on a single port:\n\n* The PEP Proxy Port - `7897` is exposed purely for tutorial access - so that cUrl or Postman can requests directly to this **Wilma** instance\n  without being part of the same network.\n\n| Key |Value|Description|\n|-----|-----|-----------|\n| PEP_PROXY_APP_HOST | `iot-agent`| The hostname of the service behind the PEP Proxy |\n| PEP_PROXY_APP_PORT | `7896`| The port of the service behind the PEP Proxy |\n| PEP_PROXY_PORT | `7897`| The port that the PEP Proxy is listening on |\n| PEP_PROXY_IDM_HOST | `keyrock`| The hostname for the Identity Manager |\n| PEP_PROXY_HTTPS_ENABLED | `false`| Whether the PEP Proxy is running under HTTPS |\n| PEP_PROXY_AUTH_ENABLED | `false`|  Whether the PEP Proxy is checking for Authorization|\n| PEP_PROXY_IDM_SSL_ENABLED | `false`|  Whether the Identity Manager is running under HTTPS |\n| PEP_PROXY_IDM_PORT | `3005`|  The Port for the Identity Manager instance|\n| PEP_PROXY_APP_ID | `tutorial-dckr-site-0000-xpresswebapp`| |\n| PEP_PROXY_USERNAME | `pep_proxy_00000000-0000-0000-0000-000000000000`|  The Username for the PEP Proxy |\n| PEP_PASSWORD | `test`|  The Password for the PEP Proxy |\n| PEP_PROXY_PDP | `idm`| The Type of service offering the Policy Decision Point|\n| PEP_PROXY_MAGIC_KEY | `1234` | |\n\nFor this example, the PEP Proxy is checking for Level 1 - *Authentication Access* not  Level 2 - *Basic Authorization* or \nLevel 3 - *Advanced Authorization*. \n\n\n## Securing an IoT Agent South Port - Application Configuration\n\nThe tutorial application also plays the role of providing data from our dummy IoT Sensors. The IoT Sensors are\nmaking HTTP request containing commands and measurements in Ultralight syntax. An IoT Sensor username and password\nhave already been registered in **Keyrock**, programmatically each sensor must obtain an OAuth2 access token and\nwill then make requests to  a second **Wilma** PEP Proxy in front of the **IoT Agent**.\n\n\n```yaml\n  tutorial-app:\n    image: fiware/tutorials.context-provider\n    hostname: iot-sensors-app\n    container_name: tutorial-app\n    depends_on:\n        - orion-proxy\n        - iot-agent-proxy\n        - keyrock\n    networks:\n      default:\n        ipv4_address: 172.18.1.7\n        aliases:\n          - tutorial\n    expose:\n        - \"3000\"\n        - \"3001\"\n    ports:\n        - \"3000:3000\"\n        - \"3001:3001\"\n    environment:\n        - \"IOTA_HTTP_HOST=iot-agent-proxy\"\n        - \"IOTA_HTTP_PORT=7897\"\n        - \"DUMMY_DEVICES_PORT=3001\" # Port used by the dummy IOT devices to receive commands\n        - \"DUMMY_DEVICES_TRANSPORT=HTTP\" # Default transport used by dummy Io devices\n        - \"DUMMY_DEVICES_API_KEY=4jggokgpepnvsb2uv4s40d59ov\"\n        - \"DUMMY_DEVICES_USER=iot_sensor_00000000-0000-0000-0000-000000000000\"\n        - \"DUMMY_DEVICES_PASSWORD=test\"\n```\n\nThe `tutorial` container hosts the dummy Ultralight sensors. Rather than accessing the **IoT Agent** directly on port `7896` as\nshown in all previous tutorials, all traffic is forwarded to `iot-agent-proxy` on port `7897`. Most of the relevant `tutorial`\ncontainer settings have been described in previous tutorials, the `DUMMY_DEVICES_USER` and `DUMMY_DEVICES_PASSWORD` are new\nadditions.\n\n\n| Key |Value|Description|\n|-----|-----|-----------|\n|IOTA_HTTP_HOST|`iot-agent-proxy`| The host name of the Wilma PEP Proxy protecting the IoT Agent for UltraLight 2.0 |\n|IOTA_HTTP_PORT|`7896` | The port that the Wilma PEP Proxy protecting the IoT Agent is listenting on|\n|DUMMY_DEVICES_PORT|`3001`| Port used by the dummy IOT devices to receive commands|\n|DUMMY_DEVICES_TRANSPORT|`HTTP`|Default transport used by dummy Io devices|\n|DUMMY_DEVICES_API_KEY|`4jggokgpepnvsb2uv4s40d59ov`| Random security key used for UltraLight interactions - ensures the integrity of interactions between the devices and the IoT Agent |\n|DUMMY_DEVICES_USER|`iot_sensor_00000000-0000-0000-0000-000000000000` | Username assigned to the device(s) in **Keyrock** |\n|DUMMY_DEVICES_PASSWORD|`test` | Password assigned to the device(s) in **Keyrock** |\n\nThe `DUMMY_DEVICES_USER` and `DUMMY_DEVICES_PASSWORD` would usually be obtained by adding new entries to the application in **Keyrock**,\nhowever, in this tutorial, they have been pre-defined by populating the **MySQL** database with data on start-up.\n\n## Securing IoT Agent - Start up\n\nTo start the system with a PEP Proxies protecting access to both **Orion** and the **IoT Agent** run the following command:\n\n```console\n./services southport\n```\n\n\n## Securing an IoT Agent South Port -  Sample Code\n\n\nWhen an IoT Sensor starts up, it must log-in like any other user to obtain an access token:\n\n```javascript\nconst DUMMY_DEVICE_HTTP_HEADERS = { 'Content-Type': 'text/plain' };\n```\n```javascript\nfunction initSecureDevices(){\n    Security.oa.getOAuthPasswordCredentials(process.env.DUMMY_DEVICES_USER, process.env.DUMMY_DEVICES_PASSWORD)\n    .then(results => {\n        DUMMY_DEVICE_HTTP_HEADERS['X-Auth-Token'] = results.access_token;\n        return;\n    })\n    .catch(error => {\n        debug(error);\n        return;\n    });\n}\n```\n\nEach HTTP request thereafter includes the `X-Auth-Token` Header in the request identifying the IoT Sensor:\n\n```javascript\nconst options = { method: 'POST',\n  url: UL_URL,\n  qs: { k: UL_API_KEY, i: deviceId },\n  headers: DUMMY_DEVICE_HTTP_HEADERS,\n  body: state };\n\nrequest(options,  (error) => {\n  if (error){\n    debug( debugText +  \" \" + error.code)\n  } \n});\n```\n\n",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		},
		{
			"name": "Securing an IoT Agent North Port",
			"item": [
				{
					"name": "Keyrock  - Obtaining a permanent token",
					"request": {
						"method": "POST",
						"header": [
							{
								"description": "base64 concatenation of Client Id and Client Secret",
								"key": "Authorization",
								"value": "Basic {{Authorization}}"
							},
							{
								"key": "Content-Type",
								"value": "application/x-www-form-urlencoded"
							},
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "username=alice-the-admin@test.com&password=test&grant_type=password&scope=permanent"
						},
						"url": {
							"raw": "http://{{keyrock}}/oauth2/token",
							"protocol": "http",
							"host": [
								"{{keyrock}}"
							],
							"path": [
								"oauth2",
								"token"
							]
						},
						"description": "The Keyrock application has been configured to offer permanent tokens\n\nThe standard `Authorization: Basic` header holds the base 64 concatentation of the client id and secret. The parameter\n`scope=permanent` is added to retrieve permanent tokens when available. The response contains an `access_token` which\ncan be used for device provisioning."
					},
					"response": []
				},
				{
					"name": "IoT Agent - Provisioning a trusted service group",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-service-path",
								"value": "/",
								"type": "text"
							},
							{
								"key": "Accept",
								"value": "application/json",
								"type": "text",
								"name": "Accept"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n \"services\": [\n   {\n     \"apikey\":      \"4jggokgpepnvsb2uv4s40d59ov\",\n     \"cbroker\":     \"http://orion:1026\",\n     \"entity_type\": \"Motion\",\n     \"resource\":    \"/iot/d\",\n     \"trust\": \"e37aeef5d48c9c1a3d4adf72626a8745918d4355\"\n   }\n ]\n}"
						},
						"url": {
							"raw": "http://localhost:4041/iot/services",
							"protocol": "http",
							"host": [
								"localhost"
							],
							"port": "4041",
							"path": [
								"iot",
								"services"
							]
						},
						"description": "The Access token (also known as a Trust Token) must be added to the service group."
					},
					"response": []
				},
				{
					"name": "IoT Agent - Provisioning a sensor",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "fiware-service",
								"value": "openiot"
							},
							{
								"key": "fiware-service-path",
								"value": "/",
								"type": "text"
							},
							{
								"key": "Accept",
								"value": "application/json",
								"type": "text",
								"name": "Accept"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n \"devices\": [\n   {\n     \"device_id\":   \"motion001\",\n     \"entity_name\": \"urn:ngsi-ld:Motion:001\",\n     \"entity_type\": \"Motion\",\n     \"timezone\":    \"Europe/Berlin\",\n     \"attributes\": [\n       { \"object_id\": \"c\", \"name\": \"count\", \"type\": \"Integer\" }\n     ],\n     \"static_attributes\": [\n       { \"name\":\"refStore\", \"type\": \"Relationship\", \"value\": \"urn:ngsi-ld:Store:001\"}\n     ]\n   }\n ]\n}"
						},
						"url": {
							"raw": "http://localhost:4041/iot/devices",
							"protocol": "http",
							"host": [
								"localhost"
							],
							"port": "4041",
							"path": [
								"iot",
								"devices"
							]
						},
						"description": "Once a trusted service group has been created, a device can be provisioned in the usual manner"
					},
					"response": []
				}
			],
			"description": "![](https://fiware.github.io/tutorials.PEP-Proxy/img/pep-proxy-north-port.png)\n\n## Securing an IoT Agent North Port - IoT Agent Configuration\n\nThe `iot-agent` container is listening on port `4041`, it is configured to forward traffic to `orion-proxy` on port\n`1027`.\n\n```yaml\niot-agent:\n    labels:
      org.fiware: 'tutorial'
    image: fiware/iotagent-ul:${ULTRALIGHT_VERSION}\n    hostname: iot-agent\n    container_name: fiware-iot-agent\n    depends_on:\n        - mongo-db\n        - orion\n    networks:\n        - default\n    ports:\n        - \"4041:4041\"\n        - \"7896:7896\"\n    environment:\n        - IOTA_CB_HOST=orion-proxy\n        - IOTA_CB_PORT=1027\n        - IOTA_NORTH_PORT=4041\n        - IOTA_REGISTRY_TYPE=mongodb\n        - IOTA_LOG_LEVEL=DEBUG\n        - IOTA_TIMESTAMP=true\n        - IOTA_CB_NGSI_VERSION=v2\n        - IOTA_AUTOCAST=true\n        - IOTA_MONGO_HOST=mongo-db\n        - IOTA_MONGO_PORT=27017\n        - IOTA_MONGO_DB=iotagentul\n        - IOTA_HTTP_PORT=7896\n        - IOTA_PROVIDER_URL=http://iot-agent:4041\n        - IOTA_AUTH_ENABLED=true\n        - IOTA_AUTH_TYPE=oauth2\n        - IOTA_AUTH_HEADER=Authorization\n        - IOTA_AUTH_HOST=keyrock\n        - IOTA_AUTH_PORT=3005\n        - IOTA_AUTH_URL=http://keyrock:3005\n        - IOTA_AUTH_TOKEN_PATH=/oauth2/token\n        - IOTA_AUTH_PERMANENT_TOKEN=true\n        - IOTA_AUTH_CLIENT_ID=tutorial-dckr-site-0000-xpresswebapp\n        - IOTA_AUTH_CLIENT_SECRET=tutorial-dckr-host-0000-clientsecret\n```\n\n| Key                       | Value                                  | Description                                                |\n| ------------------------- | -------------------------------------- | ---------------------------------------------------------- |\n| IOTA_AUTH_ENABLED         | `true`                                 | Whether to use authorization on the north port             |\n| IOTA_AUTH_TYPE            | `oauth2`                               | The type of authorization to be used (Keyrock uses OAuth2) |\n| IOTA_AUTH_HEADER          | `Authorization`                        | The name of the header to be added to requests             |\n| IOTA_AUTH_HOST            | `keyrock`                              | The Identity Manager holding the application               |\n| IOTA_AUTH_PORT            | `3005`                                 | The port the Identity Manager is listening on              |\n| IOTA_AUTH_URL             | `http://keyrock:3005`                  | The URL for authentication requests                        |\n| IOTA_AUTH_CLIENT_ID       | `tutorial-dckr-site-0000-xpresswebapp` | the Id of the applicantion within Keyrock                  |\n| IOTA_AUTH_CLIENT_SECRET   | `tutorial-dckr-host-0000-clientsecret` | The client secret of the application within Keyrock        |\n| IOTA_AUTH_PERMANENT_TOKEN | `true`                                 | Whether to use permanent tokens                            |\n| IOTA_AUTH_TOKEN_PATH      | `/oauth2/token`                        | the path to be used when requesting tokens                 |\n\n## Securing an IoT Agent North Port - Start up\n\nTo start the system with a PEP Proxy protecting access to between **Orion** and the **IoT Agent** North Port run the\nfollowing command:\n\n```\n./services northport\n```",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				},
				{
					"listen": "test",
					"script": {
						"type": "text/javascript",
						"exec": [
							""
						]
					}
				}
			]
		}
	],
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		}
	],
	"variable": [
		{
			"key": "keyrock",
			"value": "localhost:3005"
		},
		{
			"key": "X-Auth-token",
			"value": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
		},
		{
			"key": "X-Subject-token",
			"value": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
		},
		{
			"key": "application-id",
			"value": "tutorial-dckr-site-0000-xpresswebapp"
		},
		{
			"key": "X-Access-token",
			"value": " 79d07d0139c66b75fc25f56a88008553f12f6ac7"
		},
		{
			"key": "Authorization",
			"value": "dHV0b3JpYWwtZGNrci1zaXRlLTAwMDAteHByZXNzd2ViYXBwOnR1dG9yaWFsLWRja3Itc2l0ZS0wMDAwLWNsaWVudHNlY3JldA=="
		},
		{
			"key": "iot-agent-id",
			"value": "iot_sensor_00000000-0000-0000-0000-000000000000"
		},
		{
			"key": "pep-proxy-id",
			"value": "pep_proxy_00000000-0000-0000-0000-000000000000"
		}
	]
}