From 65e657da3c52ac021063c9e4e71a5f3b3f3c09ad Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 4 Jun 2024 10:18:47 +0200 Subject: [PATCH] Switch to WSL --- FIWARE Securing Access.postman_collection.json | 2 +- README.ja.md | 8 +++----- README.md | 9 +++++---- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/FIWARE Securing Access.postman_collection.json b/FIWARE Securing Access.postman_collection.json index 6fa588b..fbce6f6 100644 --- a/FIWARE Securing Access.postman_collection.json +++ b/FIWARE Securing Access.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "322a0fc2-45c0-47c4-bd8f-088f8470af41", "name": "FIWARE Securing Access", - "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 secures access to a FIWARE application using the entities created in the [previous tutorial](https://github.com/Fiware/tutorials.Roles-Permissions). The tutorial explains appropriate use of the various OAuth2 grant flows, and how to use\nthe **Keyrock** generic enabler as an Authorization Server to identify users. **Keyrock** is also used as a Policy Decision\nPoint (PDP) to restrict access.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Securing-Access/icon/GitHub-Mark-32px.png) [FIWARE 403: Securing Access](https://github.com/Fiware/tutorials.Securing-Access)\n\n\n# Securing Access\n\n> \"When a person or party approaches your post, you should challenge them at a distance that is sufficient\n> for you to react if they turn out to have hostile intentions. You should say in a firm voice, loud enough\n> to be easily heard, *\"Halt! Who goes there?\"* (or *\"Who is there?\"*). Once the person answers, you should then say\n> *\"Advance to be recognized.\"* ... If you have identified the person or persons approaching, permit them to pass.\n> If you are not satisfied with that person's identification, you must detain the person and call the petty officer\n> of the watch.\"\n>\n> — 11th General Order of the US Marine Corps\n\nIn order to secure access to application resources, it is necessary to know two things. Firstly, who is making the\nrequest and secondly is the requestor permitted to access the resource? The FIWARE **Keyrock** generic enabler uses\nuses [OAuth2](https://oauth.net/2/) to enable third-party applications to obtain limited access to services.\n**OAuth2** is the open standard for access delegation to grant access rights. It allows notifying a resource provider\n(e.g. the Knowage Generic Enabler) that the resource owner (e.g. you) grants permission to a third-party\n(e.g. a Knowage Application) access to their information (e.g. the list of entities).\n\nThere are several common OAuth 2.0 grant flows, the details of which can be found below:\n\n* [Authorization Code](https://oauth.net/2/grant-types/authorization-code)\n* [Implicit](https://oauth.net/2/grant-types/implicit)\n* [Password](https://oauth.net/2/grant-types/password)\n* [Client Credentials](https://oauth.net/2/grant-types/client-credentials)\n* [Device Code](https://oauth.net/2/grant-types/device-code)\n* [Refresh Token](https://oauth.net/2/grant-types/refresh-token)\n\nThe primary concept is that both **Users** and **Applications** must first identify themselves using\na standard OAuth2 Challenge-Response mechanism. Thereafter a user is assigned a token which they\nappend to every subsequent request. This token identifies the user, the application and the rights the\nuser is able to exercise. **Keyrock** can then be used with other enablers can be used to limit and\nlock-down access. The details of the access flows are discussed below and in subsequent tutorials.\n\nThe reasoning behind OAuth2 is that you never need to expose your own username and password to a\nthird party to give them full access - you merely permit the relevant access which can be either Read-Only\nor Read-Write and such access can be defined down to a granular level. Furthermore there is provision for\nrevoking access at any time, leaving the resource owner in control of who can access what.\n\nOnce the application is able to authenticate users, it is also possible to lock down access using access control\nmechanisms. Access control requires having an access policy - in other words defining who can do what.\nWe have already defined roles and permisions within the [previous tutorial](https://github.com/Fiware/tutorials.Roles-Permissions),\nand now need to programatically enforce this policy by adding in a simple\nPolicy Decision Point (PDP) – which evaluates and issues authorization decisions, and then secure access by enforcing\nthe decision using a Policy Enforcement Point (PEP).\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.Securing-Access/img/entities.png)\n\n## OAuth2\n\n**Keyrock** uses [OAuth2](https://oauth.net/2/) to enable third-party applications\nto obtain limited access to services. **OAuth2** is the open standard for access delegation to\ngrant access rights. It allows notifying a resource provider (e.g. the Knowage Generic Enabler)\nthat the resource owner (e.g. you) grants permission to a third-party (e.g. a Knowage Application)\naccess to their information (e.g. the list of entities).\n\nThere are several common OAuth 2.0 grant flows, the details of which can be found below:\n\n* [Authorization Code](https://oauth.net/2/grant-types/authorization-code)\n* [Implicit](https://oauth.net/2/grant-types/implicit)\n* [Password](https://oauth.net/2/grant-types/password)\n* [Client Credentials](https://oauth.net/2/grant-types/client-credentials)\n* [Device Code](https://oauth.net/2/grant-types/device-code)\n* [Refresh Token](https://oauth.net/2/grant-types/refresh-token)\n\nThe primary concept is that both **Users** and **Applications** must first identify themselves using\na standard OAuth2 Challenge-Response mechanism. Thereafter a user is assigned a token which they\nappend to every subsequent request. This token identifies the user, the application and the rights the\nuser is able to exercise. **Keyrock** can then be used with other enablers can be used to limit and\nlock-down access. The details of the access flows are discussed below and in subsequent tutorials.\n\nThe reasoning behind OAuth2 is that you never need to expose your own username and password to a\nthird party to give them full access - you merely permit the relevant access which can be either Read-Only\nor Read-Write and such access can be defined down to a granular level. Furthermore there is provision for\nrevoking access at any time, leaving the resource owner in control of who can access what.\n\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 adds OAuth2-driven security into the existing Stock Management and Sensors-based application\ncreated in [previous tutorials](https://github.com/Fiware/tutorials.IoT-Agent/) by using the data created in the first [security tutorial](https://github.com/Fiware/tutorials.Identity-Management/) and reading it programatically. It\nwill make use of three 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/) and integrates the use of the [Keyrock](http://fiware-idm.readthedocs.io/) Generic enabler. Usage 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* 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\n![](https://fiware.github.io/tutorials.Securing-Access/img/architecture.png)\n\nThe necessary configuration information for adding security to the **Stock Management Frontend** can be found in the `context-provider` section of the associated `docker-compose.yml` file - only the relevant variables are shown below:\n\n## Context-Provider Security Configuration\n\n```yaml\n context-provider:\n image: quay.io/fiware/tutorials.context-provider\n hostname: context-provider\n container_name: context-provider\n networks:\n default:\n ipv4_address: 172.18.1.7\n expose:\n - \"3000\"\n - \"3001\"\n ports:\n - \"3000:3000\"\n - \"3001:3001\"\n environment:\n - \"DEBUG=tutorial:*\"\n - \"WEB_APP_PORT=3000\"\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\nThe `context-provider` container is listening on two ports:\n\n* Port `3000` is exposed so we can see the web-page displaying the Dummy IoT devices.\n* Port `3001` is exposed purely for tutorial access - so that cUrl or Postman can make UltraLight commands\n without being part of the same network.\n\n\nThe `context-provider` container is driven by environment variables as shown:\n\n| Key |Value|Description|\n|-----|-----|-----------|\n|DEBUG|`tutorial:*`| Debug flag used for logging |\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\nThe other `context-provider` container configuration values described in the YAML file have been described in previous tutorials\n\nThe separate `KEYROCK_URL` and `KEYROCK_IP_ADDRESS` are only necessary because of the simplified\nDocker containerization used within the tutorial. The `KEYROCK_URL` variable with the value `localhost` is referring\nto the location externally exposed by the container, the `KEYROCK_IP_ADDRESS` variable refers to the same location\nbut accessed from within the Docker network. Similarly the `CALLBACK_URL` contains `localhost` as it\nis assumed that the browser will be accessed from the same machine. All of these values should be replaced\nwith appropriate proxies and DNS settings for a production environment, but production deployment is beyond\nthe scope of this tutorial.\n\n\n# Start Up\n\nTo start the installation, do the following:\n\n```console\ngit clone git@github.com:Fiware/tutorials.Securing-Access.git\ncd tutorials.Securing-Access\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.Securing-Access/blob/master/services) Bash script provided within the repository:\n\n```console\n./services \n```\n\nWhere `` 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-0000-0000-0000-000000000000`|\n| Management | Management Group for Store Managers |`managers-0000-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` |\n\n\nTo save time, the data creating users and organizations from the [previous tutorial](https://github.com/Fiware/tutorials.Identity-Management) has been downloaded and is automatically persisted to the MySQL\ndatabase on start-up so the asigned UUIDs do not change and the data does not need to be entered again.\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.Securing-Access/img/log-in.png)\n\nand look around.", + "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 secures access to a FIWARE application using the entities created in the [previous tutorial](https://github.com/Fiware/tutorials.Roles-Permissions). The tutorial explains appropriate use of the various OAuth2 grant flows, and how to use\nthe **Keyrock** generic enabler as an Authorization Server to identify users. **Keyrock** is also used as a Policy Decision\nPoint (PDP) to restrict access.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Securing-Access/icon/GitHub-Mark-32px.png) [FIWARE 403: Securing Access](https://github.com/Fiware/tutorials.Securing-Access)\n\n\n# Securing Access\n\n> \"When a person or party approaches your post, you should challenge them at a distance that is sufficient\n> for you to react if they turn out to have hostile intentions. You should say in a firm voice, loud enough\n> to be easily heard, *\"Halt! Who goes there?\"* (or *\"Who is there?\"*). Once the person answers, you should then say\n> *\"Advance to be recognized.\"* ... If you have identified the person or persons approaching, permit them to pass.\n> If you are not satisfied with that person's identification, you must detain the person and call the petty officer\n> of the watch.\"\n>\n> — 11th General Order of the US Marine Corps\n\nIn order to secure access to application resources, it is necessary to know two things. Firstly, who is making the\nrequest and secondly is the requestor permitted to access the resource? The FIWARE **Keyrock** generic enabler uses\nuses [OAuth2](https://oauth.net/2/) to enable third-party applications to obtain limited access to services.\n**OAuth2** is the open standard for access delegation to grant access rights. It allows notifying a resource provider\n(e.g. the Knowage Generic Enabler) that the resource owner (e.g. you) grants permission to a third-party\n(e.g. a Knowage Application) access to their information (e.g. the list of entities).\n\nThere are several common OAuth 2.0 grant flows, the details of which can be found below:\n\n* [Authorization Code](https://oauth.net/2/grant-types/authorization-code)\n* [Implicit](https://oauth.net/2/grant-types/implicit)\n* [Password](https://oauth.net/2/grant-types/password)\n* [Client Credentials](https://oauth.net/2/grant-types/client-credentials)\n* [Device Code](https://oauth.net/2/grant-types/device-code)\n* [Refresh Token](https://oauth.net/2/grant-types/refresh-token)\n\nThe primary concept is that both **Users** and **Applications** must first identify themselves using\na standard OAuth2 Challenge-Response mechanism. Thereafter a user is assigned a token which they\nappend to every subsequent request. This token identifies the user, the application and the rights the\nuser is able to exercise. **Keyrock** can then be used with other enablers can be used to limit and\nlock-down access. The details of the access flows are discussed below and in subsequent tutorials.\n\nThe reasoning behind OAuth2 is that you never need to expose your own username and password to a\nthird party to give them full access - you merely permit the relevant access which can be either Read-Only\nor Read-Write and such access can be defined down to a granular level. Furthermore there is provision for\nrevoking access at any time, leaving the resource owner in control of who can access what.\n\nOnce the application is able to authenticate users, it is also possible to lock down access using access control\nmechanisms. Access control requires having an access policy - in other words defining who can do what.\nWe have already defined roles and permisions within the [previous tutorial](https://github.com/Fiware/tutorials.Roles-Permissions),\nand now need to programatically enforce this policy by adding in a simple\nPolicy Decision Point (PDP) – which evaluates and issues authorization decisions, and then secure access by enforcing\nthe decision using a Policy Enforcement Point (PEP).\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.Securing-Access/img/entities.png)\n\n## OAuth2\n\n**Keyrock** uses [OAuth2](https://oauth.net/2/) to enable third-party applications\nto obtain limited access to services. **OAuth2** is the open standard for access delegation to\ngrant access rights. It allows notifying a resource provider (e.g. the Knowage Generic Enabler)\nthat the resource owner (e.g. you) grants permission to a third-party (e.g. a Knowage Application)\naccess to their information (e.g. the list of entities).\n\nThere are several common OAuth 2.0 grant flows, the details of which can be found below:\n\n* [Authorization Code](https://oauth.net/2/grant-types/authorization-code)\n* [Implicit](https://oauth.net/2/grant-types/implicit)\n* [Password](https://oauth.net/2/grant-types/password)\n* [Client Credentials](https://oauth.net/2/grant-types/client-credentials)\n* [Device Code](https://oauth.net/2/grant-types/device-code)\n* [Refresh Token](https://oauth.net/2/grant-types/refresh-token)\n\nThe primary concept is that both **Users** and **Applications** must first identify themselves using\na standard OAuth2 Challenge-Response mechanism. Thereafter a user is assigned a token which they\nappend to every subsequent request. This token identifies the user, the application and the rights the\nuser is able to exercise. **Keyrock** can then be used with other enablers can be used to limit and\nlock-down access. The details of the access flows are discussed below and in subsequent tutorials.\n\nThe reasoning behind OAuth2 is that you never need to expose your own username and password to a\nthird party to give them full access - you merely permit the relevant access which can be either Read-Only\nor Read-Write and such access can be defined down to a granular level. Furthermore there is provision for\nrevoking access at any time, leaving the resource owner in control of who can access what.\n\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## WSL\n\nWe will start up our services using a simple bash script. Windows users should download the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to provide a\ncommand line functionality similar to a Linux distribution on Windows.\n\n# Architecture\n\n\nThis application adds OAuth2-driven security into the existing Stock Management and Sensors-based application\ncreated in [previous tutorials](https://github.com/Fiware/tutorials.IoT-Agent/) by using the data created in the first [security tutorial](https://github.com/Fiware/tutorials.Identity-Management/) and reading it programatically. It\nwill make use of three 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/) and integrates the use of the [Keyrock](http://fiware-idm.readthedocs.io/) Generic enabler. Usage 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* 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\n![](https://fiware.github.io/tutorials.Securing-Access/img/architecture.png)\n\nThe necessary configuration information for adding security to the **Stock Management Frontend** can be found in the `context-provider` section of the associated `docker-compose.yml` file - only the relevant variables are shown below:\n\n## Context-Provider Security Configuration\n\n```yaml\n context-provider:\n image: quay.io/fiware/tutorials.context-provider\n hostname: context-provider\n container_name: context-provider\n networks:\n default:\n ipv4_address: 172.18.1.7\n expose:\n - \"3000\"\n - \"3001\"\n ports:\n - \"3000:3000\"\n - \"3001:3001\"\n environment:\n - \"DEBUG=tutorial:*\"\n - \"WEB_APP_PORT=3000\"\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\nThe `context-provider` container is listening on two ports:\n\n* Port `3000` is exposed so we can see the web-page displaying the Dummy IoT devices.\n* Port `3001` is exposed purely for tutorial access - so that cUrl or Postman can make UltraLight commands\n without being part of the same network.\n\n\nThe `context-provider` container is driven by environment variables as shown:\n\n| Key |Value|Description|\n|-----|-----|-----------|\n|DEBUG|`tutorial:*`| Debug flag used for logging |\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\nThe other `context-provider` container configuration values described in the YAML file have been described in previous tutorials\n\nThe separate `KEYROCK_URL` and `KEYROCK_IP_ADDRESS` are only necessary because of the simplified\nDocker containerization used within the tutorial. The `KEYROCK_URL` variable with the value `localhost` is referring\nto the location externally exposed by the container, the `KEYROCK_IP_ADDRESS` variable refers to the same location\nbut accessed from within the Docker network. Similarly the `CALLBACK_URL` contains `localhost` as it\nis assumed that the browser will be accessed from the same machine. All of these values should be replaced\nwith appropriate proxies and DNS settings for a production environment, but production deployment is beyond\nthe scope of this tutorial.\n\n\n# Start Up\n\nTo start the installation, do the following:\n\n```console\ngit clone git@github.com:Fiware/tutorials.Securing-Access.git\ncd tutorials.Securing-Access\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.Securing-Access/blob/master/services) Bash script provided within the repository:\n\n```console\n./services \n```\n\nWhere `` 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-0000-0000-0000-000000000000`|\n| Management | Management Group for Store Managers |`managers-0000-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` |\n\n\nTo save time, the data creating users and organizations from the [previous tutorial](https://github.com/Fiware/tutorials.Identity-Management) has been downloaded and is automatically persisted to the MySQL\ndatabase on start-up so the asigned UUIDs do not change and the data does not need to be entered again.\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.Securing-Access/img/log-in.png)\n\nand look around.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ diff --git a/README.ja.md b/README.ja.md index 82a3118..58abf83 100644 --- a/README.ja.md +++ b/README.ja.md @@ -21,7 +21,7 @@ OpenID Connect フローを使用してユーザを認証します。 - [JSON Web Tokens の標準概念](#standard-concepts-of-json-web-tokens) - [前提条件](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [アーキテクチャ](#architecture) - [チュートリアルのセキュリティ設定](#tutorial-security-configuration) - [起動](#start-up) @@ -168,11 +168,9 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaXNzIjoiaHR0cHM してインストールされますが、Linux ユーザは[ここ](https://docs.docker.com/compose/install/)に記載されている手順に従う 必要があります。 - +## WSL -## Cygwin - -シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは [cygwin](http://www.cygwin.com/) を +シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは [を使用して Windows に Linux をインストールする方法](https://learn.microsoft.com/ja-jp/windows/wsl/install) を ダウンロードして、Windows 上の Linux ディストリビューションと同様のコマンドライン機能を提供する必要があります。 diff --git a/README.md b/README.md index 9b735cb..29316b6 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ This tutorial also secures access to a FIWARE application but using various Open - [Standard Concepts of Json Web Tokens](#standard-concepts-of-json-web-tokens) - [Prerequisites](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [Architecture](#architecture) - [Tutorial Security Configuration](#tutorial-security-configuration) - [Start Up](#start-up) @@ -155,10 +155,11 @@ is used configure the required services for the application. This means all cont single command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users will need to follow the instructions found [here](https://docs.docker.com/compose/install/) -## Cygwin +## WSL -We will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/) -to provide a command-line functionality similar to a Linux distribution on Windows. +We will start up our services using a simple bash script. Windows users should download the +[Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to provide a command-line +functionality similar to a Linux distribution on Windows. # Architecture