{"info":{"_postman_id":"83b05e2a-e6d6-4869-a632-afcbb2072759","name":"FIWARE Identity Management","description":"

This tutorial is an introduction to FIWARE Keyrock - a generic enabler which introduces\nIdentity Management into FIWARE services. The tutorial explains how to create users and organizations in preparation to assign\nroles and permissions to them in a later tutorial.

The docker-compose files for this tutorial can be found on GitHub:

$\"GitHub\"$ FIWARE 401: Identity Management

Identity Management

\n
\"If one meets a powerful person — ask them five questions: ‘What power have you got?\nWhere did you get it from? In whose interests do you exercise it? To whom are you\naccountable? And how can we get rid of you?’\"
\n
— Anthony Wedgwood Benn (The Five Essential Questions of Democracy)
\n

In computer security terminology, Identity management is the security and business discipline that \"enables the right\nindividuals to access the right resources at the right times and for the right reasons\". It addresses the need to\nensure appropriate access to resources across disparate systems.

The FIWARE framework consists of a series of separate components, and the security chapter aims to implement\nthe common needs of these components regarding who (or what) gets to access which resources within the system,\nbut before access to resources can be locked down, the identity of the person (or service) making the request\nneeds to be known. The FIWARE Keyrock Generic Enabler sets up all of the common characteristics of an\nIdentity Management System out-of-the-box, so that other components are able to use standard authentication\nmechanisms to accept or reject requests based on industry standard protocols.

Identity Management therefore covers the issues of how to gain an identity within the system, the protection\nof that identity and the surrounding technologies such as passwords and network protocols.

Standard Concepts of Identity Management

The following common objects are found with the Keyrock Identity Management database:

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
Application - Any securable FIWARE application consisting of a series of microservices
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
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
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
Permission - An ability to do something on a resource within the system

Additionally two further non-human application objects can be secured within a FIWARE application:

IoTAgent - a proxy between IoT Sensors and the Context Broker
PEPProxy - a middleware for use between generic enablers challenging the rights of a user.

The relationship between the objects can be seen below - the entities marked in red are used directly within this tutorial:

$\"\"$

Video : Introduction to Keyrock

$\"\"$

Click on the image above to watch an introductory video describing the Keyrock Generic Enabler

Prerequisites

Docker

To keep things simple both components will be run using Docker. Docker is a\ncontainer technology which allows to different components isolated into their respective environments.

To install Docker on Windows follow the instructions here
To install Docker on Mac follow the instructions here
To install Docker on Linux follow the instructions here

Docker Compose is a tool for defining and running multi-container Docker applications. A\nYAML file 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

Cygwin

We will start up our services using a simple bash script. Windows users should download cygwin to provide a\ncommand line functionality similar to a Linux distribution on Windows.

Architecture

This introduction will only make use of one FIWARE component - the Keyrock\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.

The overall architecture will consist of the following elements:

One FIWARE Generic Enabler:
\n
- FIWARE Keyrock offer a complement Identity Management System including:
  - An OAuth2 authentication system for Applications and Users
  - A website graphical front-end for Identity Management Administration
  - An equivalent REST API for Identity Management via HTTP requests
  \n
\n
One MySQL database :
\n
- Used to persist user identities, applications, roles and permissions
\n

Since all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports.

$\"\"$

The specific architecture of each section of the tutorial is discussed below.

Keyrock Configuration

  keyrock:\n    image: 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      - 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=3443\n      - IDM_ADMIN_USER=admin\n      - IDM_ADMIN_EMAIL=admin@test.com\n      - IDM_ADMIN_PASS=1234\n    secrets:\n      - my_secret_data\n

The idm container is a web application server listening on two ports:

Port 3005 has been exposed for HTTP traffic so we can display the web page and interact with the REST API.
Port 3443 has been exposed for secure HTTPS traffic for the website and REST API

\n
Note HTTPS should be used throughout for any secured application, but to do this properly,\nKeyrock requires a trusted SSL certificate - the default certificate is self-certified and\navailable for testing purposes. The certificates can be overridden by attaching a volume to\nreplace the files under /opt/fiware-idm/certs.
\n
In a production environment, all access should occur over HTTPS, to avoid sending\nany sensitive information using plain-text. Alternatively HTTP can be used within a\nprivate network behind a configured HTTPS Reverse Proxy
\n
The port 3005 offering the HTTP protocol is being exposed for demonstration purposes only and to\nsimplify the interactions within this tutorial - you may also use HTTPS on port 3443 with certain\ncaveats.
\n
If you want to use HTTPS to access the REST API when you are using Postman, ensure that SSL\ncertificate verfication is OFF. If you want to use HTTPS to access the web front-end, please\naccept any security warnings issued.
\n

The idm container is driven by environment variables as shown:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Value	Description
IDM_DB_PASS	`idm`	Password of the attached MySQL Database - secured by Docker Secrets (see below)
IDM_DB_USER	`root`	User name of the default MySQL user - left in plain-text
IDM_HOST	`http://localhost:3005`	Host name of the Keyrock App Server - used in activation eMails when signing up users
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
IDM_HTTPS_ENABLED	`true`	Whether to offer HTTPS Support - this will use the self-signed certs unless overridden
IDM_HTTPS_PORT	`3443`	Port used by the Keyrock App Server for HTTP traffic this has been altered from the default 443

\n
:information_source: Note that this example has secured the MySQL password using Docker Secrets\nBy using IDM_DB_PASS with the _FILE suffix and referring to a secrets file location.\nThis avoids exposing the password as an ENV variable in plain-text - either in the Dockerfile Image or\nas an injected variable which could be read using docker inspect.
\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

MySQL Configuration

  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

The mysql-db container is listening on a single port:

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

The mysql-db container is driven by environment variables as shown:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Value.	Description
MYSQL_ROOT_PASSWORD	`123`.	specifies a password that is set for the MySQL `root` account - secured by Docker Secrets (see below)
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

Start Up

To start the installation, do the following:

git clone git@github.com:Fiware/tutorials.Identity-Management.git\ncd tutorials.Identity-Management\n\n./services create\n

\n
Note The initial creation of Docker images can take up to three minutes
\n

Thereafter, all services can be initialized from the command line by running the services Bash script provided within the repository:

./services <command>\n

Where <command> will vary depending upon the exercise we wish to activate.

\n
:information_source: Note: If you want to clean up and start over again you can do so with the following command:
\n
./services stop\n
\n

Reading directly from the Keyrock MySQL Database

All Identify Management records and relationships are held within the the attached MySQL database. This can be\naccessed by entering the running Docker container as shown:

docker exec -it db-mysql bash\n

mysql -u <user> -p<password> idm\n

Where <user> and <password> 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.

SQL commands can then be entered from the command line. e.g.:

select id, username, email, password from user;\n

UUIDs within Keyrock

All 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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Description	Sample Value
`keyrock`	URL for the location of the Keyrock service	`localhost:3005`
`X-Auth-token`	Token received in the Header when logging in as a user - in other words \"Who am I?\"	`51f2e380-c959-4dee-a0af-380f730137c3`
`X-Subject-token`	Token added to requests to define \"Who do I want to inquire about?\" - This can also be a repeat the `X-Auth-token` defined above	`51f2e380-c959-4dee-a0af-380f730137c3`
`user-id`	id of an existing user, found with the `user` table	`96154659-cb3b-4d2d-afef-18d6aec0518e`
`organization-id`	id of an existing organization, found with the `organization` table	`e424ed98-c966-46e3-b161-a165fd31bc01`
`organization-role-id`	type of role a user has within an organization either `owner` or `member`	`member`

Tokens 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.

Video : Creating User Accounts with the Keyrock GUI

$\"\"$

Click on the image above to watch a video demonstrating how to create users with the Keyrock GUI

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Identity Management","slug":"identity-management"},{"content":"Prerequisites","slug":"prerequisites"},{"content":"Architecture","slug":"architecture"},{"content":"Start Up","slug":"start-up"}],"owner":"513743","collectionId":"83b05e2a-e6d6-4869-a632-afcbb2072759","publishedId":"RWMLLRui","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF7059"},"publishDate":"2020-01-02T11:03:10.000Z"},"item":[{"name":"Logging In - Authentication","item":[{"name":"Create token with Password","id":"4e3e28a2-de58-4ca0-b50a-777ba7ecbf16","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"name\": \"admin@test.com\",\n \"password\": \"1234\"\n}"},"url":"http://localhost:3005/v1/auth/tokens","description":"

The following example logs in using the Admin Super-User - it is the equivalent of using the log-in screen of the GUI.\nThe URL https://localhost:3443/v1/auth/tokens should also work in a secure system.

The response header returns an X-Subject-token which identifies who has logged on the application.\nThis token is required in all subsequent requests to gain access.

\n","urlObject":{"protocol":"http","path":["v1","auth","tokens"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"4e3e28a2-de58-4ca0-b50a-777ba7ecbf16"},{"name":"Get User Information via a Token","id":"4220597a-8fb8-4752-806a-f9ae06834161","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"},{"key":"X-Subject-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/auth/tokens","description":"

In order to manage the Identity Manager through the API you must obtain an access token to be included in HTTP headers. There are two methods to obtain an access token.

\n","urlObject":{"protocol":"http","path":["v1","auth","tokens"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"4220597a-8fb8-4752-806a-f9ae06834161"},{"name":"Refresh token with Token","id":"8821c498-2b44-4feb-b9d8-b639ebb06bc2","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"token\": \"70bb37f8-938e-4158-a8ab-7218af3c384d\"\n}"},"url":"http://localhost:3005/v1/auth/tokens","description":"

Tokens are time limited - it is no longer possible to gain access once a token has expired.\nHowever it is possible to refresh a token for a newer one prior to expiry.

Most applications use this end-point to avoid timing out a user whilst they are interacting with the application.

A new token is returned in the X-Subject-Token header of the response.

\n","urlObject":{"protocol":"http","path":["v1","auth","tokens"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"8821c498-2b44-4feb-b9d8-b639ebb06bc2"}],"id":"b71456c0-d517-4158-bbcd-f58baa22c16f","description":"

The Log-in Screen allows an existing user to identify themselves and obtain a token for further operations. It is the initial start-up\nscreen of the Keyrock GUI - http://localhost:3005/idm (or https://localhost:3443/idm and accept the warnings)

Enter a user name and password to enter the application. The default super-user has the values admin@test.com and 1234.

\n","event":[{"listen":"prerequest","script":{"id":"04f600b8-5b31-4ed2-ada6-7db583d6b15b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"1b5166e8-d073-4cef-9649-def95e2eeaef","type":"text/javascript","exec":[""]}}],"_postman_id":"b71456c0-d517-4158-bbcd-f58baa22c16f"},{"name":"Managing User Accounts","item":[{"name":"Create a User","id":"5fb8c7da-9be1-4ca4-8f98-d2537f49df87","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"raw","raw":"{\n \"user\": {\n \"username\": \"admin2\",\n \"email\": \"admin2@test.com\",\n \"password\": \"test\",\n \"admin\": true\n }\n}"},"url":"http://localhost:3005/v1/users","description":"

REST API

To create a new user via the REST API, send a POST request to the /v1/users endpoint containing\nthe username,email and password along with the X-Auth-token header from a previously logged in administrative user.

GUI

Alternatively, Users are able to sign-up for themselves using the GUI. The only requirement is an email address and a password.

Once an account is created, the user is sent an eMail to confirm their existence and activate their account.

The REST API is also able to create and amend users without their own interaction - this could be useful for\nbulk CRUD actions for example.

\n
Note - an eMail server must be configured to send out invites properly, otherwise the invitation\nmay be deleted as spam. For testing purposes, it is easier to update the users table directly:\nupdate user set enabled = 1;
\n

\n","urlObject":{"protocol":"http","path":["v1","users"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"5fb8c7da-9be1-4ca4-8f98-d2537f49df87"},{"name":"Read info about a User","id":"9bb115e1-4aba-44ba-a0de-bf147eb32fa3","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/users/aaaaaaaa-good-0000-0000-000000000000","description":"

Making a GET request to a resource under the /v1/users/aaaaaaaa-good-0000-0000-000000000000 endpoint will return the user listed under that id.\nThe X-Auth-token must be supplied in the headers.

The response contains basic details of the account in question.

\n","urlObject":{"protocol":"http","path":["v1","users","aaaaaaaa-good-0000-0000-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"9bb115e1-4aba-44ba-a0de-bf147eb32fa3"},{"name":"List Users","id":"bf4cf4d5-f9ac-462b-8008-dbe25fbd1ada","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/users","description":"

Obtaining a complete list of all users is a super-admin permission requiring the X-Auth-token - most users will \nonly be permitted to return users within their own organization. Listing users can be done by making a GET request to \nthe /v1/users endpoint

\n","urlObject":{"protocol":"http","path":["v1","users"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"bf4cf4d5-f9ac-462b-8008-dbe25fbd1ada"},{"name":"Update a User","id":"a81ae6a1-fb6e-465c-b2fa-101ce0b02ce8","request":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"raw","raw":"{\n\t\"user\": {\n\t \"username\": \"alice\",\n\t \"email\": \"alice@test.com\",\n\t \"enabled\": true,\n\t \"gravatar\": false,\n\t \"date_password\": \"2018-07-26T15:25:14.000Z\",\n\t \"description\": \"Alice works for FIWARE\",\n\t \"website\": \"http://www.fiware.org\"\n\t}\n}"},"url":"http://localhost:3005/v1/users/aaaaaaaa-good-0000-0000-000000000000","description":"

Within the GUI, users can be updated from the settings page. This can also be done from the command line\nby making PATCH request to /v1/users/<user-id> endpoint when the user id is known. The X-Auth-token\nheader must also be set.

The response lists the fields which have been updated.

\n","urlObject":{"protocol":"http","path":["v1","users","aaaaaaaa-good-0000-0000-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"a81ae6a1-fb6e-465c-b2fa-101ce0b02ce8"},{"name":"Delete a User","id":"ac942a43-afad-42d5-87a3-800557eda774","request":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/users/aaaaaaaa-good-0000-0000-000000000000","description":"

Within the GUI, users can delete their account from the settings page, selecting the Cancel Account Option,\nonce again a super-admin user can do this from the command line by sending a DELETE request to the \n/v1/users/aaaaaaaa-good-0000-0000-000000000000 endpoint. The X-Auth-token header must also be set.

\n","urlObject":{"protocol":"http","path":["v1","users","aaaaaaaa-good-0000-0000-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"ac942a43-afad-42d5-87a3-800557eda774"}],"id":"6ca001d1-68e7-43e2-81bf-bdf7d2ac669d","description":"

Users accounts are at the heart of any identity management system. The essential fields of every account hold a unique user name\nand email address to identify the user, along with a password for authentication. The other optional fields\nadd more information about the user such as a user website, description or avatar.

As the default super-admin user admin@test.com with a password of 1234, we will set up a series of user accounts and assign them to\nrelevant organizations within the system.

Dramatis Personae

The following people legitimately have accounts within the Application

Alice, she will be the Administrator of the Keyrock Application
Bob, the Regional Manager of the supermarket chain - he has several store managers under him:
- Manager1
- Manager2
\n
Charlie, the Head of Security of the supermarket chain - he has several store detectives under him:
- Detective1
- Detective2
\n

All the CRUD actions for Users require an X-Auth-token header from a previously logged in administrative user to be able\nto read or modify other user accounts. The standard CRUD actions are assigned to the appropriate HTTP verbs (POST, GET, PATCH and DELETE)\nunder the /v1/users endpoint.

\n","event":[{"listen":"prerequest","script":{"id":"f181be01-0817-44ba-a88d-241b9da2cf3b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"28237ecf-a94a-4783-91e6-634dc845b7f7","type":"text/javascript","exec":[""]}}],"_postman_id":"6ca001d1-68e7-43e2-81bf-bdf7d2ac669d"},{"name":"Grouping Accounts under Organizations","item":[{"name":"Organization CRUD Actions","item":[{"name":"Create an Organization","id":"a6a5e5c1-6696-44f2-8d43-dabfd09e7c9e","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"raw","raw":"{\n \"organization\": {\n \"name\": \"Security\",\n \"description\": \"This group is for the store detectives\"\n }\n}"},"url":"http://localhost:3005/v1/organizations","description":"

To create a new organization, send a POST request to the /v1/organizations endpoint containing the name and description along with the X-Auth-token header from a previously logged in user.

The Organization is created and the user who created it is automatically assigned as a user. \nThe response returns UUID to identify the new organization.

\n","urlObject":{"protocol":"http","path":["v1","organizations"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"a6a5e5c1-6696-44f2-8d43-dabfd09e7c9e"},{"name":"List Organizations","id":"2a8828a2-661d-4a30-a99e-da51e0712d0d","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations","urlObject":{"protocol":"http","path":["v1","organizations"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"2a8828a2-661d-4a30-a99e-da51e0712d0d"},{"name":"Read info about an Organization","id":"21952466-75bf-4ee7-96aa-9b10ef948cdd","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000","description":"

Making a GET request to a resource under the /v1/organizations/security-team-0000-0000-000000000000 endpoint will return the organization\nlisted under that id. The X-Auth-token must be supplied in the headers as only permitted organizations will be shown.

The response returns the details of the organization.

\n","urlObject":{"protocol":"http","path":["v1","organizations","security-team-0000-0000-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"21952466-75bf-4ee7-96aa-9b10ef948cdd"},{"name":"Update an Organization","id":"d17a820e-b201-46fc-9671-8bcfc3525cc0","request":{"method":"PATCH","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"raw","raw":"{\n \"organization\": {\n \"name\": \"FIWARE Security\",\n \"description\": \"The FIWARE Foundation is the legal independent body promoting, augmenting open-source FIWARE technologies\",\n \"website\": \"http://fiware.org\"\n }\n}"},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000","description":"

To amend the details of an existing organization, a PATCH request is send to the /v1/organizations/security-team-0000-0000-000000000000 endpoint.

The response contains a list of the fields which have been amended.

\n","urlObject":{"protocol":"http","path":["v1","organizations","security-team-0000-0000-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"d17a820e-b201-46fc-9671-8bcfc3525cc0"},{"name":"Delete an Organization","id":"28085766-e59b-4fca-82ee-db41c0064b8f","request":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000","urlObject":{"protocol":"http","path":["v1","organizations","security-team-0000-0000-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"28085766-e59b-4fca-82ee-db41c0064b8f"}],"id":"1b7ce43a-8401-4817-9872-ec7beab18fdd","description":"

GUI

Once signed-in, users are able to create and update organizations for themselves.

REST API

Alterntively, the standard CRUD actions are assigned to the appropriate HTTP verbs (POST, GET, PATCH and DELETE) under the /v1/organizations endpoint.

\n","event":[{"listen":"prerequest","script":{"id":"4eb46ba3-0ae3-4b98-bef0-3b0a19da56aa","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"6173bfcf-4814-4c1e-9b4b-5d77d1de5a6a","type":"text/javascript","exec":[""]}}],"_postman_id":"1b7ce43a-8401-4817-9872-ec7beab18fdd"},{"name":"Users within an Organization","item":[{"name":"Add a User as a Member of an Organization","id":"265864a1-55f5-4643-8c47-cbe3e7831e10","request":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000/users/aaaaaaaa-good-0000-0000-000000000000/organization_roles/member","description":"

To add a user as a member of an organization, an owner must make a PUT request as shown, including the <organization-id> and <user-id> in the URL path and identifying themselves using an X-Auth-Token in the header.

The response lists the user's current role within the organization (i.e. member)

\n","urlObject":{"protocol":"http","path":["v1","organizations","security-team-0000-0000-000000000000","users","aaaaaaaa-good-0000-0000-000000000000","organization_roles","member"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"265864a1-55f5-4643-8c47-cbe3e7831e10"},{"name":"Add a User as an Owner of an Organization","id":"8f7582c1-8218-4f78-b66c-22eb383e9c88","request":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000/users/aaaaaaaa-good-0000-0000-000000000000/organization_roles/owner","description":"

An owner can also create new owners by making a PUT request as shown, including the <organization-id> and <user-id> in the URL path and identifying themselves using an X-Auth-Token in the header.

The response lists the user's current role within the organization (i.e. owner)

\n","urlObject":{"protocol":"http","path":["v1","organizations","security-team-0000-0000-000000000000","users","aaaaaaaa-good-0000-0000-000000000000","organization_roles","owner"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"8f7582c1-8218-4f78-b66c-22eb383e9c88"},{"name":"List Users within an organization","id":"a87a10d1-3bb7-4114-ae6f-360a6628a16b","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000/users","description":"

Listing users within an organization is an owner or super-admin permission requiring the X-Auth-token\nListing users can be done by making a GET request to the /v1/organizations/security-team-0000-0000-000000000000/users endpoint.

The response contains the users list.

\n","urlObject":{"protocol":"http","path":["v1","organizations","security-team-0000-0000-000000000000","users"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"a87a10d1-3bb7-4114-ae6f-360a6628a16b"},{"name":"Info of user organization relationship","id":"35feb08a-b199-4e37-9746-9af429d572db","request":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000/users/aaaaaaaa-good-0000-0000-000000000000/organization_roles","description":"

To find the role of a user within an organization, send a GET request to the /v1/organizations/security-team-0000-0000-000000000000/users/aaaaaaaa-good-0000-0000-000000000000/organization_roles endpoint.

The response returns the role of the given <user-id>

\n","urlObject":{"protocol":"http","path":["v1","organizations","security-team-0000-0000-000000000000","users","aaaaaaaa-good-0000-0000-000000000000","organization_roles"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"35feb08a-b199-4e37-9746-9af429d572db"},{"name":"Remove User from an Organization","id":"4927f03b-0ba4-4066-9f0e-3c2360d6b908","request":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3005/v1/organizations/security-team-0000-0000-000000000000/users/aaaaaaaa-good-0000-0000-000000000000/organization_roles/member","description":"

Owners and Super-Admins can remove a user from and organization by making a delete request.

Users within an Organization are assigned to one of types - owner or member.
The members of an organization inherit all of the roles and permissions assigned \nto the organization itself. In addition, owners of an organization are able to \nadd an remove other members and owners.

\n","event":[{"listen":"prerequest","script":{"id":"c64b6abe-444d-438b-99af-ed0fc27c528a","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"a074d0bf-43f5-41f9-8617-43156bd2a774","type":"text/javascript","exec":[""]}}],"_postman_id":"d22bcb81-c089-4128-ac52-bd929d978c56"}],"id":"288b2b0a-6648-446c-9a23-20c4ede655dd","description":"

For any identity management system of a reasonable size, it is useful to be able to assign\nroles to groups of users, rather than setting them up individually. Since user administration\nis a time consuming business, it is also necessary to be able to delegate the responsibility\nof managing these group of users down to other accounts with a lower level of access.

Consider our supermarket chain for example, there could be a group of users (Managers) who\ncan change the prices of products within the store, and another group of users (Store Detectives)\nwho can lock and unlock door after closing time. Rather than give access to each individual account,\nit would be easier to assign the rights to an organization and then add users to the groups.

Furthermore, Alice, the Keyrock administrator does not need to explicitly add additional user\naccounts to each organization herself - she could delegate that right to an owner within each organization.\nFor example Bob the Regional Manager would be made the owner of the management organization and could\nadd and remove addition manager accounts (such as manager1 and manager2) to that organization\nwhereas Charlie the Head of Security could be handed an ownership role in the security organization and add\nadditional store detectives to that organization.

Note that Bob does not have the rights to alter the membership list of the security organization and\nCharlie does not have the rights to alter the membership list of the management organization.\nFurthermore neither Bob nor Charlie would be able to alter the permissions of the application themselves,\nmerely add and remove existing user accounts to the organization they control.

Creating an application and setting-up the permissions is not covered here as it is the subject of the next tutorial.

\n","event":[{"listen":"prerequest","script":{"id":"c7f250c1-d118-4228-a631-3100cf4b0749","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"e44c9292-bf65-406b-aef4-0e01c969b714","type":"text/javascript","exec":[""]}}],"_postman_id":"288b2b0a-6648-446c-9a23-20c4ede655dd"}],"event":[{"listen":"prerequest","script":{"id":"d269e0a7-2b8d-4976-ad7f-95be8e136bec","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"fd30f550-eb89-4ac1-8dc5-cdf1ef26ef52","type":"text/javascript","exec":[""]}}],"variable":[{"key":"keyrock","value":"localhost:3005"},{"key":"X-Subject-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"},{"key":"organization-id","value":"security-team-0000-0000-000000000000"},{"key":"user-id","value":"aaaaaaaa-good-0000-0000-000000000000"},{"key":"X-Auth-token","value":"bdeb0cb0-126e-46c7-a8fc-a2a5bc290503"}]}