This repository contains information about the hackathon "Gaia-X compliant Trust and IAM framework", which happens at the Tech-X Conference and Hackathon #6 in Bilbao.
i4Trust is a framework used for building collaborative dataspaces, based on FIWARE components and compatible with the iSHARE scheme. Access to data and data processing(app) services in those dataspaces is protected through a decentralized Trust and IAM framework, where individual users1 don't have to be registered as users of services seperately, but can be vouched for by existing participants, that are already trusted inside the dataspace. The trust between the participants is provided through a trust-anchor service, called "iSHARE Satellite". It implements a list of trusted participants, which can be used by the companies to ensure they are only talking to trusted partners.
This framework for example allows to offer services through a marketplace, where participants of the dataspace can offer and acquire rights to access each other's services. In our use-case, a company called Packet Delivery Co. is offering digital services around its "traditional" logistics services. Participants in the dataspace can acquire access to those services and grant such access to their customers. Packet Delivery Co. currently supports two types of offerings, the "Gold-Service" and the "Standard-Service". Organizations acquiring the "Gold-Service" are allowed to grant their users not only to access information about their Packet-Deliveries(e.g. planned time of arrival), but also the ability to change those values to better fit their needs(e.g. deliver when I'm at home). On the other hand, users of organizations acquiring the "Standard-Service" can only see the times, but not change them.
In our use-case, the company No Cheaper Inc. is running an online shop, selling various goods at small prices. They use Packet Delivery Co. to deliver those products, but don't want to grant their users additional benefits. Therefore it has only acquired the "Standard-Service", which allows the users to view the planned arrivals.
Happy Pets Inc. however, offers various products for pet owners and wants to offer to some of its customers also the option to update the planned time of arrival. As a participant of the dataspace, it will acquire access to the "Gold-Service" at the marketplace and that will mean it is now allowed to issue credentials to its customers. Customers with such credentials are now allowed to change the pta, while others are not.
Happy Pets' competitor Animal Goods Org. decides to also offer its customers the services of Packet Delivery Co.. Since they are quite new on the market, they are not yet part of the dataspace. In order to do so, they have to properly on-board themself to the dataspace and then can also acquire access. For doing so, it creates a Gaia-X compliant self-description2, containing various legal informations required for companies in the European Union. To prove the legitimacy of those informations, they get a Compliancy Credential from the Gaia-X Compliancy Service3. With those two credentials, a legal representative can use the OnBoarding-Service of the dataspace to register Animal Goods Org. as a new participant. The representative identifies itself with a credential4, too.
Once this is done, Animal Goods Org. can access the marketplace and also acquire the rights to use the "Gold-Service" for its customers.
While the i4Trust framework for Dataspaces is well established, working and already used in multiple dataspaces(see i4Trust experiments) and a solution for the OnBoarding-Service, combining the i4Trust IAM-Framework with Gaia-X compliancy, there integration is yet to be finished.
In order to properly on-board new participants to an i4Trust-Dataspace, the Satellite-Implementation needs to be evolved to get participant information from the OnBoarding-Service. Therefor, in the hackathon, we want to implement:
- an EBSI Trusted Issuers Registry compliant endpoint, based on the NGSI-LD API. This could either be an extension to the already existing Satellite-implementation or a completely new service.
- [optional] Implement additional endpoints from the satellite-api(Spec)
- [optional] Extend the LegalPerson-Credential to include iSHARE-related data, like the certificate or the EORI
Goal: In order to show the improvements to the integration, the following steps should be presented:
- issue a Self-Description for Animal Goods Org.5
- get a Compliancy Credential6
- get a NaturalPerson Credential for Animal Goods Org.
- register Animal Goods Org. at the OnBoarding-Portal
- take just the NaturalPerson credential and verify it against the new service7
All components are deployed via GitOps. The deployments can be found at: https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/gaia-x
The diagram shows the relevant components and their interaction. They are not necessarily in the provided sequence, but there are certain dependencies between some steps.
- The person("NaturalPerson") receives a LegalPerson-Credential2 and a NaturalPerson-Credential4, containing the self-descrption of the organisation and the identity of the user itself. The NaturalPerson-Credential is issued by the organisation described in the LegalPerson-Credential.
- The issuer(Keycloak) uses WaltId to get the actual credential
- WaltId maintains the DID(and corresponding private key) of the organization, therefor is also responsible to publish the did.json required for did:web - this happens through route-rewriting to WaltId's Core-API
- the participant also publishes its certificate-chain, defined in the x5u-parameter of the did.json, as mandated by the Gaia-X complinacy service(in a real environment, the certificate-chain needs to be derived from a Gaia-X trusted CA. To ease the demo-environment, we use Let's encrypt provided certificates here)
- The person uses its wallet(on the mobile phone) to also retrieve a CompliancyCredential3 for the LegalPerson-Credential from the Gaia-X ComplinacyService
- the FIWARE Demo-Wallet provides a button to request such credential for any stored credential
- the Compliancyservice will check the credential according to the Gaia-X rules and send back a credential to the wallet
- the FIWARE Demo-Wallet provides a button to request such credential for any stored credential
- In order to OnBoard the participant(e.g.
Animal Goods Org.), the user accesses the OnBoarding-Portal- the portal will forward the user to the Login-Page of the verifier, which displays a QR-Code, containing all information to fulfil the SIOP-2/OIDC4VP-Flow
- the user scans the code with its wallet and let it send all credentials as a VerfiablePresentation
- the verifier will now check all (3) credential it did receive:
- verify the signature, issuance-date and vaildity-timeframe for each of the credentials
- checks that the CompliancyCredential was issued by a CompliancyService registered in the Gaia-X Registry(see demo-registry)
- checks that the CompliancyCredential actually proofs the compliancy of the LegalPerson-Credential and that the NaturalPerson-Credential was issued by the LegalPerson, thus building a chain-of-trust between the credentials up towards the Gaia-X CompliancyService
- creates a JWT containing the VerifiablePresentation and provide it to the portal via the token-endpoint
- The portal now uses the JWT to access the backend-services
- it requests the Orion-LD ContextBroker, using the NGSI-LD Api to get or create participants
- all requests go through the Kong API-Gateway
- the requests are forwarded to the DSBA-PDP by the PEP-Plugin to get an authorization-decision
- the PDP checks the request in context of the roles inside then NaturalPerson-Credential, using the iSHARE-compliant Authorization Registry
- if allowed, it forwards the request to the ContextBroker to be answered
⚠️ Step 5 is not implemented yet, therefore becomes the challenge. In order to connect the OnBoarding-Service with actual Dataspaces, a services implementing the EBSI Trusted Issuers Registry API retrieves the TrustedIssuers-Information from the ContextBroker and provide them to the Dataspace.
| Address | Paths | Description | Security |
|---|---|---|---|
| https://portal.gaia-x.fiware.dev/ | OnBoarding Portal | login via VerifiableCredentials | |
| https://animalgoods-kc.gaia-x.fiware.dev/ | realms/fiware-server/account/#/ | Keycloak of Animal Goods Org. for retrieving VCs | Users: legal-representativ, standard-employee pw==username |
| https://demo-wallet.fiware.dev/ | FIWARE Demo Wallet | none | |
| https://compliance.gaia-x.fiware.dev/docs/# | docs/# | FIWARE instance of the Gaia-X compliancy serivce, trusted in the demo-environment | none |
| https://registry.gaia-x.fiware.dev/ | Mock instance of the Gaia-X Registry, used to trust the demo compliancy service | none | |
| https://animalgoods.gaia-x.fiware.dev | /did/did.json | Json-Document, allowing to resolve did:web:animalgoods.gaia-x.fiware.dev:did | none |
| https://animalgoods.gaia-x.fiware.dev | /certs | Certifcate chain, referenced by the did.json | none |
| https://onboarding.gaia-x.fiware.dev | /did/did.json | Json-Document, allowing to resolve did:web:onboarding.gaia-x.fiware.dev:did | none |
| https://onboarding.gaia-x.fiware.dev | /certs | Certifcate chain, referenced by the did.json | none |
| https://ar.gaia-x.fiware.dev | Authorization-Registry, used by the OnBoarding-Service | iSHARE-specific | |
| https://kong.gaia-x.fiware.dev | /token | Token helper to get iSHARE-compliant JWT. Used for setting up the policies | X-Api-Key8 |
| https://kong.gaia-x.fiware.dev | /tir | Orion-LD access for implementing the Trusted Issuers Registry. | X-Api-Key8 |
| https://kong.gaia-x.fiware.dev | /walt | Instance of WaltId, can be used to verify credentials against the TIR. | X-Api-Key8 |
| https://kong.gaia-x.fiware.dev | /vc | Access to Orion-LD, used by the portal. Authorization through the PDP. | JWT |
The setup uses various opensource components, the following table contains links to most of them:
The demo-setup stores issuers as NGSI-LD Enities, using the following format:
{
"id":"urn:ngsi-ld:TrustedIssuer:did:web:animalgoods.gaia-x.fiware.dev:did",
"type":"TrustedIssuer",
"issuer":{
"type":"Property",
"value":"did:web:animalgoods.gaia-x.fiware.dev:did"
},
"selfDescription":{
"type":"Property",
"value":{
"gx-terms-and-conditions:gaiaxTermsAndConditions":"70c1d713215f95191a11d38fe2341faed27d19e083917bc8732ca4fea4976700","gx:headquarterAddress":{
"gx:countrySubdivisionCode":"BE-BRU"
},
"gx:legalAddress":{
"gx:countrySubdivisionCode":"BE-BRU"
},
"gx:legalName":"Animal Goods Org.",
"gx:legalRegistrationNumber":{
"gx:vatID":"MYVATID"
},
"id":"did:web:animalgoods.gaia-x.fiware.dev:did",
"type":"gx:LegalParticipant"
}
}
}In order to work, both participants have to be registered in their corresponding Walt-Id instance. To do so, identify the instances running walt-id.
export ONBOARDING_WALT=$(kubectl get pods -n gaia-x --no-headers -o custom-columns=":metadata.name" | grep walt-id-onboarding-vcwaltid | grep -v "certs")
export PARTICIPANT_WALT=$(kubectl get pods -n gaia-x --no-headers -o custom-columns=":metadata.name" | grep walt-id-vcwaltid | grep -v "certs")Then make the core-service locally available, via port-forwarding:
kubectl port-forward ${ONBOARDING_WALT} 7000:7000 -n gaia-x
kubectl port-forward ${PARTICIPANT_WALT} 6000:7000 -n gaia-xIn order to register the DID properly, first get the private key.
export ONBOARDING_RSA=$(kubectl get secret gaia-x-walt-id-onboarding-vcwaltid-tls-sec -o jsonpath="{.data['tls\.key']}" -n gaia-x | base64 --decode)
export PARTICIPANT_RSA=$(kubectl get secret gaia-x-walt-id-vcwaltid-tls-sec -o jsonpath="{.data['tls\.key']}" -n gaia-x | base64 --decode)And import it to walt-id:
export ONBOARDING_KEY=$(curl --location 'localhost:7000/v1/key/import' \
--header 'Content-Type: text/plain' \
--data "${ONBOARDING_RSA}" | jq -r '.id')
export PARTICIPANT_KEY=$(curl --location 'localhost:6000/v1/key/import' \
--header 'Content-Type: text/plain' \
--data "${PARTICIPANT_RSA}" | jq -r '.id')You will receive a key-id as a response. With that ID, register the did:
curl --location 'localhost:7000/v1/did/create' \
--header 'Content-Type: application/json' \
--data "{
\"method\": \"web\",
\"keyAlias\":\"${ONBOARDING_KEY}\",
\"domain\": \"onboarding.gaia-x.fiware.dev\",
\"path\": \"did\",
\"x5u\": \"https://onboarding.gaia-x.fiware.dev/certs/tls.crt\"
}"
curl --location 'localhost:6000/v1/did/create' \
--header 'Content-Type: application/json' \
--data "{
\"method\": \"web\",
\"keyAlias\":\"${PARTICIPANT_KEY}\",
\"domain\": \"animalgoods.gaia-x.fiware.dev\",
\"path\": \"did\",
\"x5u\": \"https://animalgoods.gaia-x.fiware.dev/certs/tls.crt\"
}"After that step, the did.json should be available at https://onboarding.gaia-x.fiware.dev/did/did.json and https://animalgoods.gaia-x.fiware.dev/did/did.json
The onboarding service is secured, using the i4Trust authorization framework. See the Building-Blocks document at 6.4 for detailed information.
The demo setup will use 3 policies:
- Allow Gaia-X compliant participants to issue Verfiable credentials, containing the roles
LEGAL_REPRESENTATIVEandEMPLOYEE.
{
"delegationEvidence": {
"notBefore": 1614354348,
"notOnOrAfter": 1737894651,
"policyIssuer": "EU.EORI.DEONE",
"target": {
"accessSubject": "Gaia-X"
},
"policySets": [
{
"target": {
"environment": {
"licenses": [ "iSHARE.0001" ]
}
},
"policies": [
{
"target": {
"resource": {
"type": "VerifiableCredential",
"identifiers": [
"*"
],
"attributes": [
"LEGAL_REPRESENTATIVE",
"EMPLOYEE"
]
},
"actions": [
"ISSUE"
]
},
"rules": [
{
"effect": "Permit"
}
]
}
]
}
]
}
}- Allow participants in Role
LEGAL_REPRESENTATIVEto CRUD TrustedIssuers:
{
"delegationEvidence": {
"notBefore": 1614354348,
"notOnOrAfter": 1737894651,
"policyIssuer": "EU.EORI.DEONE",
"target": {
"accessSubject": "LEGAL_REPRESENTATIVE"
},
"policySets": [
{
"target": {
"environment": {
"licenses": [ "iSHARE.0001" ]
}
},
"policies": [
{
"target": {
"resource": {
"type": "TrustedIssuer",
"identifiers": [
"*"
],
"attributes": [
"*"
]
},
"actions": [
"POST",
"GET",
"PUT",
"DELETE"
]
},
"rules": [
{
"effect": "Permit"
}
]
}
]
}
]
}
}- Allow employees to view TrustedIssuers:
{
"delegationEvidence": {
"notBefore": 1614354348,
"notOnOrAfter": 1737894651,
"policyIssuer": "EU.EORI.DEONE",
"target": {
"accessSubject": "EMPLOYEE"
},
"policySets": [
{
"target": {
"environment": {
"licenses": [ "iSHARE.0001" ]
}
},
"policies": [
{
"target": {
"resource": {
"type": "TrustedIssuer",
"identifiers": [
"*"
],
"attributes": [
"*"
]
},
"actions": [
"GET"
]
},
"rules": [
{
"effect": "Permit"
}
]
}
]
}
]
}
}Policy creation follows the same steps for each of them:
- Get an API-Key. In order to make handling of iSHARE-JWT easier, the setup includes a token-helper. To not make all JWT publicly available, the token-helper is available through Kong via an API-Key. To retrieve the key use:
export KONG_POD=$(kubectl get pods -n gaia-x --no-headers -o custom-columns=":metadata.name" | grep kong)
kubectl port-forward ${KONG_POD} 8001:8001 -n gaia-x
export API_KEY=$(curl --location 'localhost:8001/key-auths' | jq -r '.data[0].key')- Use the key to access the token-helper and get an JWT for the AR. Be fast: the token expires after 30s.
export iSHARE_JWT=$(curl --location 'kong.gaia-x.fiware.dev/token?clientId=EU.EORI.DEONE&idpId=EU.EORI.DEONE' --header "X-Api-Key: ${API_KEY}" | jq -r '.token')- Use the JWT to get the access-token from the AR:
export ACCESS_TOKEN=$(curl --location 'https://ar.gaia-x.fiware.dev/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=${iSHARE_JWT}" \
--data-urlencode 'client_id=EU.EORI.DEONE' | jq -r '.access_token')- Create the policy, using the access-token:
curl --location 'https://ar.gaia-x.fiware.dev/ar/policy' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${ACCESS_TOKEN}"
--data '{<THE_POLICY>}'Footnotes
-
While most of the use-case is focused on Human-2-Machine interaction, e.g. a user beeing a Human, the framework is not limited to that. A "user" could also be another service, participating in Machine-2-Machine interaction. ↩
-
Example self-description:
↩ ↩2{ "type" : [ "VerifiableCredential" ], "@context" : [ "https://www.w3.org/2018/credentials/v1", "https://registry.lab.gaia-x.eu/development/api/trusted-shape-registry/v1/shapes/jsonld/trustframework#", "https://w3id.org/security/suites/jws-2020/v1" ], "id" : "urn:uuid:a4c51032-1aab-46ba-8f51-68210a60cc27", "issuer" : "did:web:animalgoods.gaia-x.fiware.dev:did", "issuanceDate" : "2023-04-26T09:17:52Z", "issued" : "2023-04-26T09:17:52Z", "validFrom" : "2023-04-26T09:17:52Z", "expirationDate" : "2023-04-28T21:17:52Z", "credentialSubject" : { "id" : "did:web:animalgoods.gaia-x.fiware.dev:did", "type" : "gx:LegalParticipant", "gx:legalName" : "Animal Goods Org.", "gx:legalRegistrationNumber" : { "gx:vatID" : "MYVATID" }, "gx:headquarterAddress" : { "gx:countrySubdivisionCode" : "BE-BRU" }, "gx:legalAddress" : { "gx:countrySubdivisionCode" : "BE-BRU" }, "gx-terms-and-conditions:gaiaxTermsAndConditions" : "70c1d713215f95191a11d38fe2341faed27d19e083917bc8732ca4fea4976700" }, "proof" : { "type" : "JsonWebSignature2020", "creator" : "did:web:animalgoods.gaia-x.fiware.dev:did", "created" : "2023-04-26T09:17:52Z", "verificationMethod" : "did:web:animalgoods.gaia-x.fiware.dev:did#e1b0c827edd5446ebb830d9a8b9b748c", "jws" : "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJQUzI1NiJ9..SGj9KmaiowH2NOVJtWDN9tnAN4MivHJ2QdijCbTv-7V3ZXXtXrLI7qNkOMyxX9LwJv83S6USWFNoqWiluB8CiGYkfFe1FexqWBbodIIqxCM0xO7k2y78Zy_aMTjWkcFuKeGtELL6VeBnQglQauAOMOX60_-TRxNp96K8bJ-8O7EfJQhJnDVq5Dx6XE6oG4_vQyeDPafxb1_JmtjqG0aZ5b8ZRjPYkCYzpeomV4hAtOCT8xN7W6d7vAw07IeVZ_mcvk4OmS6hKND2x3g_gLfroTf43kx0sI-HeD6x4F3wCb_yFvxzolXZ4yI-f-JHalTwFuLJUKlrhNPsjse1eqRGCQ" } } -
Compliancy Credential:
↩ ↩2{ "@context": [ "https://www.w3.org/2018/credentials/v1", "http://gx-registry-development:3000/development/api/trusted-shape-registry/v1/shapes/jsonld/trustframework#" ], "type": [ "VerifiableCredential" ], "id": "https://storage.gaia-x.eu/credential-offers/b3e0a068-4bf8-4796-932e-2fa83043e203", "issuer": "did:web:compliance.lab.gaia-x.eu:development", "issuanceDate": "2023-04-26T09:19:11.791Z", "expirationDate": "2023-07-25T09:19:11.791Z", "credentialSubject": [ { "type": "gx:compliance", "id": "did:web:raw.githubusercontent.com:egavard:payload-sign:master", "integrity": "sha256-9fc56e0099742e57d467156c4526ba723981b2e91eb0ccf6b725ec65b968fcc8" } ], "proof": { "type": "JsonWebSignature2020", "created": "2023-04-26T09:19:12.415Z", "proofPurpose": "assertionMethod", "jws": "eyJhbGciOiJQUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..bSsi9yohByC9021w1AiLvzgIozgYqTAWLBkEWC8Qay043k81p6UzWfZ04rFv48agxkzDHwCxlFGO_N24SLJvHieZwRJnyoM-VfIYfSJ-9iTI07TMQl-wd03sO5x4R8YWIDeSd3hoWkn5csmQYhQlXmwLRKpMni0qgMMmMTR336XkSImq5NpEiB8QzwJVkmjn4oHHELwEPa3HSfAl42lTUvAwQceaNU288QrPC0ykRW4mdPmKk5TXgkf19tolj8xwhr-pncVv_0D7LH3bYoFzzvNBeQQZ3LOT5tr9QD6AjIJN126gX1ia6gMdmj5SKT_7KgtWk9npsKg3hggpbnihBA", "verificationMethod": "did:web:compliance.lab.gaia-x.eu:development" } } -
Natural Person Credential:
↩ ↩2{ "type" : [ "VerifiableCredential", "NaturalPersonCredential" ], "@context" : [ "https://www.w3.org/2018/credentials/v1", "https://w3id.org/security/suites/jws-2020/v1" ], "id" : "urn:uuid:2eff859a-1474-4e51-a897-0e1360fecff9", "issuer" : "did:web:animalgoods.gaia-x.fiware.dev:did", "issuanceDate" : "2023-04-26T09:41:32Z", "issued" : "2023-04-26T09:41:32Z", "validFrom" : "2023-04-26T09:41:32Z", "expirationDate" : "2023-04-28T21:41:32Z", "credentialSchema" : { "id" : "https://raw.githubusercontent.com/FIWARE-Ops/tech-x-challenge/main/schema.json", "type" : "FullJsonSchemaValidator2021" }, "credentialSubject" : { "id" : "d7704c3f-4f13-474d-980c-6036ef670157", "type" : "gx:NaturalParticipant", "familyName" : "Happy", "firstName" : "User", "roles" : [ { "names" : [ "LEGAL_REPRESENTATIVE" ], "target" : "did:web:onboarding.gaia-x.fiware.dev:did" } ], "email" : "[email protected]" }, "proof" : { "type" : "JsonWebSignature2020", "creator" : "did:web:animalgoods.gaia-x.fiware.dev:did", "created" : "2023-04-26T09:41:32Z", "verificationMethod" : "did:web:animalgoods.gaia-x.fiware.dev:did#4057b20fdc4a4c25abaab4f44de95c0f", "jws" : "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJQUzI1NiJ9..Wm4S4chhXVYAibziWZ6HFUntav8xQz6iG9Lc-qyjnmeHeDrPvOnEMbKqQ1EmKzRhq1XHVl_yTEKo0T5F26ArbDokvaz-dK9LPa3PNkY8S-s5CAi5ufAIuO8FFqbCmonGr140U9_iLGYqaXEYpK9-AjmKl_-jB88jFlBxapbKEKGdHH1vrhggL_xbNmgbcRlueRgOWmHzy2RhFnzHxmpiCl6cvsHKB6dT-Q-VfBvwYExrJqGzLiGvxcNcqKnZ1OVEmaI7KPKQ8GBTvdp7P46gEVLlW_BQYdv3uDlHnoTZhz4ufJBLwMqiYrXvMmmscllnH_BUv2lUYXPRRBdSBD3EBA" } } -
The FIWARE Demo-Wallet and the Animal Goods Org. Keycloak can be used for example. ↩
-
To make issuing easier, a compliancy service trusting our participants is provided at https://compliance.gaia-x.fiware.dev ↩
-
Some APIs are not typically public available, but provided for the hackathon to support the development and testing. They are secured, using Kong's API-Key functionality. Provide the key as
X-Api-Key-header. Get one:
↩ ↩2 ↩3export KONG_POD=$(kubectl get pods -n gaia-x --no-headers -o custom-columns=":metadata.name" | grep kong) kubectl port-forward ${KONG_POD} 8001:8001 -n gaia-x curl --location 'localhost:8001/key-auths' | jq -r '.data[0].key')