From b6ed03b7324670316dac31f7474eaab51055b7d2 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 4 Jun 2024 10:18:59 +0200 Subject: [PATCH] Switch to WSL --- FIWARE XACML Rules.postman_collection.json | 2 +- README.ja.md | 8 +++----- README.md | 9 +++++---- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/FIWARE XACML Rules.postman_collection.json b/FIWARE XACML Rules.postman_collection.json index 78992e8..7ba3e33 100644 --- a/FIWARE XACML Rules.postman_collection.json +++ b/FIWARE XACML Rules.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "6554748b-8871-4e83-8c4d-7ab315f9894a", "name": "FIWARE XACML Rules", - "description": "[![FIWARE Security](https://nexus.lab.fiware.org/repository/raw/public/badges/chapters/security.svg)](https://github.com/FIWARE/catalogue/blob/master/security/README.md)\n\nThis tutorial introduces an additional security generic enabler - **Authzforce**\nand adds fine grained control to the security rules generated by **Keyrock**.\nAccess to the entities created in the\n[previous tutorial](https://github.com/Fiware/tutorials.PEP-Proxy) is now\nconfigured and controlled using an XACML access control policy - this creates a\nflexible ruleset which can be uploaded and reinterpreted on the fly so complex\nbusiness rules can be created and changed according to current circumstances.\n\nThe tutorial discusses code showing how to integrate **Authzforce** within a web\napplication and demonstrates examples of **Authzforce** XACML Server-PDP\ninteractions. [cUrl](https://ec.haxx.se/) commands are used to show the\ninteractions between generic enablers.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.XACML-Access-Rules/icon/GitHub-Mark-32px.png) [FIWARE 405: Ruleset Based Permissions](https://github.com/Fiware/tutorials.XACML-Access-Rules)\n\n\n# Ruleset Based Permissions\n\n> \"Say: Come, I will rehearse what _Allah_ hath prohibited you from:\n>\n> - Join not anything as equal with _Him_\n> - Be good to your parents\n> - Kill not your children on a plea of want - _We_ provide sustenance for you\n> and for them\n> - Come not nigh to shameful deeds. Whether open or secret\n> - Take not life, which _Allah_ hath made sacred, except by way of justice\n> and law\n>\n> thus doth _He_ command you, that ye may learn wisdom.\"\n>\n> — Quran 6.151, Sūrat al-Anʻām\n\n[Previous tutorials](https://github.com/Fiware/tutorials.Securing-Access) have\nintroduced a simple access control system based on authentication (level 1) or\nbasic authorization access to resources based on a role (level 2). These\npolicies are easy to create, but the rules within them are very black and white,\nrules cannot rely on one another, have exception clauses or offer access based\non time limits or attribute values. There is also no mechanism to resolve\ndifferent rules in the case of conflict.\n\nTo satisfy a complex access control scenario, an additional arbitration\nmicroservice is required, which is able to come to a judgement on each\nPermit/Deny policy decision by reading and interpreting the full set of access\ncontrol rules, and based their judgement on the evidence provided by the\nrequesting service.\n\nFIWARE [Authzforce](https://authzforce-ce-fiware.readthedocs.io/) is a service\nwhich is able to provide such an interpretive Policy Decision Point (PDP). It is\nan advanced access control Generic Enabler which is able to interpret rules\nsupplied using the\n[XACML standard](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xacml).\nRulesets can be amended and uploaded at any time providing a flexible method to\nmaintain security policies which can change according to business need.\nFurthermore the language used to describe the access policy is designed to be\nhighly extensible and cover any access control scenario.\n\n## What is XACML\n\neXtensible Access Control Markup Language (XACML) is a vendor neutral\ndeclarative access control policy language. It was created to promote common\naccess control terminology and interoperability. The architectural naming\nconventions for elements such as Policy Execution Point (PEP) and Policy\nDecision Point (PDP) come from the XACML specifications.\n\nXACML policies are split into a hierarchy of three levels - ``,\n`` and ``, the `` is a collection of ``\nelements each of which contain one or more `` elements.\n\nEach `` within a `` is evaluated as to whether it should grant\naccess to a resource - the overall `` result is defined by the overall\nresult of all `` elements processed in turn. Separate `` results\nare then evaluated against each other using combining alogorthms define which\n`` wins in case of conflict.\n\nA `` element consists of a `` and a ``. This is an\nexample ``, it states access will be granted (`Effect=\"Permit\"`) when a\nPOST request is sent to the `/bell/ring` endpoint, provided that the\n`subject:role` has been provided and that the\n`role=security-role-0000-0000-000000000000` :\n\n```xml\n\n Ring Alarm Bell\n \n \n \n \n /bell/ring\n \n \n \n \n \n \n \n POST\n \n \n \n \n \n \n \n \n security-role-0000-0000-000000000000\n \n \n \n\n```\n\nThis is a very verbose method for creating a simple Verb-Resource access rule,\nbut unlike simple Verb-Resource rules, with XACML, other more complex\ncomparisons can be made, for example checking that time is before a certain hour\nof day, or checking that a URL starts with or contains a certain string.\nConditions can be specified down to the attribute level or combined to make\ncomplex calculations, for example - an XACML `` could be created to apply\nthe following policy:\n\n> _A store manager is able to amend Product prices only the first of the month,\n> and can only alter prices of products she or her immediate superior has\n> created in the first place_\n\nSuch a `` would require that the `` includes separate\nclauses/clarifications for the following:\n\n- What is the User's role? (e.g. `manager`)\n- What action is being invoked? (e.g PATCH or PUT)\n- Which resource is being protected URL string? (e.g. `/v2/entities`)\n- What other information must be present in the body of the request? (e.g.\n Entity `type` must equal `Product`)\n- When is the resource being requested? (e.g. the current date)\n- What other additional information must be retrieved from elsewhere prior to\n making the request\n - Who created the entity? Is it me or my manager?\n\nAs you can see these rules can quickly become very complex. For this initial\nintroduction to XACML, the basic rule set used will be kept as simple as\npossible to avoid unnecessary confusion, suffice it to say that an access policy\nbased on XACML can be expanded to fit the security needs of any complex system.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using\n[Docker](https://www.docker.com). **Docker** is a container technology which\nallows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions\n [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions\n [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions\n [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker\napplications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Identity-Management/master/docker-compose.yml)\nis used configure the required services for the application. This means all\ncontainer services can be brought up in a single command. Docker Compose is\ninstalled by default as part of Docker for Windows and Docker for Mac, however\nLinux users will need to follow the instructions found\n[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\ndownload [cygwin](http://www.cygwin.com/) to provide a command-line\nfunctionality similar to a Linux distribution on Windows.\n\n# Architecture\n\nThis application adds level 3 Advanced Authorization security into the existing\nStock Management and Sensors-based application created in\n[previous tutorials](https://github.com/Fiware/tutorials.Securing-Access/) and\nsecures access to the context broker behind a\n[PEP Proxy](https://github.com/Fiware/tutorials.PEP-Proxy/). It will make use of\nfive FIWARE components - the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/),the\n[IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/),\nthe [Keyrock](https://fiware-idm.readthedocs.io/en/latest/) Identity Manager,\nthe [Wilma]() PEP Proxy and the\n[Authzforce](https://authzforce-ce-fiware.readthedocs.io) XACML Server. All\naccess control decisions will be delegated to **Authzforce** which will read the\nruleset from a previously uploaded policy domain.\n\nBoth the Orion Context Broker and the IoT Agent rely on open source\n[MongoDB](https://www.mongodb.com/) technology to keep persistence of the\ninformation they hold. We will also be using the dummy IoT devices created in\nthe [previous tutorial](https://github.com/Fiware/tutorials.IoT-Sensors/).\n**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\n [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which\n will receive requests using\n [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n- The FIWARE\n [IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/)\n which will receive southbound requests using\n [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) and convert\n them to\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n commands for the devices\n- FIWARE [Keyrock](https://fiware-idm.readthedocs.io/en/latest/) offer a\n complement Identity Management System including:\n - An OAuth2 authentication system for Applications and Users\n - A site graphical frontend for Identity Management Administration\n - An equivalent REST API for Identity Management via HTTP requests\n- FIWARE [Authzforce](https://authzforce-ce-fiware.readthedocs.io/) is a XACML\n Server providing an interpretive Policy Decision Point (PDP) access to the\n **Orion** and/or **IoT Agent** microservices\n- FIWARE [Wilma](https://fiware-pep-proxy.rtfd.io/) is a PEP Proxy securing\n access to the **Orion** microservices, it delegates the passing of\n authorisation decisions to **Authzforce** PDP\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the **Orion Context Broker** to hold context data information\n such as data entities, subscriptions and registrations\n - Used by the **IoT Agent** to hold device information such as device URLs\n 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, it also delegates\n authoriation decisions to the **Authzforce** PDP\n- A webserver acting as set of\n [dummy IoT devices](https://github.com/Fiware/tutorials.IoT-Sensors) using\n the\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n protocol running over HTTP - access to certain resources is restricted.\n\nSince all interactions between the elements are initiated by HTTP requests, the\nentities can be containerized and run from exposed ports.\n\n![](https://fiware.github.io/tutorials.XACML-Access-Rules/img/architecture.png)\n\nThe specific architecture of each section of the tutorial is discussed below.\n\n## Keyrock Configuration\n\n```yaml\nkeyrock:\n image: quay.io/fiware/idm\n container_name: fiware-keyrock\n hostname: keyrock\n networks:\n default:\n ipv4_address: 172.18.1.5\n depends_on:\n - mysql-db\n - authzforce\n ports:\n - \"3005:3005\"\n environment:\n - DEBUG=idm:*\n - DATABASE_HOST=mysql-db\n - IDM_DB_PASS_FILE=/run/secrets/my_secret_data\n - IDM_DB_USER=root\n - IDM_HOST=http://localhost:3005\n - IDM_PORT=3005\n - IDM_ADMIN_USER=alice\n - IDM_ADMIN_EMAIL=alice-the-admin@test.com\n - IDM_ADMIN_PASS=test\n - IDM_PDP_LEVEL=advanced\n - IDM_AUTHZFORCE_ENABLED=true\n - IDM_AUTHZFORCE_HOST=authzforce\n - IDM_AUTHZFORCE_PORT=8080\n secrets:\n - my_secret_data\n```\n\nThe `keyrock` container is a web application server listening on a single port:\n\n- Port `3005` has been exposed for HTTP traffic so we can display the web page\n and interact with the REST API.\n\nThe `keyrock` container is connecting to **Authzforce** and is driven by\nenvironment variables as shown:\n\n| Key | Value | Description |\n| ---------------------- | ------------ | ---------------------------------------------------------------------------- |\n| IDM_PDP_LEVEL | `advanced` | Flag indicating that **Keyrock** should delegate PDP decisions to Authzforce |\n| IDM_AUTHZFORCE_ENABLED | `true` | Flag indicating that **Authzforce** is available |\n| IDM_AUTHZFORCE_HOST | `authzforce` | This is URL where the **Authzforce** is found |\n| IDM_AUTHZFORCE_PORT | `8080` | Port that **Authzforce** is listening on |\n\nThe other `keyrock` container configuration values described in the YAML file\nhave been described in previous tutorials\n\n## PEP Proxy Configuration\n\n```yaml\norion-proxy:\n image: quay.io/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 - authzforce\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_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=authzforce\n - PEP_PROXY_AUTH_ENABLED=true\n - PEP_PROXY_MAGIC_KEY=1234\n - PEP_PROXY_AZF_PROTOCOL=http\n - PEP_PROXY_AZF_HOST=authzforce\n - PEP_PROXY_AZF_PORT=8080\n```\n\nThe `orion-proxy` container is an instance of FIWARE **Wilma** listening on port\n`1027`, it is configured to forward traffic to `orion` on port `1026`, which is\nthe default port that the Orion Context Broker is listening to for NGSI\nRequests.\n\nThe `orion-proxy` container is delegating PDP decisions to **Authzforce** and is\ndriven by environment variables as shown:\n\n| Key | Value | Description |\n| ---------------------- | ------------ | --------------------------------------------------------- |\n| PEP_PROXY_PDP | `authzforce` | Flag ensuring that the PEP Proxy uses Authzforce as a PDP |\n| PEP_PROXY_AZF_PROTOCOL | `http` | Flag to enable use of the XACML PDP |\n| PEP_PROXY_AZF_HOST | `authzforce` | This is URL where the **Authzforce** is found users |\n| PEP_PROXY_AZF_PORT | `8080` | Port that **Authzforce** is listening on |\n\nThe other `orion-proxy` container configuration values described in the YAML\nfile have been described in previous tutorials\n\n## Authzforce Configuration\n\n```yaml\nauthzforce:\n image: fiware/authzforce-ce-server\n hostname: authzforce\n container_name: fiware-authzforce\n networks:\n default:\n ipv4_address: 172.18.1.12\n ports:\n - \"8080:8080\"\n volumes:\n - ./authzforce/domains:/opt/authzforce-ce-server/data/domains\n```\n\nThe `authzforce` container is listening on port `8080`, where it receives\nrequests to make PDP decisions. A volume has been exposed to upload a\npre-configured domain so that a set of XACML access control policies has already\nbeen supplied.\n\n## Tutorial Security Configuration\n\n```yaml\ntutorial:\n image: quay.io/fiware/tutorials.context-provider\n hostname: iot-sensors\n container_name: fiware-tutorial\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 - \"AUTHZFORCE_ENABLED=true\"\n - \"AUTHZFORCE_URL=http://authzforce\"\n - \"AUTHZFORCE_PORT=8080\"\n```\n\nThe `tutorial` container is listening on two ports:\n\n- Port `3000` is exposed so we can see the web page displaying the Dummy IoT\n devices.\n- Port `3001` is exposed purely for tutorial access - so that cUrl or Postman\n can make UltraLight commands without being part of the same network.\n\nThe `tutorial` container is now secured by **Authforce**, and is driven by\nenvironment variables as shown:\n\n| Key | Value | Description |\n| ------------------ | ------------------- | --------------------------------------------------- |\n| AUTHZFORCE_ENABLED | `true` | Flag to enable use of the XACML PDP |\n| AUTHZFORCE_URL | `http://authzforce` | This is URL where the **Authzforce** is found users |\n| AUTHZFORCE_PORT | `8080` | Port that **Authzforce** is listening on |\n\nThe other `tutorial` container configuration values described in the YAML file\nhave been described in previous tutorials\n\n# Start Up\n\nTo start the installation, do the following:\n\n```console\ngit clone git@github.com:Fiware/tutorials.XACML-Access-Rules.git\ncd tutorials.XACML-Access-Rules\n\n./services create\n```\n\n> **Note** The initial creation of Docker images can take up to three minutes\n\nThereafter, all services can be initialized from the command-line by running the\n[services](https://github.com/Fiware/tutorials.XACML-Access-Rules/blob/master/services)\nBash script provided within the repository:\n\n```console\n./services start\n```\n\n> :information_source: **Note:** If you want to clean up and start over again\n> you can do so with the following command:\n>\n> ```console\n> ./services stop\n> ```\n\n### Dramatis Personae\n\nThe following people at `test.com` legitimately have accounts within the\nApplication\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\n managers under him:\n - Manager1\n - Manager2\n- Charlie, the Head of Security of the supermarket chain - he has several\n 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\nThe following people at `example.com` have signed up for accounts, but have no\nreason to be granted access\n\n- Eve - Eve the Eavesdropper\n- Mallory - Mallory the malicious attacker\n- Rob - Rob the Robber\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", + "description": "[![FIWARE Security](https://nexus.lab.fiware.org/repository/raw/public/badges/chapters/security.svg)](https://github.com/FIWARE/catalogue/blob/master/security/README.md)\n\nThis tutorial introduces an additional security generic enabler - **Authzforce**\nand adds fine grained control to the security rules generated by **Keyrock**.\nAccess to the entities created in the\n[previous tutorial](https://github.com/Fiware/tutorials.PEP-Proxy) is now\nconfigured and controlled using an XACML access control policy - this creates a\nflexible ruleset which can be uploaded and reinterpreted on the fly so complex\nbusiness rules can be created and changed according to current circumstances.\n\nThe tutorial discusses code showing how to integrate **Authzforce** within a web\napplication and demonstrates examples of **Authzforce** XACML Server-PDP\ninteractions. [cUrl](https://ec.haxx.se/) commands are used to show the\ninteractions between generic enablers.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.XACML-Access-Rules/icon/GitHub-Mark-32px.png) [FIWARE 405: Ruleset Based Permissions](https://github.com/Fiware/tutorials.XACML-Access-Rules)\n\n\n# Ruleset Based Permissions\n\n> \"Say: Come, I will rehearse what _Allah_ hath prohibited you from:\n>\n> - Join not anything as equal with _Him_\n> - Be good to your parents\n> - Kill not your children on a plea of want - _We_ provide sustenance for you\n> and for them\n> - Come not nigh to shameful deeds. Whether open or secret\n> - Take not life, which _Allah_ hath made sacred, except by way of justice\n> and law\n>\n> thus doth _He_ command you, that ye may learn wisdom.\"\n>\n> — Quran 6.151, Sūrat al-Anʻām\n\n[Previous tutorials](https://github.com/Fiware/tutorials.Securing-Access) have\nintroduced a simple access control system based on authentication (level 1) or\nbasic authorization access to resources based on a role (level 2). These\npolicies are easy to create, but the rules within them are very black and white,\nrules cannot rely on one another, have exception clauses or offer access based\non time limits or attribute values. There is also no mechanism to resolve\ndifferent rules in the case of conflict.\n\nTo satisfy a complex access control scenario, an additional arbitration\nmicroservice is required, which is able to come to a judgement on each\nPermit/Deny policy decision by reading and interpreting the full set of access\ncontrol rules, and based their judgement on the evidence provided by the\nrequesting service.\n\nFIWARE [Authzforce](https://authzforce-ce-fiware.readthedocs.io/) is a service\nwhich is able to provide such an interpretive Policy Decision Point (PDP). It is\nan advanced access control Generic Enabler which is able to interpret rules\nsupplied using the\n[XACML standard](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xacml).\nRulesets can be amended and uploaded at any time providing a flexible method to\nmaintain security policies which can change according to business need.\nFurthermore the language used to describe the access policy is designed to be\nhighly extensible and cover any access control scenario.\n\n## What is XACML\n\neXtensible Access Control Markup Language (XACML) is a vendor neutral\ndeclarative access control policy language. It was created to promote common\naccess control terminology and interoperability. The architectural naming\nconventions for elements such as Policy Execution Point (PEP) and Policy\nDecision Point (PDP) come from the XACML specifications.\n\nXACML policies are split into a hierarchy of three levels - ``,\n`` and ``, the `` is a collection of ``\nelements each of which contain one or more `` elements.\n\nEach `` within a `` is evaluated as to whether it should grant\naccess to a resource - the overall `` result is defined by the overall\nresult of all `` elements processed in turn. Separate `` results\nare then evaluated against each other using combining alogorthms define which\n`` wins in case of conflict.\n\nA `` element consists of a `` and a ``. This is an\nexample ``, it states access will be granted (`Effect=\"Permit\"`) when a\nPOST request is sent to the `/bell/ring` endpoint, provided that the\n`subject:role` has been provided and that the\n`role=security-role-0000-0000-000000000000` :\n\n```xml\n\n Ring Alarm Bell\n \n \n \n \n /bell/ring\n \n \n \n \n \n \n \n POST\n \n \n \n \n \n \n \n \n security-role-0000-0000-000000000000\n \n \n \n\n```\n\nThis is a very verbose method for creating a simple Verb-Resource access rule,\nbut unlike simple Verb-Resource rules, with XACML, other more complex\ncomparisons can be made, for example checking that time is before a certain hour\nof day, or checking that a URL starts with or contains a certain string.\nConditions can be specified down to the attribute level or combined to make\ncomplex calculations, for example - an XACML `` could be created to apply\nthe following policy:\n\n> _A store manager is able to amend Product prices only the first of the month,\n> and can only alter prices of products she or her immediate superior has\n> created in the first place_\n\nSuch a `` would require that the `` includes separate\nclauses/clarifications for the following:\n\n- What is the User's role? (e.g. `manager`)\n- What action is being invoked? (e.g PATCH or PUT)\n- Which resource is being protected URL string? (e.g. `/v2/entities`)\n- What other information must be present in the body of the request? (e.g.\n Entity `type` must equal `Product`)\n- When is the resource being requested? (e.g. the current date)\n- What other additional information must be retrieved from elsewhere prior to\n making the request\n - Who created the entity? Is it me or my manager?\n\nAs you can see these rules can quickly become very complex. For this initial\nintroduction to XACML, the basic rule set used will be kept as simple as\npossible to avoid unnecessary confusion, suffice it to say that an access policy\nbased on XACML can be expanded to fit the security needs of any complex system.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using\n[Docker](https://www.docker.com). **Docker** is a container technology which\nallows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions\n [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions\n [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions\n [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker\napplications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Identity-Management/master/docker-compose.yml)\nis used configure the required services for the application. This means all\ncontainer services can be brought up in a single command. Docker Compose is\ninstalled by default as part of Docker for Windows and Docker for Mac, however\nLinux users will need to follow the instructions found\n[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\ndownload the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to provide a command-line\nfunctionality similar to a Linux distribution on Windows.\n\n# Architecture\n\nThis application adds level 3 Advanced Authorization security into the existing\nStock Management and Sensors-based application created in\n[previous tutorials](https://github.com/Fiware/tutorials.Securing-Access/) and\nsecures access to the context broker behind a\n[PEP Proxy](https://github.com/Fiware/tutorials.PEP-Proxy/). It will make use of\nfive FIWARE components - the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/),the\n[IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/),\nthe [Keyrock](https://fiware-idm.readthedocs.io/en/latest/) Identity Manager,\nthe [Wilma]() PEP Proxy and the\n[Authzforce](https://authzforce-ce-fiware.readthedocs.io) XACML Server. All\naccess control decisions will be delegated to **Authzforce** which will read the\nruleset from a previously uploaded policy domain.\n\nBoth the Orion Context Broker and the IoT Agent rely on open source\n[MongoDB](https://www.mongodb.com/) technology to keep persistence of the\ninformation they hold. We will also be using the dummy IoT devices created in\nthe [previous tutorial](https://github.com/Fiware/tutorials.IoT-Sensors/).\n**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\n [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which\n will receive requests using\n [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n- The FIWARE\n [IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/)\n which will receive southbound requests using\n [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) and convert\n them to\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n commands for the devices\n- FIWARE [Keyrock](https://fiware-idm.readthedocs.io/en/latest/) offer a\n complement Identity Management System including:\n - An OAuth2 authentication system for Applications and Users\n - A site graphical frontend for Identity Management Administration\n - An equivalent REST API for Identity Management via HTTP requests\n- FIWARE [Authzforce](https://authzforce-ce-fiware.readthedocs.io/) is a XACML\n Server providing an interpretive Policy Decision Point (PDP) access to the\n **Orion** and/or **IoT Agent** microservices\n- FIWARE [Wilma](https://fiware-pep-proxy.rtfd.io/) is a PEP Proxy securing\n access to the **Orion** microservices, it delegates the passing of\n authorisation decisions to **Authzforce** PDP\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the **Orion Context Broker** to hold context data information\n such as data entities, subscriptions and registrations\n - Used by the **IoT Agent** to hold device information such as device URLs\n 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, it also delegates\n authoriation decisions to the **Authzforce** PDP\n- A webserver acting as set of\n [dummy IoT devices](https://github.com/Fiware/tutorials.IoT-Sensors) using\n the\n [UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)\n protocol running over HTTP - access to certain resources is restricted.\n\nSince all interactions between the elements are initiated by HTTP requests, the\nentities can be containerized and run from exposed ports.\n\n![](https://fiware.github.io/tutorials.XACML-Access-Rules/img/architecture.png)\n\nThe specific architecture of each section of the tutorial is discussed below.\n\n## Keyrock Configuration\n\n```yaml\nkeyrock:\n image: quay.io/fiware/idm\n container_name: fiware-keyrock\n hostname: keyrock\n networks:\n default:\n ipv4_address: 172.18.1.5\n depends_on:\n - mysql-db\n - authzforce\n ports:\n - \"3005:3005\"\n environment:\n - DEBUG=idm:*\n - DATABASE_HOST=mysql-db\n - IDM_DB_PASS_FILE=/run/secrets/my_secret_data\n - IDM_DB_USER=root\n - IDM_HOST=http://localhost:3005\n - IDM_PORT=3005\n - IDM_ADMIN_USER=alice\n - IDM_ADMIN_EMAIL=alice-the-admin@test.com\n - IDM_ADMIN_PASS=test\n - IDM_PDP_LEVEL=advanced\n - IDM_AUTHZFORCE_ENABLED=true\n - IDM_AUTHZFORCE_HOST=authzforce\n - IDM_AUTHZFORCE_PORT=8080\n secrets:\n - my_secret_data\n```\n\nThe `keyrock` container is a web application server listening on a single port:\n\n- Port `3005` has been exposed for HTTP traffic so we can display the web page\n and interact with the REST API.\n\nThe `keyrock` container is connecting to **Authzforce** and is driven by\nenvironment variables as shown:\n\n| Key | Value | Description |\n| ---------------------- | ------------ | ---------------------------------------------------------------------------- |\n| IDM_PDP_LEVEL | `advanced` | Flag indicating that **Keyrock** should delegate PDP decisions to Authzforce |\n| IDM_AUTHZFORCE_ENABLED | `true` | Flag indicating that **Authzforce** is available |\n| IDM_AUTHZFORCE_HOST | `authzforce` | This is URL where the **Authzforce** is found |\n| IDM_AUTHZFORCE_PORT | `8080` | Port that **Authzforce** is listening on |\n\nThe other `keyrock` container configuration values described in the YAML file\nhave been described in previous tutorials\n\n## PEP Proxy Configuration\n\n```yaml\norion-proxy:\n image: quay.io/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 - authzforce\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_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=authzforce\n - PEP_PROXY_AUTH_ENABLED=true\n - PEP_PROXY_MAGIC_KEY=1234\n - PEP_PROXY_AZF_PROTOCOL=http\n - PEP_PROXY_AZF_HOST=authzforce\n - PEP_PROXY_AZF_PORT=8080\n```\n\nThe `orion-proxy` container is an instance of FIWARE **Wilma** listening on port\n`1027`, it is configured to forward traffic to `orion` on port `1026`, which is\nthe default port that the Orion Context Broker is listening to for NGSI\nRequests.\n\nThe `orion-proxy` container is delegating PDP decisions to **Authzforce** and is\ndriven by environment variables as shown:\n\n| Key | Value | Description |\n| ---------------------- | ------------ | --------------------------------------------------------- |\n| PEP_PROXY_PDP | `authzforce` | Flag ensuring that the PEP Proxy uses Authzforce as a PDP |\n| PEP_PROXY_AZF_PROTOCOL | `http` | Flag to enable use of the XACML PDP |\n| PEP_PROXY_AZF_HOST | `authzforce` | This is URL where the **Authzforce** is found users |\n| PEP_PROXY_AZF_PORT | `8080` | Port that **Authzforce** is listening on |\n\nThe other `orion-proxy` container configuration values described in the YAML\nfile have been described in previous tutorials\n\n## Authzforce Configuration\n\n```yaml\nauthzforce:\n image: fiware/authzforce-ce-server\n hostname: authzforce\n container_name: fiware-authzforce\n networks:\n default:\n ipv4_address: 172.18.1.12\n ports:\n - \"8080:8080\"\n volumes:\n - ./authzforce/domains:/opt/authzforce-ce-server/data/domains\n```\n\nThe `authzforce` container is listening on port `8080`, where it receives\nrequests to make PDP decisions. A volume has been exposed to upload a\npre-configured domain so that a set of XACML access control policies has already\nbeen supplied.\n\n## Tutorial Security Configuration\n\n```yaml\ntutorial:\n image: quay.io/fiware/tutorials.context-provider\n hostname: iot-sensors\n container_name: fiware-tutorial\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 - \"AUTHZFORCE_ENABLED=true\"\n - \"AUTHZFORCE_URL=http://authzforce\"\n - \"AUTHZFORCE_PORT=8080\"\n```\n\nThe `tutorial` container is listening on two ports:\n\n- Port `3000` is exposed so we can see the web page displaying the Dummy IoT\n devices.\n- Port `3001` is exposed purely for tutorial access - so that cUrl or Postman\n can make UltraLight commands without being part of the same network.\n\nThe `tutorial` container is now secured by **Authforce**, and is driven by\nenvironment variables as shown:\n\n| Key | Value | Description |\n| ------------------ | ------------------- | --------------------------------------------------- |\n| AUTHZFORCE_ENABLED | `true` | Flag to enable use of the XACML PDP |\n| AUTHZFORCE_URL | `http://authzforce` | This is URL where the **Authzforce** is found users |\n| AUTHZFORCE_PORT | `8080` | Port that **Authzforce** is listening on |\n\nThe other `tutorial` container configuration values described in the YAML file\nhave been described in previous tutorials\n\n# Start Up\n\nTo start the installation, do the following:\n\n```console\ngit clone git@github.com:Fiware/tutorials.XACML-Access-Rules.git\ncd tutorials.XACML-Access-Rules\n\n./services create\n```\n\n> **Note** The initial creation of Docker images can take up to three minutes\n\nThereafter, all services can be initialized from the command-line by running the\n[services](https://github.com/Fiware/tutorials.XACML-Access-Rules/blob/master/services)\nBash script provided within the repository:\n\n```console\n./services start\n```\n\n> :information_source: **Note:** If you want to clean up and start over again\n> you can do so with the following command:\n>\n> ```console\n> ./services stop\n> ```\n\n### Dramatis Personae\n\nThe following people at `test.com` legitimately have accounts within the\nApplication\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\n managers under him:\n - Manager1\n - Manager2\n- Charlie, the Head of Security of the supermarket chain - he has several\n 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\nThe following people at `example.com` have signed up for accounts, but have no\nreason to be granted access\n\n- Eve - Eve the Eavesdropper\n- Mallory - Mallory the malicious attacker\n- Rob - Rob the Robber\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", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ diff --git a/README.ja.md b/README.ja.md index 75ae87c..4eb5bc6 100644 --- a/README.ja.md +++ b/README.ja.md @@ -34,7 +34,7 @@ - [XACML とは](#what-is-xacml) - [前提条件](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [アーキテクチャ](#architecture) - [Keyrock の設定](#keyrock-configuration) - [PEP Proxy の設定](#pep-proxy-configuration) @@ -222,12 +222,10 @@ XACML の最初のイントロダクションでは、不要な混乱を避け [ここ](https://docs.docker.com/compose/install/)に記載されている手順に従う必要 があります。 - - -## Cygwin +## WSL シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは -[cygwin](http://www.cygwin.com/) をダウンロードして、Windows 上の Linux +[を使用して Windows に Linux をインストールする方法](https://learn.microsoft.com/ja-jp/windows/wsl/install) をダウンロードして、Windows 上の Linux ディストリビューションと同様のコマンドライン機能を提供する必要があります。 diff --git a/README.md b/README.md index df2fa43..a42e461 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ between generic enablers. [Postman documentation](https://fiware.github.io/tutor - [What is XACML](#what-is-xacml) - [Prerequisites](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [Architecture](#architecture) - [Keyrock Configuration](#keyrock-configuration) - [PEP Proxy Configuration](#pep-proxy-configuration) @@ -208,10 +208,11 @@ configure the required services for the application. This means all container se 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