This is a simple "Getting started with i4Trust" installation guide, targeting developers with limited Kubernetes experience and therefore not already having a working cluster available on the cloud. We use the Red Hat OpenShift Developer Sandbox to create a fully working OpenShift environment to build on, without any cost. The cluster itself has some restrictions and should not be used for production purposes, but is very convenient to use as a starting point. Follow the steps described below, and all necessary components will be available and up-and-running properly for development and testing.
⚠️ This is a simplified "Getting started" set-up designed for tutorial use only, and should NEVER be used as a production environment. It is not properly secured as it contains plain-text passwords, and also contains other obvious anti-patterns, for example it has no resource limiting, no availability settings ans no backups. Copying the tutorial set-up directly for commercial use will harm you in production. This is a just development setup, and should be treated as such.
i4Trust is a common framework used for creating collaborative dataspaces based on FIWARE and iSHARE. Data is passed between context brokers using the NGSI-LD data format, and protected using distributed trust mechanisms, meaning that a permission chain of "who gives access to what" is set up between the various participants within the dataspace. Individual clients of the particpants do not need to be preregistered, but can be vouched for by an existing participant who has already registered a digital certificate created by a Certificate Authority.
What this means in practice is that, to allow its users to take part in a dataspace, a participant will need to create a publicly available cloud based environment consisting of their own context broker protected by a PEP-Proxy which delegates appropriate security actions up to an iSHARE satellite. To create this we will need to use common cloud orchestration tools such as Kubernetes and Helm Charts.
This tutorial assumes some background in cloud operations, as you can find plenty of existing tutorials elsewhere on the Internet. Please ensure that you have downloaded the oc , helm and kubectrl command line clients and familiarised yourself with their use before starting the tutorial. Basic knowledge of cryptography such as how to create or manipulate digital certificates using openssl and base 64 encoding is also required.
The following explainer videos go into to more detail about the components and their usage
⚠️ The consumer "EU.EORI.NLHAPPYPETS" and the provider "EU.EORI.NLPACKETDEL" are placeholder and should be replaced with your valid participants certificates. Beside that, the ID of the provider("EU.EORI.NLPACKETDEL") also needs to be changed according to the used certificates in kong-configuration and keyrock-configuration.
The step-by-step guide will examplify an M2M-scenario, where consumer "EU.EORI.NLHAPPYPETS" requests the IDM(e.g. Keyrock) of provider "EU.EORI.NLPACKETDEL" for an access-token. This token is then used by "EU.EORI.NLHAPPYPETS" to request the orion-ld on "EU.EORI.NLPACKETDEL" through kong. Kong will verify the identity provided in the token, using the iShare-testinstances for satellite(e.g. https://scheme.isharetest.net) and authorization-registry(e.g. https://ar.isharetest.net).
⚠️ If you don't have identities for the iShare-testinstances, either request them at the i4Trust-helpdesk or use a dedicated AR and Satellite(for example Keyrock and FIWARE/ishare-satellite).
- Create account and sandbox on the offical page from RedHat launch
-
Follow the guide to the openshift-console:
-
Get the token and login from your console:
--> login using your local shell
git clone [email protected]:i4Trust/tutorials.git- Move to sandbox folder:
cd tutorials/OpenShift-Sandbox-Deployment/- Install mongoDB:
⚠️ The sandbox allows installations to a dev namepsace. The namespace (hereafter referred to as<NAMESPACE>will have the name<YOUR_RED_HAT_ACCOUNT>-dev
helm dependency build ./mongodb/
helm install mongodb ./mongodb/ -n <NAMESPACE>Verify:
kubectl get pods -n <NAMESPACE>
NAME READY STATUS RESTARTS AGE
mongodb-7d4b49b5f9-q54tm 1/1 Running 0 61s- Install mysql:
helm dependency build ./mysql/
helm install mysql ./mysql/ -n <NAMESPACE>Verify:
kubectl get pods -n <NAMESPACE>
NAME READY STATUS RESTARTS AGE
mongodb-7d4b49b5f9-gr2cj 1/1 Running 0 83s
mysql-664b9568bf-sh9k2 1/1 Running 0 39s- Install keyrock:
⚠️ replace cert and key in the secrets.yaml with your data. They need to be base64 encoded. The certificate and key need to correspond with the ID configured at ./keyrock/values.yaml#l102More information on how to obtain a test i4Trust digital certificate and how to encode it can be found here
helm dependency build ./keyrock/
helm install keyrock ./keyrock/ -n <NAMESPACE>Verify:
kubectl get pods -n <NAMESPACE>
NAME READY STATUS RESTARTS AGE
keyrock-0 1/1 Running 0 75s
mongodb-7d4b49b5f9-gr2cj 1/1 Running 0 12m
mysql-664b9568bf-sh9k2 1/1 Running 0 11mGet the address:
kubectl get route keyrock -n <NAMESPACE>
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
keyrock keyrock-stefan-fiware-dev.apps.sandbox.x8i5.p1.openshiftapps.com keyrock 8080 NoneOpen in browser http:// and login with User: [email protected] Password: admin
- Install Orion-LD:
helm dependency build ./orion-ld/
helm install orion-ld ./orion-ld/ -n <NAMESPACE>Verify:
kubectl get pods -n <NAMESPACE>
NAME READY STATUS RESTARTS AGE
keyrock-0 1/1 Running 0 3h3m
mongodb-64949fb874-8fsh2 1/1 Running 0 3m41s
mysql-664b9568bf-sh9k2 1/1 Running 0 3h14m
orion-ld-58ddb4bcfb-rpx4x 1/1 Running 0 32s- Install Kong:
Insert certificate and key into the secret-file. Make sure to base64-encode it. The ID at config-map#l37 has to match the certificate and key. Update the configuration for the backend service(usually the context broker) to be secured in the config-map.
⚠️ Do not forget the--skip-crds. The sandbox does not allow cluster-wide CRDs and we dont need them in our use-case.
helm dependency build ./kong/
helm install kong ./kong/ -n <NAMESPACE> --skip-crdsVerify:
kubectl get pods -n <NAMESPACE>
NAME READY STATUS RESTARTS AGE
keyrock-0 1/1 Running 0 159m
kong-kong-64fb477547-42d2p 1/1 Running 0 35s
mongodb-7d4b49b5f9-96npm 1/1 Running 0 145m
mysql-664b9568bf-sh9k2 1/1 Running 0 170mThe system now can be reached at:
kubectl get routes kong-route -n <NAMESPACE> -o json | jq -r '.spec.host'Put your client key and certificate into the folder to mount(the files in example-secrets) are only generated examples) and use the correct IDs.
- Generate a JWT for your client:
docker run -v $(pwd)/doc/example-secrets:/certificates -e I_SHARE_CLIENT_ID="EU.EORI.NLHAPPYPETS" -e I_SHARE_IDP_ID="EU.EORI.NLPACKETDEL" quay.io/wi_stefan/ishare-jwt-helper:0.2.1The token will be print out on the command-line. Be aware that it is(as defined by iShare) only valid for 30s.
- Request a token:
curl --location --request POST 'https://<KEYROCK_URL/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
--data-urlencode 'scope=iSHARE' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion=<GENERATED_TOKEN>' \
--data-urlencode 'client_id=EU.EORI.NLHAPPYPETS'The response will look like:
{
"access_token": "<TOKEN>",
"expires_in": 3600,
"token_type": "Bearer"
}- Request at kong:
curl --location --request GET 'http://<KONG-ADDRESS>/orion/ngsi-ld/v1/entities/urn:ngsi-ld:TEST:ENTITY' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' This should lead to a response like:
{
"message": "Local AR policy not authorized: Policy has expired or is not yet valid"
}The concrete output depends on the policies created for your participants(e.g. I_SHARE_CLIENT_ID and I_SHARE_IDP_ID). In our example, a policy is found but currently not active.