ereuse/idhub-help
9
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

updates to my community

Browse source
This commit is contained in:
leandro@ac.upc.edu 2025-02-21 14:24:12 +01:00
parent e613e3a00b
commit fc5c43c2f1
19 changed files with 396 additions and 122 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
.gitignore vendored
View file

@ -1,3 +1,19 @@
.venv/
.vscode/
site/
site/404.html
site/index.html
site/sitemap.xml.gz
site/ca/index.html
site/ca/admin/index.html
site/ca/sobre/index.html
site/ca/usuari/index.html
site/en/index.html
site/en/about/index.html
site/en/admin/index.html
site/en/user/index.html
site/es/index.html
site/es/acerca/index.html
site/es/admin/index.html
site/es/usuario/index.html
site/search/search_index.json

106
docs/en/community.md
View file

@ -1,51 +1,103 @@
# IdHub for a new community
# A new community
Let’s imagine a community of organisations that want to exchange verifiable credentials (VC): the NGO federation in Uqbar (a fantastic country from J. L. Borges literature). There will be three roles:
* Trusted authority organisations (TAO): the governmental entities with authority to recognise legal actors in Uqbar.
* Trusted Issuers (TI): NGOs that relate to people as employees, members or beneficiaries. They can receive credentials from any of these NGO as a credentialSubject.
* Holders: citizens or organisations that can hold credentials. They hold them in their private wallet.
* Verifiers: organisations that can accept the presentation of credentials from subjects wich are interested in any benefit from verifiers (e.g. access or discount). The information in these credentials about these holders/credentialSubjects come from issuers, which may be accredited or recognised as such by trusted authority (Uqbar government).
Let’s imagine a community of organisations that want to exchange verifiable credentials (VC): the NGO federation in Uqbar _(a fantastic country from J. L. Borges literature)_. There will be five roles:
Ideally, Friends of Uqbar (FoU) organisation receives a NGO paper credential and a VC (c1) after registration in Uqbar's government, and a NGO federation member VC (c2). These two credentials are deposited in a public digital registry. These VC allow PAN to operate as NGO in Uqbar.
1. *Trusted authority organisations (TAO)*: the governmental entities with authority to recognise legal actors in Uqbar.
2. *Trusted Issuers (TI)*: NGOs that relate to people as employees, members or beneficiaries. They can receive credentials from any of these NGO as a credentialSubject.
3. *Holders*: citizens or organisations that can hold credentials. They hold them in their private wallet.
4. *Verifiers*: organisations that can accept the presentation of credentials from subjects wich are interested in any benefit from verifiers (e.g. access or discount). The information in these credentials about these holders/credentialSubjects come from issuers, which may be accredited or recognised as such by trusted authority (Uqbar government).
5. *Public registries*: where identifiers (DID), schemas, accreditations, VC issuance are registered. This registry is a trusted third-party, reachable to all, stores minimal data, and replicated to avoid data or service loss or tampering.
Vulnerable Smith is a beneficiary of FoU. PAN know well his situation and it receives in his ID wallet a VC (c10) as beneficiary that describes he passed a training course and is qualified to work as a entry-level blacksmith. The issuance of that VC (minimal details, at least its unique ID) is registered in a public registry (replicated to avoid data or service loss or tampering).
This is the scenario according to EBSI, derived from the W3C model for VC:
![EBSI schema](img/ebsi-model.png){ align=center }
V. Smith applies for a job in the Iron for good (IfG) NGO. He has to fill in a web form for that but furthermore he can present IfG the VC with his professional qualification. The web form details may not be trusted but the presented presented VC (c10) is verifiable: The presentation act (of c10) is signed by the applicant (V. Smith). The details included (in c10), about V. Smith as credentialSubject, are signed by the issuer (FoU). The issuer, about FoU as credentialSubject is recognised (in c1) by Uqbar's government and the NGO Federation (in c2). These credentials (c1, c2, c3) are registered in the public registry. All actors trust these credentials, and issuers can revoke credentials if they change their mind (V. Smith is proven to cheat in the revision of the final exam) by adding his training credential (c10) to the VC revocation list in the public registry. The same can apply for FoU for any wrongdoing by FoU, with their VC (c2) revocation. In addition, since all verification rely on actor and credential identifiers stored in the public registry, FoU never knows is never contacted by employers so does not know if V. Smith used the credential and which employers he contacted.
The NGO federation can agree with Uqbar's education ministry on an accreditation for certain degrees and the fields to include in a training VC for all member organisations. These diplomas comply with the schema of any training diploma in Uqbar (include data fields, required or optional, defined the education ministry) and those defined by the NGO federation for their courses.
That standardisation of the fields, their meaning, types and correct values, required and optional ensures any of the associated VC are well understood and recognised by any actor in Uqbar.
Ideally, the *Friends of Uqbar* (FoU) organisation receives a NGO paper accreditation and a VC (c1) after registration from Uqbar's tax authority, and a NGO federation (NGOF) member VC (c2). These two credentials are deposited in a public digital registry. These VC allow FoU to operate as NGO in Uqbar.
Any actor in Uqbar has a unique identifier (the decentralized identifier or DID) and two keys associated. The public key, that can be deducted (looked up) from the actor's DID, and the private, that as the name says is never shared by an actor. A signature string generated by the private key can be verified by anyone using that actor's public key. Therefore my address is my DID, that leads to find my public key. My identity consists on holding my private key. Sharing my identity is too risky as I am sharing my identity too: another actor can act as me (my DID) publicly.
The *NGO federation* can agree with Uqbar's *education ministry* on an accreditation for certain degrees and the fields to include in a training VC for all their member organisations. These diplomas comply with the schema of any training diploma in Uqbar (include data fields, required or optional, defined the education ministry) and those defined by NGOF for their courses. The NGO federation receives an accreditation from the Ministry of Education, and issues another accreditation to all member NGOs that pass a training course and qualify as training actors and therefore diploma issuers to trainees.
## The community publishes public details about their credentials for public usage
For the NGO community to use IdHub to issue training credentials for vulnerable citizens they have first to publish a several agreed details about their training credentials:
Vulnerable Smith is a beneficiary person of FoU. FoU knows well his situation and receives in his ID wallet a VC (c10) as beneficiary signed by FoU. In that VC it details he passed a training course and is qualified to work as a blacksmith operator. The issuance of that VC (minimal details, at least its unique ID) is registered in a public registry.
V. Smith applies for a job in the *Iron for good* (IfG) NGO. He has to fill in a web form for that but furthermore he can present IfG the VC with his professional qualification.
In summary, we have these organisations:
- TAO: tax authority, education ministry, NGO federation
- Trusted issuer: FoU
- Credential subject: V. Smith citizen
- Verifier: IfG
The list of credentials (VC accreditations):
- c1: As a registered org, issued by Tax authority to FoU.
- c2: As a registered NGO, issued by NGOF to FoU.
- c10: As a beneficiary subject, issued by FoU to V. Smith
The web form details may not be trusted but the presented VC (c10) by V. Smith to IfG is verifiable:
- The presentation act (of c10) by V. Smith (from his wallet) is signed by the applicant (V. Smith).
- The details included (in c10) are about V. Smith himself as credentialSubject, are signed by the issuer (FoU).
- The issuer, FoU, has other credentials issued by Uqbar's tax office (c1) and NGOF (in c2) with FoU as credentialSubject, that confirm that FoU is a valid/accredited issuer for a beneficiary VC.
- These credentials (c1, c2, c10) are registered in the public registry.
- All actors who trust Uqbar's government will also trust all these credentials (chain of trust).
- VC issuers can always revoke credentials if they change their mind (e.g. V. Smith is proven to cheat in the revision of the final exam) by adding his training credential (c10) to the VC revocation list in the public registry. The same can apply for FoU for any wrongdoing by FoU, with their VC (c2) revocation.
- VC do not ring home. Since all verifications rely on actor and credential identifiers that are stored in the public registry, FoU never knows, is never contacted, by employers so does not need to know if V. Smith used the credential or not and which employers he contacted.
- The standardisation of the fields, their meaning, types and correct values, required and optional ensures any of the associated VC can be used, are well understood and recognised by any actor in Uqbar.
- Any actor in Uqbar has a unique identifier (the decentralized identifier or DID) and two keys associated. The public key, that can be deducted (looked up) from the actor's DID, and the private, that as the name says is never shared by an actor. A signature string generated by the private key can be verified by anyone using that actor's public key. Therefore my address is my DID, that leads to find my public key. My identity consists on holding my private key. Sharing my identity is too risky as I am sharing my identity too: another actor can act as me (my DID) publicly.
## A community agrees and publishes about their credentials
For NGO community members, to issue training credentials for vulnerable citizens, they have first to publish a set of documents with several agreed upon details about their training credentials for public awareness:
## Context:
(check [./context](https://github.com/eReuse/IdHub/blob/release/context) folder)
The terms used to refer to credential fiels: the context (vocabulary or terms for fields) for credentials issued by that community: which terms are agreed upon and which definitions to avoid misunderstandings):
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/context/course-credential.jsonld)
(check [./context](https://github.com/eReuse/IdHub/tree/release/context) folder)
The terms used to refer to credential fiels: the context (vocabulary or terms for fields) for credentials issued by that community: which terms are agreed upon and which definitions to avoid misunderstandings:
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/context/course-credential.jsonld).
Let’s take "firstName": "https://idhub.pangea.org/context/#firstName”
“firstName” is the term of that vocabulary
"https://idhub.pangea.org/context/#firstName” is the unique identifier given to that definition. It looks like a URL but doesn’t need to work as such. It allows for the detection of different interpretations when these identifiers differ. For instance, “firstName” with ID “https://libraries.org/context/#firstName” may not accept the same values as the previous, even if the term is the same since namespaces are different and each community can have their specific definitions and expectations.
Let’s take "firstName": "https://idhub.pangea.org/tree/release/context/#firstName”
“firstName” is the term of that vocabulary and "https://idhub.pangea.org/context/#firstName” is the unique identifier given to that definition. It looks like a URL but doesn’t need to work as such.
It allows for the detection of different interpretations when these identifiers differ. For instance, “firstName” with ID “https://libraries.org/context/#firstName” may not accept the same values as the previous, even if the term is the same since namespaces are different and each community can have their specific definitions and expectations.
Not in this case, but if these identifiers work as Web URLs, a visit to that URL on a web browser could bring a web page that describes that term for humans in more detail: precise definition, meanings, possible values, etc.
## Schemas:
(check [./schemas](https://github.com/eReuse/IdHub/blob/release/schemas) folder)
(check [./schemas](https://github.com/eReuse/IdHub/tree/release/schemas) folder)
The credential schema for that credential defines the correct structure, fields, and values, with mandatory and optional fields and possible values, including type and syntax. It allows checking whether a given credential instance is valid or not broken before being processed.
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/schemas/course-credential.json).
## Templates:
(check [./vc_templates](https://github.com/eReuse/IdHub/blob/release/templates) folder)
(check [./idhub/templates/credentials](https://github.com/eReuse/IdHub/tree/release/idhub/templates/credentials) folder)
The credential template for that credential is a generic credential with placeholders for each possible value.
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/idhub/templates/credentials/course-credential.json).
## Spreadsheet:
(check [./vc_excel](https://github.com/eReuse/IdHub/blob/release/vc_excel) folder)
Once the credential template is ready, there is need (IdHub developers have a Python script to generate that automatically, will soon be published) that generates a spreadsheet template from most fields in the credential template: an empty XLX spreadsheet that includes as many columns as credential fields, both mandatory and optional, the comments in each column for each field, the corresponding cell format for the column cells according to what is specified to facilitate data import.
(check [./examples/excel_examples](https://github.com/eReuse/IdHub/tree/release/examples/excel_examples) folder)
Once the credential template is ready, there is need (IdHub developers have a Python script to generate that automatically, will soon be published) that generates a spreadsheet template from most fields in the credential template: an empty XLSX spreadsheet that includes as many columns as credential fields, both mandatory and optional, the comments in each column for each field, the corresponding cell format for the column cells according to what is specified to facilitate data import.
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/examples/excel_examples/course-credential.xlsx).
As you can see, communities should agree and publish details about the credentials they are going to use. NGO members can issue these credentials, and third parties, verifier organisation, can accept these since they can understand the content, given all details about them are public and clear, and verify the credential integrity from the signature by an NGO member given its DID, and that the issuer DID corresponds to an accredited member of the NGO federation, and even registered in Uqbar's government. These accreditations are also VC issued by TAO to TI organisations.
For that reason, we don’t have a UI in IdHub to add support for new credential types, but once there is a public community agreement on context, schema and templates, these files can be included in IdHub corresponding folders, and even we can generate an empty spreadsheet with a clear structure to fill in and issue on IdHub any number of these credentials at once.
# In summary
IdHub relies on sending email invites for credential issuance, therefore an email address is a key initial requirement for any actor to use IdHub. Then IdHub generates a DID, public key, private key, and can issue VCs to that actor. One current limitation of IdHub is that each issuer organisation creates a wallet to their VC holders. Therefore, a person related to multiple issuer organisation has multiple separate wallets. We plan to address that limitation soon with you contributions to further development to allow for a single wallet per person. Thanks in advance!
As you can see, communities should agree and publish details about the credentials they are going to use and exchange. NGO members can issue these credentials, and third parties, verifier organisation, can accept these since they can understand the content, given all details about them are public and clear. Others can verify the credential integrity from the signature by an NGO member given its DID, and that the issuer DID corresponds to an accredited member of the NGO federation, and even registered in Uqbar's government. These accreditations are also VC issued by TAO to TI organisations.
For that reason, we don’t have a UI in IdHub to add support for new credential types, but once there is a public community agreement on context, schema and templates, these files can be included in the IdHub's corresponding folders, and even an model (with no subject's data) spreadsheet can be generated with a clear structure to fill in and issue on IdHub any number of these credentials at once.
IdHub relies on sending email invites for credential issuance, therefore an email address is a key initial requirement for any actor to use IdHub, among others required during installation. Then, IdHub generates a DID, public key, private key, and can issue VCs to that actor.
One current limitation of IdHub is that each issuer organisation creates a wallet to their VC holders. Therefore, a person related to multiple issuer organisations has as many separate web wallets. We plan to address that limitation soon with you contributions to further development to allow for a single wallet per person. Thanks in advance!

BIN
docs/en/img/ebsi-model.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 742 KiB

21
site/404.html
View file

@ -583,6 +583,27 @@
<li class="md-nav__item">
<a href="/en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="/en/user/" class="md-nav__link">

21
site/ca/admin/index.html
View file

@ -663,6 +663,27 @@
<li class="md-nav__item">
<a href="../../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../en/user/" class="md-nav__link">

21
site/ca/index.html
View file

@ -663,6 +663,27 @@
<li class="md-nav__item">
<a href="../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../en/user/" class="md-nav__link">

21
site/ca/sobre/index.html
View file

@ -701,6 +701,27 @@
<li class="md-nav__item">
<a href="../../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../en/user/" class="md-nav__link">

21
site/ca/usuari/index.html
View file

@ -606,6 +606,27 @@
<li class="md-nav__item">
<a href="../../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../en/user/" class="md-nav__link">

21
site/en/about/index.html
View file

@ -698,6 +698,27 @@
<li class="md-nav__item">
<a href="../community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../user/" class="md-nav__link">

23
site/en/admin/index.html
View file

@ -12,7 +12,7 @@
<link rel="prev" href="../about/">
<link rel="next" href="../user/">
<link rel="next" href="../community/">
<link rel="icon" href="../../assets/images/favicon.png">
@ -663,6 +663,27 @@
<li class="md-nav__item">
<a href="../community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../user/" class="md-nav__link">

117
site/en/index.html
View file

@ -543,17 +543,6 @@
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Welcome to IdHub
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
@ -564,52 +553,6 @@
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#for-admins" class="md-nav__link">
<span class="md-ellipsis">
For admins
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#for-users" class="md-nav__link">
<span class="md-ellipsis">
For users
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#about-us" class="md-nav__link">
<span class="md-ellipsis">
About us
</span>
</a>
</li>
</ul>
</nav>
</li>
@ -663,6 +606,27 @@
<li class="md-nav__item">
<a href="community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="user/" class="md-nav__link">
@ -836,41 +800,6 @@
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#for-admins" class="md-nav__link">
<span class="md-ellipsis">
For admins
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#for-users" class="md-nav__link">
<span class="md-ellipsis">
For users
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#about-us" class="md-nav__link">
<span class="md-ellipsis">
About us
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
@ -887,6 +816,10 @@
<h1 id="welcome-to-idhub">Welcome to IdHub</h1>
<!--For full documentation visit [idhub.pangea.org](https://idhub.pangea.org).-->
<h1 id="for-installers">For installers</h1>
<p>IdHub needs to be configured to do any meaningful work at your service. Check the <a href="https://github.com/eReuse/IdHub/blob/release/README.md">Readme</a> to setup the ".env" file. A working SMTP connection is required to be able to send emails to participants.</p>
<h1 id="for-communities">For communities</h1>
<p>A new community, a set of organisations sharing credentials, should agree and publish details about their shared understanding about credentials. These details can be added to IdHub before launch to be used in that <a href="community/">community</a>.</p>
<h2 id="for-admins"><a href="admin/">For admins</a></h2>
<ul>
<li>Setup your account as issuer</li>

23
site/en/user/index.html
View file

@ -9,7 +9,7 @@
<link rel="prev" href="../admin/">
<link rel="prev" href="../community/">
<link rel="next" href="../../es/">
@ -594,6 +594,27 @@
<li class="md-nav__item">
<a href="../community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>

21
site/es/acerca/index.html
View file

@ -596,6 +596,27 @@
<li class="md-nav__item">
<a href="../../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../en/user/" class="md-nav__link">

21
site/es/admin/index.html
View file

@ -594,6 +594,27 @@
<li class="md-nav__item">
<a href="../../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../en/user/" class="md-nav__link">

21
site/es/index.html
View file

@ -594,6 +594,27 @@
<li class="md-nav__item">
<a href="../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../en/user/" class="md-nav__link">

21
site/es/usuario/index.html
View file

@ -592,6 +592,27 @@
<li class="md-nav__item">
<a href="../../en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../en/user/" class="md-nav__link">

21
site/index.html
View file

@ -602,6 +602,27 @@
<li class="md-nav__item">
<a href="en/community/" class="md-nav__link">
<span class="md-ellipsis">
A new community
</span>
</a>
</li>
<li class="md-nav__item">
<a href="en/user/" class="md-nav__link">

2
site/search/search_index.json
View file

File diff suppressed because one or more lines are too long

BIN
site/sitemap.xml.gz
View file

Binary file not shown.