Using the Security Framework

If you have followed the Install Framework guide you should be able to manage the KeyRock service locally using the web-interface http://localhost:3000. The security framework can be managed using the web interface, but the following guide will walk you through using the API's to set up tokens, application id's etc.

The default username and password is [email protected] and 1234. This should NOT be used in production environments or on systems exposed to the internet.

This tutorial and the examples shown are using the API's of the KeyRock IDM. There is also the option of configuring the security component using the graphical user interface, but that is not covered in this guide. The examples below show how to integrate with the SynchorniCity platform from code. The full documentation can be found here: https://keyrock.docs.apiary.io

Getting your first authentication token

To test the service and get a token from the default admin user please issue the command below.

curl -i -X 'POST' -H 'Content-Type: application/json' -d '{"name": "[email protected]", "password": "1234"}' 'localhost:3000/v1/auth/tokens'

This will output two things to the terminal, the header of the response containing the authentication token called X-Subject-Token:

HTTP/1.1 201 Created
Cache-Control: no-cache, private, no-store, must-revalidate, max-stale=0, post-check=0, pre-check=0
X-Subject-Token: 853db849-8971-4e17-8177-7bea5a5ec325
Content-Type: application/json; charset=utf-8
Content-Length: 138
ETag: W/"8a-XVTTRiqhSPZ1EM5wvtMg6kLR2Nw"
Set-Cookie: session=eyJyZWRpciI6Ii8ifQ==; path=/; expires=Tue, 27 Aug 2019 16:43:46 GMT; httponly
Set-Cookie: session.sig=7Yig_XPmOCDlLaBJE9oxfRT2zBM; path=/; expires=Tue, 27 Aug 2019 16:43:46 GMT; httponly
Date: Tue, 27 Aug 2019 15:43:46 GMT
Connection: keep-alive

The payload will contain a JSON with some metadata about the token, for example expiry time etc.

{
  "token": {
    "methods": [
      "password"
    ],
    "expires_at": "2019-08-27T16:43:46.986Z"
  },
  "idm_authorization_config": {
    "level": "basic",
    "authzforce": false
  }
}

Configuring the security token

In the lines below, we will put the security token into a terminal variable called AUTHTOKEN. This token will be read throughout the tutorial, and must be defined again if you close the terminal or restart your computer. Take the <X-Subject-Token> from the example above, and replace it in the command below.

export AUTHTOKEN=853db849-8971-4e17-8177-7bea5a5ec325

You can test that the authentication token has been properly set by issuing the command below:

echo $AUTHTOKEN

Setting up an application id

Now that you are ready, you can create an application id with the KeyRock security framework. Issue the command below to create the PEP Proxy, while noting that the X-Auth-token is using the variable set in the example above. If this variable was not set, you need to insert the token into the example below. For more details on how to manage security identities please refer to the documentation of KeyRock: https://fiware-idm.readthedocs.io/en/latest/

curl -X 'POST' -H "X-Auth-token: $(echo $AUTHTOKEN)" -H 'Content-Type: application/json' -d '{
  "application": {
    "name": "PEP Proxy",
    "description": "Proxy",
    "redirect_uri": "localhost/login",
    "url": "localhost",
    "grant_type": [
      "client_credentials",
      "password",
      "implicit",
      "authorization_code",
      "refresh_token"
    ]
  }
}' 'localhost:3000/v1/applications'

The response will be a JSON containing among other things the application id and application secret.

{
  "application": {
    "id": "d26c98d3-2fe0-4fcb-8daa-67dac972ff60",
    "secret": "140c9839-2fe2-4a59-a4c2-768da15f92cc",
    "image": "default",
    "token_types": "bearer",
    "jwt_secret": null,
    "name": "PEP Proxy",
    "description": "Proxy",
    "redirect_uri": "localhost/login",
    "url": "localhost",
    "grant_type": "client_credentials,password,authorization_code,implicit,refresh_token",
    "response_type": "code,token"
  }
}

To make the examples below easier to follow, the application id and application secret will be stored in terminal variables in the same way as the authentication token was stored previously. Please replace the values below with the ones generated by yourself.

export APPID=d26c98d3-2fe0-4fcb-8daa-67dac972ff60
export APPSECRET=140c9839-2fe2-4a59-a4c2-768da15f92cc

Register the PEP Proxy

The following command will register the PEP Proxy with the KeyRok IDM and generate authentication tokens.

curl -X 'POST' -H "X-Auth-token: $(echo $AUTHTOKEN)" -H 'Content-Type: application/json' "localhost:3000/v1/applications/$(echo $APPID)/pep_proxies"

The output payload should look like this

{
  "pep_proxy": {
    "id": "pep_proxy_a26b3689-5757-4f76-bc93-549fdd10940f",
    "password": "pep_proxy_82dd55b1-b75e-4665-b880-9e106556d6f3"
  }
}

To make it easier to follow the upcoming examples, please store the generated tokens as terminal variables. Replace the values below with your own tokens.

export PEPID=pep_proxy_a26b3689-5757-4f76-bc93-549fdd10940f
export PEPPASS=pep_proxy_82dd55b1-b75e-4665-b880-9e106556d6f3

The following command defines a role with the |GET|*|| properties. For a full documentation of roles and what parameters can be set, please refer to the documentation here: https://fiware-idm.readthedocs.io/en/latest/

curl -H "X-Auth-Token: $(echo $AUTHTOKEN)" -H 'Content-Type: application/json' -d '{"role":{"name": "|GET|*||"}}' "localhost:3000/v1/applications/$(echo $APPID)/roles"

The output will be a JSON containing an id and the properties.

{
  "role": {
    "id": "147c9126-6ee9-435b-84dd-291a85979e3e",
    "is_internal": false,
    "name": "|GET|*||",
    "oauth_client_id": "d26c98d3-2fe0-4fcb-8daa-67dac972ff60"
  }
}

Please store the generated role id as a terminal variable. Replace the values below with your own tokens.

export ROLEID=147c9126-6ee9-435b-84dd-291a85979e3e

Now you can query the security platform

curl -X 'POST' -H "X-Auth-token: $(echo $AUTHTOKEN)" -H 'Content-Type: application/json' "localhost:3000/v1/applications/$(echo $APPID)/users/admin/roles/$(echo $ROLEID)"

Which shows the relationship between roles and users

{
  "role_user_assignments": {
    "role_id": "147c9126-6ee9-435b-84dd-291a85979e3e",
    "user_id": "admin",
    "oauth_client_id": "d26c98d3-2fe0-4fcb-8daa-67dac972ff60"
  }
}

Configure the Proxy components

Now that the security tokens have been generated, it is time to insert them into the configuration files of the two PEP Proxy components that handle security before passing the requests on to the context broker and historical API's.

Use the command below to output the tokens that were generated in the steps above.

echo $APPID && echo $PEPID && echo $PEPPASS

The output will resemble this:

d26c98d3-2fe0-4fcb-8daa-67dac972ff60
pep_proxy_a26b3689-5757-4f76-bc93-549fdd10940f
pep_proxy_82dd55b1-b75e-4665-b880-9e106556d6f3

Using your editor of choice, update the config-pep-cb.js and config-pep-his.js files located in the security folder, locate the credentials area of the file and replace the tokens and id's. Notice this change must be applied to both files.

//== Credentials (For REGISTERED APP - Orion/Historical -) provided by KeyRock ======================
config.pep = {
    app_id: 'd26c98d3-2fe0-4fcb-8daa-67dac972ff60',
    username: 'pep_proxy_a26b3689-5757-4f76-bc93-549fdd10940f',
    password: 'pep_proxy_82dd55b1-b75e-4665-b880-9e106556d6f3',
    trusted_apps : []
}

Now you can start the PEP Proxy for the Context Broker and for the Historical API at the same time with the command below.

docker-compose -f security/compose-sec-pep.yml up -d

Once the components have started, you can request a bearer token by using the AppID and AppSecret that was generated previously.

Note that on some systems the standard base64 utility does not have the -w flag, so this must be installed separately. On MacOS you can install the GNU base64 tool by using the brew install coreutils command and then replacing base64 in the example below with gbase64. Alternatively it is also possible on MacOS to omit the -w 0 parameter.

curl -X POST -H "Authorization: Basic $(echo -n $APPID:$APPSECRET | base64 -w 0)" -H 'Content-Type: application/x-www-form-urlencoded' -d '[email protected]&password=1234' 'localhost:3000/oauth2/token'

The cURL command above will generate a token that can then be exported and used in the resulting requests.

{
  "access_token": "09016d6e2c89350fb2d0b887b4786bc9bdc2b4b1",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "f0a86d87c9822548ce35d0f71e90cb556e276dee",
  "scope": [
    "bearer"
  ]
}

Take the access_token and set the environment variable of your terminal for easy reuse of the token in subsequent calls.

export ACCESSTOKEN=d04e2274dd3c85c9e53056ca8c2b0b0dfc4bdeea

Using this new token, calling the PEP proxy will validate the bearer token before proxying the request to the context broker. This first example will create a brand new entity, and the HTTP POST request will be validated by the PEP Proxy.

curl -H "X-Auth-token: $(echo $ACCESSTOKEN)" -X 'POST' -H 'Content-Type:application/json' -d $'{
    "id": "vehicle:WasteManagement:black-box",
    "type": "Vehicle",
    "category": {
      "value": [
        "municipalServices"
      ]
    },
    "location": {
      "type": "geo:json",
      "value": {
        "type": "Point",
        "coordinates": [
          56.18786,
          10.16818
        ]
      },
      "metadata": {
        "timestamp": {
          "type": "DateTime",
          "value": "2019-01-21T06:36:34.766099026Z"
        }
      }
    },
    "name": {
      "value": "vehicle:WasteManagement:black-box"
    },
    "refVehicleModel": {
      "type": "Relationship",
      "value": "vehiclemodel:econic"
    },
    "serviceProvided": {
      "value": [
        "garbageCollection",
        "wasteContainerCleaning"
      ]
    },
    "vehicleType": {
      "value": "lorry"
    }
  }' 'localhost:7000/v2/entities?options=keyValues'

In the same way, it is possible to query the PEP Proxy for entities using the access token.

curl -H "X-Auth-token: $(echo $ACCESSTOKEN)" -H 'Accept: application/json' 'localhost:7000/v2/entities/vehicle:WasteManagement:black-box?options=keyValues'

Since creating a subscription is just a HTTP POST request, this can also be routed via the PEP Proxy as the example below demonstrates.

curl -X 'POST' -H "X-Auth-token: $(echo $ACCESSTOKEN)" -H 'Content-Type: application/json' -d $'{
  "description": "My very first SynchroniCity subscription",
  "subject": {
    "entities": [
      {
        "type": "Vehicle",
        "idPattern": ".*"
      }
    ],
    "condition": {
      "attrs": [
        "location"
      ]
    }
  },
  "notification": {
    "http": {
      "url": "https://enuksrk07rmk.x.pipedream.net"
    },
    "attrs": [
      "locatin"
    ]
  },
  "expires": "2020-04-05T14:00:00.00Z",
  "throttling": 5
}' 'localhost:7000/v2/subscriptions'