or
or
By clicking below, you agree to our terms of service.
New to HackMD? Sign up
Syntax | Example | Reference | |
---|---|---|---|
# Header | Header | 基本排版 | |
- Unordered List |
|
||
1. Ordered List |
|
||
- [ ] Todo List |
|
||
> Blockquote | Blockquote |
||
**Bold font** | Bold font | ||
*Italics font* | Italics font | ||
~~Strikethrough~~ | |||
19^th^ | 19th | ||
H~2~O | H2O | ||
++Inserted text++ | Inserted text | ||
==Marked text== | Marked text | ||
[link text](https:// "title") | Link | ||
 | Image | ||
`Code` | Code |
在筆記中貼入程式碼 | |
```javascript var i = 0; ``` |
|
||
:smile: | ![]() |
Emoji list | |
{%youtube youtube_id %} | Externals | ||
$L^aT_eX$ | LaTeX | ||
:::info This is a alert area. ::: |
This is a alert area. |
On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?
Please give us some advice and help us improve HackMD.
Syncing
xxxxxxxxxx
Identity Hub Attestation Flows and Components
Contributors:
Abstract
In this document, we define a set of user flows and describe the associated Action Objects that support a Hub-centric approach to the request, issuance, presentation, verification, and revocation of interoperable attestations. This document extends the Identity Hub Explainer.
1 Introduction
In the digital identity space, Hubs let you securely store and share data. A Hub is a datastore containing semantic data objects at well-known locations. An identity needs to be able to prove that some data is true to another entity that requests it. These attestations are that method of proof. In the digital world, the requester may be software, and the response may or may not require involvement of the individual/identity who the proof is being made against. These examples and flows depict how attestations are requested and resolved.
2 Example Use Cases
We use examples here to give guidance/suggestions for how attestations can be used with real world examples. The overall use case is a person, Alice who registers for College using that a process that includes using an attestation she possesses to prove she has received some required immunizations. After graduation, Alice requests an attestation from the College that she has graduated, and presents that attestation to her professional profile on a professional network.
Agents
We use the term “User Agent” (UA) to refer to an app on a smartphone or other device that has access to DID-linked keys and the power to do things on behalf of a DID owner (Alice). This could also be referred to as a digital wallet. Similarly, we use the term “Enterprise Agent” (EA) to refer to the comparable component representing an Organization – e.g. a College or professional network. A UA and EA are conceptually the same, but while the UA is likely a personal device (laptop, tablet, phone), an EA is likely a service that processes requests based on business rules and data held in back end systems. Note that an EA might need input from a specific member of the organization to complete the processing of a request. In that case, the EA might contact that user through that person’s User Agent (although there are many other possibilities).
Sites
In the examples below, “Sites” are assumed to be Web or Mobile Site – user interfaces that allow a user (in our case, Alice) to trigger the start of a process. There are many other ways to trigger the start of such a process.
Decentralized IDs (DIDs), Documents and Attestations
Each of Alice's Decentralized Identifiers (DIDs) referenced in the scenarios is generated and held by her user agent (UA) and used for a specific purpose - for example her relationship with the College. Each of her DIDs are not necessarily correlated to any other identifiers that make up her identity. Per the W3C DID Specification, associated with a DID is a DID Document that contains information about the public keys and service endpoints for that DID. Thus, given a DID and DID Document for another Identity, an entity has a mechanism to resolve and communicate with the Identity Owner of the DID. DIDs may be public and stored on a publicly available Distributed Ledger, with their associated DID Document found via the DIF Universal Resolver, or may be pairwise private DIDs, where two Identities directly exchange DIDs/DID Documents.
An attestation is something (such as a Verifiable Credential) issued by an entity to a holder (often the subject of the attestation) so that the holder can prove they hold the attestation to others. In one of the examples below, for instance, Alice wants to receive a graduation attestation from the College so that they can present (prove) that attestation to a professional network.
Interface Guidelines: Hubs, Agents and Identity Owners
Some basic guidelines are defined about Hubs, Agents, and their Identity Owners:
Private keys are accessible only to Agents (User and Enterprise), thus any encrypting/signing of information must be done by an Agent.
In general, Hubs are addressable using the service pointers located in a DID Document, and Agents are addressed via a user's Hub. The only exception is invocation of a User Agent through direct mechanisms, like a deep link on a mobile site, a QR code on a Web site scanned by a User Agent, or a Bluetooth/NFC data exchange.
Hubs generally have limited, generic functionality, and any decision making must be made at the Agent level via a user app/device (User Agents) or more automated business services (Enterprise Agents).
For simplicity we show the Hub and Enterprise Agent as a single entity in the following scenarios. In typical implementations, those will be separate entities that communicate to accomplish their respective activities.
2.1 Alice links to an Entity
In order to communicate a request for attestation to an entity (in our examples, Alice), will first need to establish a connection between her user agent and the entity she will interact with. This is necessary for all follow-on scenarios.
Alice wants to transact with the entities described in the scenarios with the intent to receive or exchange attestations. First and foremost, the entity must verify that Alice is the owner of the decentralized identifier she claims. In order to find Alice’s user agent, we leverage the Universal Resolver (UR) to lookup Alice’s Decentralized Identifier (DID) to find her DID Document (DDO). The keys located in Alice's DDO are used to authenticate Alice’s ownership of the DID, and determine access to Alice’s hub and user agent.
Alice navigates to an entity’s website and clicks a link to initiate a DID linkage with the entity. The content received from clicking the link includes DID information about the Enitity that Alice should use for the relationship.
The entity prompts for Alice to disclose a DID that represents her digital identity.
Alice selects an existing DID or creates a new DID for this relationship and sends the DID to the Entity Site.
The Entity Site passes the DID to the Entity’s Enterprise Agent to initiate the DID Auth response.
The EA uses the Universal Resolver (UR) to request retrieval of the DID Document that matches the provided DID.
The DID Document is returned to the EA.
The EA initiates the DID Auth process by issuing a challenge to Alice’s Hub.
Alice’s Hub passes the DID Auth challenge to Alice’s User Agent for signing.
Alice’s User Agent proves her identity with a signed response to the auth challenge.
The Entity Hub confirms the response and notifies the Entity Site with a successful login.
2.1.2 DIF Identity Hub 2FA
A second identity linking scenario to consider is when Alice is registering with the site using a device that is not a UA, yet she still wants to use her UA to establish the connection. In this case, Alice discloses a DID connected to her UA to the site, the site contacts the UA and the mobile device containing the UA displays a code for Alice to use. Alice enters the code into a form on the site, proving that she controls the DID.
Alice navigates to an entity’s website and clicks a link to initiate a DID linkage with the entity.
The entity prompts for Alice to disclose a DID that represents her digital identity.
Alice selects an existing DID and sends the DID to the Entity Site.
The Entity/EA uses the Universal Resolver (UR) to request retrieval of the DID Document that matches the provided DID.
The DID Document is returned to the Entity/EA.
The EA initiates the DID Auth process by issuing a challenge to Alice’s Hub.
Alice’s Hub passes the DID Auth challenge to Alice’s User Agent for signing.
Alice’s User Agent processes the challenge and displays on the mobile device a code expected by the Entity Site.
Alice on her laptop enters the code and the Entity Site confirms the response, resulting in a successful login.
2.2 Alice must provide preconditional proof
Alice is attempting to register for College and her DID is already linked to the College. In this example, for Alice to get admitted to the College, Alice must prove she previously has received appropriate immunizations.
Assumptions
Alice initiates a Registration request on the College Site.
The College EA determines there are preconditions for Registration: she must prove she has the required immunizations. The College EA initiates a request for presentation of the preconditions.
Alice is prompted by her UA to provide the preconditions.
Alice selects the correct attestation to use and her UA sends them back to the College Hub.
The College EA processes the preconditions and sends a Registered Student attestation to Alice's Hub.
Alice accepts the request to accept/store the College registration attestation.
Alice’s Hub stores the Registered Student attestation and broadcasts it to her connected devices.
Referenced Action Objects
2.3 Alice obtains a diploma attestation
In this example, Alice has graduated from College and wants to acquire a digital diploma attestation.
Assumptions
Alice initiates a request through the College website to obtain an attestation regarding her graduation.
College website reaches out to its Enterprise Agent service to determine what attestations are available for Alice.
The College's EA sends an attestation offer to Alice’s Hub.
Alice's UA receives a Action from the College EA that contains the attestations it can provide. Alice selects the attestations she wants.
Alice's UA sends an attestation request for her selected attestations to the College's Hub.
The EA delivers the attestations to Alice's Hub.
Alice is prompted to accept or deny the attestation.
Alice accepts the attestation and stores it across her Hubs and devices.
Referenced Action Objects
2.4 Alice shares her education verification, and future updates, with a professional networking site
Alice has graduated from College, possesses an attestation from the College, and wants to share her existing and future education attestations with a professional networking site.
Assumptions
Alice navigates to the professional network site and initiates the flow to grant access to her educational attestations.
The website sends a
RequestPermissionAction
to Alice’s hub.Alice’s Hub relays the request to Alice's UA, which prompts her to grant/deny permission.
Alice grants permission to access her current and future educational attestations by pushing a signed permission object and DID-specific keys to her Hub.
Alice’s Hub stores the keys she generated for the professional networking site, and relays a Action to the professional network's Hub to provide notice that their permission request has been granted.
The Prof Site is notified that the permission has been granted.
At any time in the future, the professional networking site can retrieve Alice’s education credentials from Alice’s Hub, based on the permissions she provided and using the private key held by the professional networking site.
Referenced Action Objects
2.5 Alice applies for job and refuses to provide references
Alice is applying for a job and has connected with the HR department via her DID. Alice has already provided some basic attestations about her right to work, name, address, etc. But when she receives a request for her references Alice refuses/denies the request as by the time this request comes in Alice has already accepted a position somewhere else (for example).
Assumptions
HR initiates a request for references via Alice’s Hub
Alice's Hub finds appropriate Attestations and provides them to Alice's User Agent.
For whatever reason, Alice refuses (via her agent) to provide references at this time
Alice’s Hub notifies HR Hub of the refusal (reason for refusal is optional)
A notification is sent to HR with the refusal details (generic or specific to the scenario)
Referenced Action Objects
2.6 A bank sends Alice a contract that requires her DID signature, which she signs and delivers back to the bank.
Referenced Action Objects
2.7 The College determines Alice was issued a nursing certificate instead of her CS diploma, so they revoke the attestation and issue the correct one.
Referenced Action Objects
2.8 Alice retracts data access permission from a professional networking site.
Referenced Action Objects
2.9 Alice's College discovers they made a mistake on her diploma attestation, and sends her an amended attestation with the correct info.
Referenced Action Objects
3 Action Objects
Identity Hub attestation handling relies on the passage and recognition of common Action types that Hubs, User Agents, and consuming apps/services understand. In order to ensure that the flows related to attestations are precise and maximally descriptive of their intent, the Identity Hub spec will define its own Action objects for each of the relevant attestation actions. These objects are extensions of the Schema.org Action object, the schema origin of which shall be schema.identity.foundation. These objects are strictly a shared means of communicating and facilitating the various activities related to attestations, they do not infer or require a specific type of proof format or material be used within them.
Note that each Action returns only a status of whether the Action was successfully (or not) transmitted. The result of processing the request is conveyed to the caller via a subsequent Action.
The following is a description of the objects and examples that encompass their structure and properties:
3.1 RequestAttestationAction
The Holder requests an attestation from an Issuer.
3.2 DenyAttestationAction
In response to a request for an Attestation, a Verifier/Issuer informs a Holder that the attestation cannot be provided. This
Action
inherits from schema.org'sRejectAction
.3.3 PreconditionsAttestationAction
In response to a request for an Attestation, a Verifier/Issuer informs a Holder a list of Pre-Conditions that must be met before the requested Attestation can be issued.
3.4 OfferAttestationAction
In response to a request for an Attestation that cannot be issued because that type is not available, provide to the Holder a list of attestations that ARE available.
3.5 DeliverAttestationAction
Used by any party that delivers a finalized attestation to a target entity. This
Action
inherits from schema.org'sSendAction
.3.6 PresentAttestationAction
This Action is the envelop used to present an attestation to an inspecting party.
3.7 SignAttestationAction
A party sends a Action to a target prompting them to sign the provided attestation payload. This
Action
inherits from schema.org'sEndorseAction
.3.8 RevokeAttestationAction
The party that previously supplied an attestation sends a notice to the attestation owner/holder that issuing party has revoked the attestation. This
Action
inherits from schema.org'sDeactivateAction
.3.9 AmendAttestationAction
Require past ID, optionally include previous attestation. This
Action
inherits from schema.org'sReplaceAction
.3.10 RequestPermissionAction
Request permission for access to a DID's Identity Hub data. This
Action
inherits from schema.org'sAuthorizeAction
.3.11 GrantPermissionAction
The party that allows a permission sends a notice to the requesting party to let them know the permission has been granted. This
Action
inherits from schema.org'sAcceptAction
.3.12 DenyPermissionAction
The party evaluating the permission request does not grant the permission, and sends the requesting party a notice of the denial. This
Action
inherits from schema.org'sRejectAction
.There is not currently an example of this action in the scenarios in Section 2 of this document.
3.13 RetractPermissionAction
The party that has previously issued a permission granting access sends a notice to the affected party to let them know the permission has been retracted. This
Action
inherits from schema.org'sDeleteAction
.3.14 RetrieveAttestationsAction
Used by any party that has been granted permission access to a set of Attestations via the GrantPermissionAction to retrieve a set of Attestations.
4 Glossary
Decentralized Identifier: Decentralized Identifiers (DIDs) are a new type of identifier for verifiable, "self-sovereign" digital identity. DIDs are fully under the control of the DID subject, independent from any centralized registry, identity provider, or certificate authority.
DID: Decentralized Identifier
DID Auth: Authentication of an Identity by verifying the Identities control of it's DID
DID Document: The control document that specifies keys, service endpoints, and other basic details about a DID.
DDO: Abbreviation for a DID Document
EA: Enterprise Agent: a HUB-aware service that integrates with an Enterprise’s backend systems and representatives to process HUB requests. Conceptually equivalent to a person’s UA, but for an organization.
UA: Abbreviation for User Agent
Universal Resolver: A mechanism of getting the DID Document associated with a DID across any (supported) DID implementation
UR: Abbreviation for Universal Resolver
User Agent: a smartphone-based digital wallet, browser
5 Technical & Spec Implications