From c314bed5bf35827f4515c485bdcf17d8cab3d512 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 4 Jun 2024 10:18:45 +0200 Subject: [PATCH] Switch to WSL --- FIWARE Roles and Permissions.postman_collection.json | 2 +- README.ja.md | 8 +++----- README.md | 9 +++++---- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/FIWARE Roles and Permissions.postman_collection.json b/FIWARE Roles and Permissions.postman_collection.json index c735d3f..8891588 100644 --- a/FIWARE Roles and Permissions.postman_collection.json +++ b/FIWARE Roles and Permissions.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "24108c31-ca17-4451-9829-d4e6bb05aaa3", "name": "FIWARE Roles and Permissions", - "description": "The tutorial explains how to create applications, and how to assign roles and permissions to them.\nIt takes the users and organizations created in the [previous tutorial](https://github.com/Fiware/tutorials.Identity-Management)\nand ensures that only legitmate users will have access to resources.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Identity-Management/icon/GitHub-Mark-32px.png) [FIWARE 402: Roles and Permissions](https://github.com/Fiware/tutorials.Roles-Permissions)\n\n# What is Authorization?\n\n> \"No matter what he does, every person on earth plays a central role in the history of the world.\n> And normally he doesn't know it\"\n>\n> — Paulo Coelho (The Alchemist)\n\n\nAuthorization is the function of specifying access rights/privileges to resources related to information\nsecurity. More formally, \"to authorize\" is to define an access policy. In the case of Keyrock, User\naccess is granted based on permissions assigned to a role.\n\nEvery application secured by the **Keyrock** generic enabler can define a set of permissions - i.e.\na set of things that can be done within the application. For example within the application, the ability\nto send a commmand to unlock a Smart Door could be secured behind a `Unlock Door` permission. Similarly\nthe ability to send a commmand to ring the alarm bell could be secured behind a `Ring Bell` permission,\nand the ability to alter prices could be secured behind a `Price Change` permission\n\nThese permissions are grouped together in a series of roles - for example `Unlock Door` and `Ring Bell`\ncould both be assigned to the Security Role, meaning that Users who are subsequently given that role\nwould gain both permissions.\n\nPermissions can overlap and be assigned to multiple roles - maybe `Ring Bell` is also assigned to the management\nrole along with `Price Change` and `Order Stock`.\n\nIn turn users or organizations will be assigned to one of more roles - each user will gain the sum of all the\npermissions for each role they have. For example if Alice is assigned to both management and security roles,\nshe will gain all four permissions `Unlock Door`, `Ring Bell`, `Price Change` and `Order Stock`.\n\nThe concept of a role is unknown to a user - they only know the list of permissions they have been granted,\nnot how the permissions are split up within the application.\n\nIn summary, permissions are all the possible actions that can be done to resources within an application, whereas roles\nare groups of actions which can be done by a type of user of that application.\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 organiation. This allows each organization\n to be responisible 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 betwen 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:\n\n![](https://fiware.github.io/tutorials.Roles-Permissions/img/entities.png)\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.Entity-Relationships/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\nThis introduction will only make use of one FIWARE component - the [Keyrock](http://fiware-idm.readthedocs.io/)\nIdentity Management Generic Enabler. Usage of **Keyrock** alone alone is insufficient for an application to qualify\n as *“Powered by FIWARE”*. Additionally will be persisting user data in a **MySQL** database.\n\n\nThe overall architecture will consist of the following elements:\n\n* One **FIWARE Generic Enabler**:\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\n* One [MySQL](https://www.mysql.com/) database :\n * Used to persist user identities, applications, roles and permsissions\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\n![](https://fiware.github.io/tutorials.Roles-Permissions/img/architecture.png)\n\nThe specific architecture of each section of the tutorial is discussed below.\n\n## Keyrock Configuration\n\n\n```yaml\n keyrock:\n image: quay.io/fiware/idm\n container_name: fiware-keyrock\n hostname: keyrock\n depends_on:\n - mysql-db\n ports:\n - \"3005:3005\"\n - \"3443:3443\"\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_HTTPS_ENABLED=true\n - IDM_HTTPS_PORT=${KEYROCK_HTTPS_PORT}\n - IDM_ADMIN_USER=alice\n - IDM_ADMIN_EMAIL=alice-the-admin@test.com\n - IDM_ADMIN_PASS=test\n secrets:\n - my_secret_data\n```\n\nThe `keyrock` container is a web application server listening on two ports:\n\n* Port `3005` has been exposed for HTTP traffic so we can display the web page and interact with the REST API.\n* Port `3443` has been exposed for secure HTTPS traffic for the website and REST API\n\n> **Note** HTTPS should be used throughout for any secured application, but to do this properly,\n> **Keyrock** requires a trusted SSL certificate - the default certificate is self-certified and\n> available for testing purposes. The certificates can be overridden by attaching a volume to\n> replace the files under `/opt/fiware-idm/certs`.\n>\n> In a production environment, all access should occur over HTTPS, to avoid sending\n> any sensitive information using plain-text. Alternatively HTTP can be used within a\n> private network behind a configured HTTPS Reverse Proxy\n>\n> The port `3005` offering the HTTP protocol is being exposed for demonstration purposes only and to\n> simplify the interactions within this tutorial - you may also use HTTPS on port `3443` with certain\n> caveats.\n>\n> If you want to use HTTPS to access the REST API when you are using Postman, ensure that SSL\n> certificate verfication is OFF. If you want to use HTTPS to access the web front-end, please\n> accept any security warnings issued.\n\n\n\nThe `keyrock` container is driven by environment variables as shown:\n\n| Key |Value|Description|\n|-----|-----|-----------|\n|IDM_DB_PASS|`idm`| Password of the attached MySQL Database - secured by **Docker Secrets** (see below) |\n|IDM_DB_USER|`root`|User name of the default MySQL user - left in plain-text |\n|IDM_HOST|`http://localhost:3005`| Host name of the **Keyrock** App Server - used in activation eMails when signing up users|\n|IDM_PORT|`3005`| Port used by the **Keyrock** App Server for HTTP traffic - this has been altered from the default 3000 port to avoid clashes |\n|IDM_HTTPS_ENABLED|`true`| Whether to offer HTTPS Support - this will use the self-signed certs unless overridden |\n|IDM_HTTPS_PORT|`3443`| Port used by the **Keyrock** App Server for HTTP traffic this has been altered from the default 443 |\n\n\n> **Note** that this example has secured the MySQL password using **Docker Secrets**\n> By using `IDM_DB_PASS` with the `_FILE` suffix and referring to a secrets file location.\n> This avoids exposing the password as an `ENV` variable in plain-text - either in the `Dockerfile` Image or\n> as an injected variable which could be read using `docker inspect`.\n>\n> The following list of variables (where used) should be set via secrets with the `_FILE` suffix in a Production System:\n>\n> * `IDM_SESSION_SECRET`\n> * `IDM_ENCRYPTION_KEY`\n> * `IDM_DB_PASS`\n> * `IDM_DB_USER`\n> * `IDM_ADMIN_ID`\n> * `IDM_ADMIN_USER`\n> * `IDM_ADMIN_EMAIL`\n> * `IDM_ADMIN_PASS`\n> * `IDM_EX_AUTH_DB_USER`\n> * `IDM_EX_AUTH_DB_PASS`\n\n\n## MySQL Configuration\n\n```yaml\n mysql-db:\n image: mysql:5.7\n hostname: mysql-db\n container_name: db-mysql\n expose:\n - \"3306\"\n ports:\n - \"3306:3306\"\n networks:\n default:\n environment:\n - \"MYSQL_ROOT_PASSWORD_FILE=/run/secrets/my_secret_data\"\n - \"MYSQL_ROOT_HOST=172.18.1.5\"\n volumes:\n - mysql-db:/var/lib/mysql\n secrets:\n - my_secret_data\n```\n\n\nThe `mysql-db` container is listening on a single port:\n\n* Port `3306` is the default port for a MySQL server. It has been exposed so you can also run other database tools to display data if you wish\n\nThe `mysql-db` container is driven by environment variables as shown:\n\n| Key |Value. |Description |\n|-------------------|----------|------------------------------------------|\n|MYSQL_ROOT_PASSWORD|`123`. | specifies a password that is set for the MySQL `root` account - secured by **Docker Secrets** (see below)|\n|MYSQL_ROOT_HOST |`root`| By default, MySQL creates the `root'@'localhost` account. This account can only be connected to from inside the container. Setting this environment variable allows root connections from other hosts |\n\n# Start Up\n\nTo start the installation, do the following:\n\n```console\ngit clone git@github.com:Fiware/tutorials.Roles-Permissions.git\ncd tutorials.Roles-Permissions\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.Roles-Permissions/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> **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\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 | UUID |\n|------------|----------------------------|---------|---------------------------------------|\n| alice | alice-the-admin@test.com | `test` |`aaaaaaaa-good-0000-0000-000000000000` |\n| bob | bob-the-manager@test.com | `test` |`bbbbbbbb-good-0000-0000-000000000000` |\n| charlie | charlie-security@test.com | `test` |`cccccccc-good-0000-0000-000000000000` |\n| manager1 | manager1@test.com | `test` |`manager1-good-0000-0000-000000000000` |\n| manager2 | manager2@test.com | `test` |`manager2-good-0000-0000-000000000000` |\n| detective1 | detective1@test.com | `test` |`secure01-good-0000-0000-000000000000` |\n| detective2 | detective2@test.com | `test` |`secure02-good-0000-0000-000000000000` |\n| eve | eve@example.com | `test` |`eeeeeeee-evil-0000-0000-000000000000` |\n| mallory | mallory@example.com | `test` |`mmmmmmmm-evil-0000-0000-000000000000` |\n| rob | rob@example.com | `test` |`rrrrrrrr-evil-0000-0000-000000000000` |\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\nThe data creating users and organizations from the [previous tutorial](https://github.com/Fiware/tutorials.Identity-Management) has been downloaded:\n\n```console\ndocker exec db-mysql /usr/bin/mysqldump -u root --password=idmx idm > backup.sql\n```\n\nand is injected into the MySQL Database on start-up.\n\n\n\n\nTo refresh your memory about how to create users and organizations, 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.Roles-Permissions/img/log-in.png)\n\nand look at the organizations list.\n\n\n\n### Reading directly from the Keyrock MySQL Database\n\nAll Identify Management records and releationships are held within the the attached MySQL database. This can be\naccessed by entering the running Docker container as shown:\n\n\n```console\ndocker exec -it db-mysql bash\n```\n\n```console\nmysql -u -p idm\n```\n\nWhere `` and `` match the values defined in the `docker-compose` file for `MYSQL_ROOT_PASSWORD`\nand `MYSQL_ROOT_USER`. The default values for the tutorial are usually `root` and `secret`.\n\nSQL commands can then be entered from the command line. e.g.:\n\n```SQL\nselect id, username, email, password from user;\n```\n\n\n### UUIDs within Keyrock\n\nAll ids and tokens within **Keyrock** are subject to change. The following values will need to be amended when\nquerying for records .Record ids use Universally Unique Identifiers - UUIDs.\n\n| Key |Description | Sample Value |\n|-----|-----------------------------------|--------------|\n|`keyrock`| URL for the location of the **Keyrock** service|`localhost:3005`|\n|`X-Auth-token`| Token received in the Header when logging in as a user |`aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa` = I am Alice|\n|`X-Subject-token`|Token to pass when asking about a subject, alternatively repeat the user token |`bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb` = Asking about Bob|\n|`user-id`| id of an existing user, found with the `user` table |`bbbbbbbb-good-0000-0000-000000000000` - Bob's User Id|\n|`application-id`| id of an existing application, found with the `oauth_client` table |`c978218d-ad63-4427-b12b-542b81299cfb`|\n|`role-id`| id of an existing role, found with the `role` table |`d28baa00-839e-4b45-a6b2-1cec563942ee`|\n|`permission-id`| id of an existing permission, found with the `permission` table |`6b6cd19c-9398-4834-9ba1-1616c57139c0`|\n|`organization-id`| id of an existing organization, found with the `organization` table |`e424ed98-c966-46e3-b161-a165fd31bc01`|\n|`organization-role-id`| type of role a user has within an organization either `owner` or `member`|`member`|\n|`iot-agent-id`| id of an existing IoT Agent, found with the `iot` table |`iot_sensor_f3d0245b-3330-4e64-a513-81bf4b0dae64`|\n|`pep-proxy-id`| id of an existing PEP Proxy, found with the `pep_proxy` table |`iot_sensor_f3d0245b-3330-4e64-a513-81bf4b0dae64`|\n\nTokens are designed to expire after a set period. If the `X-Auth-token` value you are using has expired, log-in again to obtain a new token. For this tutorial, a long lasting set of tokens has been created for each user and persisted into the database,\nso there is usually no need to refresh tokens.", + "description": "The tutorial explains how to create applications, and how to assign roles and permissions to them.\nIt takes the users and organizations created in the [previous tutorial](https://github.com/Fiware/tutorials.Identity-Management)\nand ensures that only legitmate users will have access to resources.\n\nThe `docker-compose` files for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Identity-Management/icon/GitHub-Mark-32px.png) [FIWARE 402: Roles and Permissions](https://github.com/Fiware/tutorials.Roles-Permissions)\n\n# What is Authorization?\n\n> \"No matter what he does, every person on earth plays a central role in the history of the world.\n> And normally he doesn't know it\"\n>\n> — Paulo Coelho (The Alchemist)\n\n\nAuthorization is the function of specifying access rights/privileges to resources related to information\nsecurity. More formally, \"to authorize\" is to define an access policy. In the case of Keyrock, User\naccess is granted based on permissions assigned to a role.\n\nEvery application secured by the **Keyrock** generic enabler can define a set of permissions - i.e.\na set of things that can be done within the application. For example within the application, the ability\nto send a commmand to unlock a Smart Door could be secured behind a `Unlock Door` permission. Similarly\nthe ability to send a commmand to ring the alarm bell could be secured behind a `Ring Bell` permission,\nand the ability to alter prices could be secured behind a `Price Change` permission\n\nThese permissions are grouped together in a series of roles - for example `Unlock Door` and `Ring Bell`\ncould both be assigned to the Security Role, meaning that Users who are subsequently given that role\nwould gain both permissions.\n\nPermissions can overlap and be assigned to multiple roles - maybe `Ring Bell` is also assigned to the management\nrole along with `Price Change` and `Order Stock`.\n\nIn turn users or organizations will be assigned to one of more roles - each user will gain the sum of all the\npermissions for each role they have. For example if Alice is assigned to both management and security roles,\nshe will gain all four permissions `Unlock Door`, `Ring Bell`, `Price Change` and `Order Stock`.\n\nThe concept of a role is unknown to a user - they only know the list of permissions they have been granted,\nnot how the permissions are split up within the application.\n\nIn summary, permissions are all the possible actions that can be done to resources within an application, whereas roles\nare groups of actions which can be done by a type of user of that application.\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 organiation. This allows each organization\n to be responisible 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 betwen 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:\n\n![](https://fiware.github.io/tutorials.Roles-Permissions/img/entities.png)\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.Entity-Relationships/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\nThis introduction will only make use of one FIWARE component - the [Keyrock](http://fiware-idm.readthedocs.io/)\nIdentity Management Generic Enabler. Usage of **Keyrock** alone alone is insufficient for an application to qualify\n as *“Powered by FIWARE”*. Additionally will be persisting user data in a **MySQL** database.\n\n\nThe overall architecture will consist of the following elements:\n\n* One **FIWARE Generic Enabler**:\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\n* One [MySQL](https://www.mysql.com/) database :\n * Used to persist user identities, applications, roles and permsissions\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\n![](https://fiware.github.io/tutorials.Roles-Permissions/img/architecture.png)\n\nThe specific architecture of each section of the tutorial is discussed below.\n\n## Keyrock Configuration\n\n\n```yaml\n keyrock:\n image: quay.io/fiware/idm\n container_name: fiware-keyrock\n hostname: keyrock\n depends_on:\n - mysql-db\n ports:\n - \"3005:3005\"\n - \"3443:3443\"\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_HTTPS_ENABLED=true\n - IDM_HTTPS_PORT=${KEYROCK_HTTPS_PORT}\n - IDM_ADMIN_USER=alice\n - IDM_ADMIN_EMAIL=alice-the-admin@test.com\n - IDM_ADMIN_PASS=test\n secrets:\n - my_secret_data\n```\n\nThe `keyrock` container is a web application server listening on two ports:\n\n* Port `3005` has been exposed for HTTP traffic so we can display the web page and interact with the REST API.\n* Port `3443` has been exposed for secure HTTPS traffic for the website and REST API\n\n> **Note** HTTPS should be used throughout for any secured application, but to do this properly,\n> **Keyrock** requires a trusted SSL certificate - the default certificate is self-certified and\n> available for testing purposes. The certificates can be overridden by attaching a volume to\n> replace the files under `/opt/fiware-idm/certs`.\n>\n> In a production environment, all access should occur over HTTPS, to avoid sending\n> any sensitive information using plain-text. Alternatively HTTP can be used within a\n> private network behind a configured HTTPS Reverse Proxy\n>\n> The port `3005` offering the HTTP protocol is being exposed for demonstration purposes only and to\n> simplify the interactions within this tutorial - you may also use HTTPS on port `3443` with certain\n> caveats.\n>\n> If you want to use HTTPS to access the REST API when you are using Postman, ensure that SSL\n> certificate verfication is OFF. If you want to use HTTPS to access the web front-end, please\n> accept any security warnings issued.\n\n\n\nThe `keyrock` container is driven by environment variables as shown:\n\n| Key |Value|Description|\n|-----|-----|-----------|\n|IDM_DB_PASS|`idm`| Password of the attached MySQL Database - secured by **Docker Secrets** (see below) |\n|IDM_DB_USER|`root`|User name of the default MySQL user - left in plain-text |\n|IDM_HOST|`http://localhost:3005`| Host name of the **Keyrock** App Server - used in activation eMails when signing up users|\n|IDM_PORT|`3005`| Port used by the **Keyrock** App Server for HTTP traffic - this has been altered from the default 3000 port to avoid clashes |\n|IDM_HTTPS_ENABLED|`true`| Whether to offer HTTPS Support - this will use the self-signed certs unless overridden |\n|IDM_HTTPS_PORT|`3443`| Port used by the **Keyrock** App Server for HTTP traffic this has been altered from the default 443 |\n\n\n> **Note** that this example has secured the MySQL password using **Docker Secrets**\n> By using `IDM_DB_PASS` with the `_FILE` suffix and referring to a secrets file location.\n> This avoids exposing the password as an `ENV` variable in plain-text - either in the `Dockerfile` Image or\n> as an injected variable which could be read using `docker inspect`.\n>\n> The following list of variables (where used) should be set via secrets with the `_FILE` suffix in a Production System:\n>\n> * `IDM_SESSION_SECRET`\n> * `IDM_ENCRYPTION_KEY`\n> * `IDM_DB_PASS`\n> * `IDM_DB_USER`\n> * `IDM_ADMIN_ID`\n> * `IDM_ADMIN_USER`\n> * `IDM_ADMIN_EMAIL`\n> * `IDM_ADMIN_PASS`\n> * `IDM_EX_AUTH_DB_USER`\n> * `IDM_EX_AUTH_DB_PASS`\n\n\n## MySQL Configuration\n\n```yaml\n mysql-db:\n image: mysql:5.7\n hostname: mysql-db\n container_name: db-mysql\n expose:\n - \"3306\"\n ports:\n - \"3306:3306\"\n networks:\n default:\n environment:\n - \"MYSQL_ROOT_PASSWORD_FILE=/run/secrets/my_secret_data\"\n - \"MYSQL_ROOT_HOST=172.18.1.5\"\n volumes:\n - mysql-db:/var/lib/mysql\n secrets:\n - my_secret_data\n```\n\n\nThe `mysql-db` container is listening on a single port:\n\n* Port `3306` is the default port for a MySQL server. It has been exposed so you can also run other database tools to display data if you wish\n\nThe `mysql-db` container is driven by environment variables as shown:\n\n| Key |Value. |Description |\n|-------------------|----------|------------------------------------------|\n|MYSQL_ROOT_PASSWORD|`123`. | specifies a password that is set for the MySQL `root` account - secured by **Docker Secrets** (see below)|\n|MYSQL_ROOT_HOST |`root`| By default, MySQL creates the `root'@'localhost` account. This account can only be connected to from inside the container. Setting this environment variable allows root connections from other hosts |\n\n# Start Up\n\nTo start the installation, do the following:\n\n```console\ngit clone git@github.com:Fiware/tutorials.Roles-Permissions.git\ncd tutorials.Roles-Permissions\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.Roles-Permissions/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> **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\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 | UUID |\n|------------|----------------------------|---------|---------------------------------------|\n| alice | alice-the-admin@test.com | `test` |`aaaaaaaa-good-0000-0000-000000000000` |\n| bob | bob-the-manager@test.com | `test` |`bbbbbbbb-good-0000-0000-000000000000` |\n| charlie | charlie-security@test.com | `test` |`cccccccc-good-0000-0000-000000000000` |\n| manager1 | manager1@test.com | `test` |`manager1-good-0000-0000-000000000000` |\n| manager2 | manager2@test.com | `test` |`manager2-good-0000-0000-000000000000` |\n| detective1 | detective1@test.com | `test` |`secure01-good-0000-0000-000000000000` |\n| detective2 | detective2@test.com | `test` |`secure02-good-0000-0000-000000000000` |\n| eve | eve@example.com | `test` |`eeeeeeee-evil-0000-0000-000000000000` |\n| mallory | mallory@example.com | `test` |`mmmmmmmm-evil-0000-0000-000000000000` |\n| rob | rob@example.com | `test` |`rrrrrrrr-evil-0000-0000-000000000000` |\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\nThe data creating users and organizations from the [previous tutorial](https://github.com/Fiware/tutorials.Identity-Management) has been downloaded:\n\n```console\ndocker exec db-mysql /usr/bin/mysqldump -u root --password=idmx idm > backup.sql\n```\n\nand is injected into the MySQL Database on start-up.\n\n\n\n\nTo refresh your memory about how to create users and organizations, 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.Roles-Permissions/img/log-in.png)\n\nand look at the organizations list.\n\n\n\n### Reading directly from the Keyrock MySQL Database\n\nAll Identify Management records and releationships are held within the the attached MySQL database. This can be\naccessed by entering the running Docker container as shown:\n\n\n```console\ndocker exec -it db-mysql bash\n```\n\n```console\nmysql -u -p idm\n```\n\nWhere `` and `` match the values defined in the `docker-compose` file for `MYSQL_ROOT_PASSWORD`\nand `MYSQL_ROOT_USER`. The default values for the tutorial are usually `root` and `secret`.\n\nSQL commands can then be entered from the command line. e.g.:\n\n```SQL\nselect id, username, email, password from user;\n```\n\n\n### UUIDs within Keyrock\n\nAll ids and tokens within **Keyrock** are subject to change. The following values will need to be amended when\nquerying for records .Record ids use Universally Unique Identifiers - UUIDs.\n\n| Key |Description | Sample Value |\n|-----|-----------------------------------|--------------|\n|`keyrock`| URL for the location of the **Keyrock** service|`localhost:3005`|\n|`X-Auth-token`| Token received in the Header when logging in as a user |`aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa` = I am Alice|\n|`X-Subject-token`|Token to pass when asking about a subject, alternatively repeat the user token |`bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb` = Asking about Bob|\n|`user-id`| id of an existing user, found with the `user` table |`bbbbbbbb-good-0000-0000-000000000000` - Bob's User Id|\n|`application-id`| id of an existing application, found with the `oauth_client` table |`c978218d-ad63-4427-b12b-542b81299cfb`|\n|`role-id`| id of an existing role, found with the `role` table |`d28baa00-839e-4b45-a6b2-1cec563942ee`|\n|`permission-id`| id of an existing permission, found with the `permission` table |`6b6cd19c-9398-4834-9ba1-1616c57139c0`|\n|`organization-id`| id of an existing organization, found with the `organization` table |`e424ed98-c966-46e3-b161-a165fd31bc01`|\n|`organization-role-id`| type of role a user has within an organization either `owner` or `member`|`member`|\n|`iot-agent-id`| id of an existing IoT Agent, found with the `iot` table |`iot_sensor_f3d0245b-3330-4e64-a513-81bf4b0dae64`|\n|`pep-proxy-id`| id of an existing PEP Proxy, found with the `pep_proxy` table |`iot_sensor_f3d0245b-3330-4e64-a513-81bf4b0dae64`|\n\nTokens are designed to expire after a set period. If the `X-Auth-token` value you are using has expired, log-in again to obtain a new token. For this tutorial, a long lasting set of tokens has been created for each user and persisted into the database,\nso there is usually no need to refresh tokens.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ diff --git a/README.ja.md b/README.ja.md index 27aaab2..2d0bde2 100644 --- a/README.ja.md +++ b/README.ja.md @@ -30,7 +30,7 @@ API へのアクセスに使用される [cUrl](https://ec.haxx.se/) コマン - [ID 管理の標準概念](#standard-concepts-of-identity-management) - [前提条件](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [アーキテクチャ](#architecture) - [Keyrock の設定](#keyrock-configuration) - [MySQL の設定](#mysql-configuration) @@ -192,12 +192,10 @@ Docker は[ここ](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 7acbbfa..fc28355 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ commands used to access the **Keyrock** REST API - - [Standard Concepts of Identity Management](#standard-concepts-of-identity-management) - [Prerequisites](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [Architecture](#architecture) - [Keyrock Configuration](#keyrock-configuration) - [MySQL Configuration](#mysql-configuration) @@ -161,10 +161,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