# EEA Telecom Working Group: Identity Attestation Flows and Components for abstract API creation (Initial Examples)

## Abstract

In this document, we define a set of user flows and describe the associated Message Objects that support an agent centric approach to the request, issuance, presentation, verification, and revocation of interoperable attestations. Such attestations can then be used in for example identity access management, service access management, account management etc.

## 1 Introduction

In the digital world, an identity needs to be able to prove that some data is true to another entity that requests it. The attestations discussed here are the method of proof. 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. We use Identity as it relates to the concept of decentralized identifiers (DIDs) and their associated document objects as per [the W3C specification](https://w3c-ccg.github.io/did-spec/), see details below.

## 2 Example Use Cases

We use examples here to give guidance/suggestions for how attestations can be used with real-world telecom examples. The overall use case is a person, Alice, who registers for an ISP provider account using a process that includes using an attestation she possesses to prove she holds the required proofs to the claims that are required to open an account such as a driver's license or a credit card. After the account opening, Alice requests an attestation from the ISP that she is now a customer of the ISP provider, and presents that attestation to another telecom provider to, for example, access a service or purchase a specially dicounted product.

#### 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). Similarly, we use the term “Enterprise Agent” (EA) to refer to the comparable component representing an Organization – e.g. an ISP provider. A UA and EA are conceptually the same, but while the UA is likely a personal device such as a laptop, a tablet or a 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 (Alice) to trigger the start of a process. Naturally, 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 are generated and held by her user agent (UA) and used for a specific purpose - for example her relationship with the ISP. Her DIDs are not necessarily correlated to any other identifiers that make up her identity. Per the [W3C DID Specification](https://w3c-ccg.github.io/did-spec/), a DID Document is associated with a DID 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 a mechanism such as the [DIF Universal Resolver](https://github.com/decentralized-identity/universal-resolver), or may be pairwise private DIDs, where two Identities directly exchange DIDs/DID Documents using a message service.

An attestation is something (such as a [Verifiable Credential](https://www.w3.org/TR/verifiable-claims-data-model/)) issued by an entity to a holder (often the subject of the attestation). The holder can then prove to others that they hold the attestation.

#### Interface Guidelines

Some basic guidelines can be defined such as:

- Private keys are accessible only to Agents (User and Enterprise), thus any encrypting or signing of information must be done by an Agent.

- In general, services used by identities are addressable using the service pointers located in a DID Document, and Agents are addressed via user-aware services. The only exception is invocation of a User Agent through direct mechanisms such as 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.

### 2.1 Alice Links to an Entity

In order to communicate a request for attestation to an entity (in our examples, Alice to an ISP), a user 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 is in her control. In order to find Alice’s user agent, a service such as the Decentralizd Identity Foundation's (DIF) Universal Resolver (UR) has to exist to lookup Alice’s Decentralized Identifier (DID), and subsequently retrieve her DID Document Object (DDO). The keys located in Alice's DDO are used to authenticate Alice’s ownership or control of the DID and to determine access to Alice’s identity hub and user agent.

participant Identity Lookup as UR
participant Entity EA as EH
participant Entity Site as ES
participant Alice UA as AUA
participant Alice DID Service as AH

AUA-->ES: 1 Initiates DID Linkage
ES-->AUA: 2 Prompts to disclose DID
AUA-->ES: 3 Discloses DID
ES-->EH: 4 Relay DID
EH-->UR: 5 Lookup DID
UR-->EH: 6 Return DDO
EH-->AH: 7 DID Auth Challenge
AH-->AUA: 8 DID Auth Challenge
AUA-->EH: 9 DID Auth Response
EH-->ES: 10 DID Auth Complete

1. 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.
- Alice may have to use a DID Service such as the DIF Universal Resolver to access the DID Document associated with the DID.

2. The entity prompts Alice to disclose a DID that represents her digital identity.
- If the website was accessed via a laptop/desktop, the website typically displays a QR Code, and Alice uses her mobile wallet app to scan the QR. If the website was accessed via her mobile device, a protocol handler raises Alice's UA app.

3. Alice selects an existing DID or creates a new DID for this relationship and sends the DID to the Entity Site.

4. The Entity Site passes the DID to the Entity’s Enterprise Agent to initiate the DID Authentication (DID-Auth) response.

5. The EA uses the Universal Resolver (UR) to request retrieval of the DID Document that matches the provided DID.

6. The DID Document is returned to the EA.

7. The EA initiates the DID-Auth process by issuing a challenge to Alice’s Identity Hub.

8. Alice’s Hub passes the DID-Auth challenge to Alice’s User Agent for signing.

9. Alice’s User Agent proves her identity with a signed response to the DID-auth challenge.

10. The Entity's Identity Hub confirms the response and notifies the Entity Site of the successful establishment of a relationship such as a login.

#### 2.1.1 Two Factor Authentication (2FA) without a User Agent

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 and displays a code for Alice to use. Alice enters the code into a form on the site, proving that she controls the DID.

participant Identity Lookup as UR
participant Entity Site as ES
participant Alice Laptop as AD
participant Alice Mobile UA as AM
participant Alice DID Service as AH

AD-->ES: 1 Initiates DID Linkage
ES-->AD: 2 Prompts to disclose DID
AD-->ES: 3 Discloses DID
ES-->UR: 4 Lookup DID
UR-->ES: 5 Return DDO
ES-->AH: 6 DID-Auth challenge
AH-->AM: 7 Challenge code displayed
AD-->ES: 8 Enters challenge code

1. Alice navigates to an entity’s website and clicks a link to initiate a DID linkage with the entity.

2. The entity prompts for Alice to disclose a DID that represents her digital identity.

3. Alice selects an existing DID and sends the DID to the Entity Site.

4. The Entity's EA uses the DID Service to request retrieval of the DID Document that matches the provided DID.

5. The DID Document is returned to the Entity's EA.

6. The EA initiates the DID-Auth process by issuing a challenge to Alice’s DID Service.

7. Alice’s DID Service passes the DID-Auth challenge to Alice’s UA for signing.

8. Alice’s UA processes the challenge and displays a code expected by the Entity Site on the mobile device.

9. Alice enters the code on her laptop and the Entity Site confirms the response, resulting in a successful login.

### 2.2 New Account Opening for Alice

Alice is attempting to open an ISP account and her DID is not linked to the ISP. In this example, she must first link her DID to the DID of the ISP and then present proper proof of identity from another trusted source such as a bank or another telecom provider.

#### Assumptions

- Alice has an DID Service accessed via an application on her mobile device.
- Alice has a verified digital attestation for her identity from a trusted identity provider.

Alice performs a DID Authentication as described in section 2.1 to link her DID to the DID of the ISP. After this has been completed, Alice proceeds with the account opening process.

participant ISP EA as CH
participant ISP Site as CS
participant Alice UA as AUA
participant Alice DID Service as AH

AUA-->CS: 1 Triggers registration attestation request
CS-->AH: 2 Message: PreconditionsAttestation (Proof of Identity)
AH-->AUA: 3 Prompts with preconditions
AUA-->CH: 4 Message: PresentAttestation (Identity Attestation)
CH-->AH: 5 Message: DeliverAttestation (Registered)
AH-->AUA: 6 Accepts Attestation?
AUA-->AH: 7 Stores approved attestation

1. Alice initiates a Registration request on the ISP site.

2. The ISP's EA determines that there are preconditions for Registration: she must prove she has a valid proof of identity. The ISP's EA initiates a request for presentation of the preconditions.

3. Alice is prompted by her UA to provide the preconditions.

4. Alice selects the correct attestation to use and her UA sends them back to the ISP's EA.

5. The ISP provider EA processes the preconditions and sends a Registered Account attestation to Alice's DID Service.

6. Alice accepts the request to accept/store the account attestation.

7. Alice’s DID service stores the account attestation and broadcasts it to her connected devices.

#### Referenced Action Objects

- PreconditionsAttestation
- PresentAttestation
- DeliverAttestation

### 2.3 Alice wants to reopen an account

Alice is attempting to open an ISP account and her DID is already linked to the ISP (old customer for example). In this example, she must prove that she previously has received appropriate account attestations.

#### Assumptions

- Alice is linked to the ISP via her DID.
- Alice has a DID Service accessed via an application on her mobile device.
- Alice has a verified digital attestation for her previous account with the ISP.

participant ISP EA as CH
participant ISP Site as CS
participant Alice UA as AUA
participant Alice DID Service as AH

AUA-->CS: 1 Triggers registration attestation request
CS-->AH: 2 Message: PreconditionsAttestation (Proof of previous account)
AH-->AUA: 3 Prompts with preconditions
AUA-->CH: 4 Message: PresentAttestation (Old Account Attestation)
CH-->AH: 5 Message: DeliverAttestation (Registered)
AH-->AUA: 6 Accepts Attestation?
AUA-->AH: 7 Stores approved attestation

1. Alice initiates a Registration request on the ISP site.

2. The ISP's EA determines that there are preconditions for Registration: she must prove she has the proof for the old account. The ISP's EA initiates a request for presentation of the preconditions.

3. Alice is prompted by her UA to provide the preconditions.

4. Alice selects the correct attestation to use and her UA sends them back to the ISP's EA.

5. The ISP's EA processes the preconditions and sends a Registered Account attestation to Alice's DID Service.

6. Alice accepts the request to accept/store the reopened account attestation.

7. Alice’s DID service stores the reopened account attestation and broadcasts it to her connected devices.

#### Referenced Action Objects

- PreconditionsAttestation
- PresentAttestation
- DeliverAttestation

### 2.4 Alice accesses a Service or Benefit with Her ISP provider account attestation

Alice possesses an account attestation from her ISP, and she wants to buy a discounted smart phone from another telecom provider that is part of the her ISP's partner program.

#### Assumptions

- The provider site has linked Alice to her DID via DID Auth.
- Alice has a DID service accessible via an app on her mobile device.
- Alice possesses an account attestation from her ISP.

participant Provider EA as LH
participant Provider Site as LS
participant Alice UA as AUA
participant Alice DID Service as AH

AUA-->LS: 1 Triggers access request
LS-->AH: 2 Message: RequestAccess
AH-->AUA: 3 Prompts to grant attestation access
AUA-->AH: 4 Generates access permission and keys
AH-->LH: 5 Message: GrantAccess
LH-->LS: 6 Notice of access granted
LS-->AH: 7 Message: RetrieveAttestation (ISP Account Proof)
LS-->LH: 8 Validate Attestation
LH-->AH: 9 Message: DeliverAttestation (Proof of Discount)
AH-->AUA: 10 Prompt of Discount Received
AUA-->LS: 11 Select & Request Smart Phone
LS-->AH: 12 Message: RequestAttestation (Proof of Discount)
AH-->LH: 13 Message: PresentAttestation (Proof of Discount)
LH-->LS: 14 Notice of Valid Discount
LS-->AUA: 15 Apply Discount to Smart Phone Price

1. Alice navigates to the provider site and initiates the flow to request access to a discounted smart phone.

2. The website sends a `RequestAccess` Message to Alice's DID Service.

3. Alice’s DID Service relays the request to Alice's UA, which prompts her to grant/deny access permission.

4. Alice grants permission to access her ISP's account attestations by pushing a signed permission object and DID-specific keys to her DID Service.

5. Alice’s DID Service stores the keys she generated for the provider site and relays a `GrantAccess` Message to the Provider EA to provide notice that its permission request has been granted.

6. The provider site is notified by its EA that the access permission has been granted to Alice's DID Service.

7. The provider site sends a `RetrieveAttestation` Message to Alice's DID Service which returns the ISP provider account attestation to the provider site.

8. The provider site requests that the EA validates the attestation.

9. The provider EA validates Alice's attestation and delivers the Discount attestation to Alice's DID Service through a `DeliverAttestation` Message.

10. Alice's DID service prompts Alice in her UA that the discount has been delivered.

11. Alice selects and requests a smart phone on the provider's website.

12. The provider's site sends a `RequestAttestation` Message to Alice's DID service to retrieve the discount attestation to be applied to the smart phone purchase.

13. Alice's DID Service sends a `PresentAttestation` message to the provider's EA.

14. The provider EA sends a notice of a valid attestation to the provider site.

15. The provider site applies the discount to the smart phone price.

Referenced Message Objects

- RequestAccess
- GrantAccess
- RetrieveAttestation
- RequestAttestation
- DeliverAttestation
- PresentAttestation

## 3 Message Objects

Identity Hub attestation handling relies on the passage and recognition of common Message types that DID Services, 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. These objects are extensions of the Schema.org Action object, the schema origin of which shall be schema.entethalliance.org. 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.

The following is a description of the list of objects (more complete -- not included in the above limited examples) and examples that encompass their structure and properties:

### 3.1 RequestAttestation

The Holder requests an attestation from an Issuer.

- Type of attestation wanted
- List of tag strings to describe the attestation
- Detailed, human-readable description of the attestation being requested (mostly for UAs to display to users)
- Who is the attestation for?
- What format do you need it in?
- Enable passing of preconditions
- Option to set a deadline for issuance/fulfillment

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "RequestAttestation",
    "identifier": UNIQUE_ID,
    "for": ["did:foo:123-456"],
    "format": CLAIM_FORMAT,
    "expiration": EPOCH_TIME,
    "description": "California Driver’s License",
    "tags": ["license", "driving", "permit", "DL", "driver’s license"],
    "preconditions": ARRAY_OF_PRECONDITION_PROOFS (optional)
}

### 3.2 DenyAttestation

In response to a request for an Attestation, a Verifier/Issuer informs a Holder that the attestation cannot be provided. This `Message` inherits from schema.org's `RejectAction`.

- Linked attestation action ID
- Reason for refusing the Request Attestation Action.

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "DenyAttestation",
    "identifier": UNIQUE_ID,
    "purpose": "We cannot open your account, you have presented insufficient proofs."
}

### 3.3 PreconditionsAttestation

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.

- Linked attestation action ID
- Specify set of preconditions, each with their own descriptors

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "PreconditionsAttestation",
    "identifier": UNIQUE_ID,
    "preconditions": ARRAY_OF_PRECONDITION_DESCRIPTORS
}

### 3.4 OfferAttestation

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.

- For each attestation type available to the requester:
- Type of attestation
- List of tag strings to describe the attestation
- Detailed, human-readable description of the attestation being requested (mostly for UAs to display to users)
- Formats available for the attestation

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "OfferAttestation",
    "identifier": UNIQUE_ID,
    "availableAttestations": ARRAY_OF_ATTESTATION_DESCRIPTORS
}

### 3.5 DeliverAttestation

Used by any party that delivers a finalized attestation to a target entity. This `Message` inherits from schema.org's `SendAction`.

- Linked attestation action ID
- Payload of the proof material
- Format of the proof material
- Time delivered

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "DeliverAttestation",
    "identifier": "UNIQUE_ID",
    "object": ATTESTATION_PAYLOAD,
    "description": "California Driver’s License",
    "tags": ["license", "driving", "permit", "DL", "driver’s license"]
}

### 3.6 PresentAttestation

This Action is the envelop used to present an attestation to an inspecting party.

- List of tag strings to describe the attestation
- Detailed, human-readable description of the attestation being requested (mostly for UAs and EAs to reason over and use in display)
- Format of the attestation payload
- The attestation payload

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "PresentAttestation",
    "object": ATTESTATION_PAYLOAD,
    "description": "ISP Account",
    "tags": ["ISP_DID", "ISP_Name", "Customer_DID", "Account_Type", "Account_Status"]
}

### 3.7 SignAttestation

A party sends an Action to a target prompting them to sign the provided attestation payload. This `Message` inherits from schema.org's `EndorseAction`.

- Linked attestation action ID
- Payload of the proof material
- Format of the proof material
- Time delivered

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "SignAttestation",
    "identifier": UNIQUE_ID,
    "object": ATTESTATION_PAYLOAD,
    "description": "ISP Account",
    "tags": ["ISP_DID", "ISP_Name", "Customer_DID", "Account_Type", "Account_Status"]
}

### 3.8 RevokeAttestation

The party that previously supplied an attestation sends a notice to the attestation owner/holder that issuing party has revoked the attestation. This `Message` inherits from schema.org's `DeactivateAction`.

- Attestation ID
- Revocation code - array of revocation codes (look for an existing standard)
- Reason for revocation - array of human-readable descriptions of the reason, or URI

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "RevokeAttestation",
    "identifier": UNIQUE_ID,
    "object": ATTESTATION_PAYLOAD 
    {"description": "ISP Account",
    "tags": ["ISP_DID", "ISP_Name", "Customer_DID", "Account_Type", "Account_Status"]}
    "result": REVOCATION_RECORD,
    "purpose": "Your account was revoked."
}

### 3.9 AmendAttestation

Used to update an attestation. Requires past ID, optionally including previous attestation. This `Message` inherits from schema.org's `ReplaceAction`.

- Attestation ID
- Change delta of some kind
- Reason for amendment - array of human-readable descriptions of the reason, or URI

{
    "@context": "http://schema.identity.foundation/",
    "@type": "AmendAttestation",
    "identifier": UNIQUE_ID,
    "object": ATTESTATION_PAYLOAD
    {"description": "ISP Account",
    "tags": ["ISP_DID", "ISP_Name", "Customer_DID", "Account_Type", "Account_Status"]}
    "purpose": "Your account has been reopened"
}

### 3.10 RequestAccess

Request permission for access to a DID's Identity Hub data. This `Message` inherits from schema.org's `AuthorizeAction`.

- Access Permission being requested
- Intended use of data being requested

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "RequestAccess",
    "object": PERMISSION_OCAP,
    "purpose": "Display and filtering on a professional network",
}

### 3.11 GrantAccess

The party that allows a permission sends a notice to the requesting party to let them know the permission has been granted. This `Message` inherits from schema.org's `AcceptAction`.

- Access Permission being requested
- Intended use of data being requested

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "GrantAccess",
    "object": PERMISSION_OCAP
}

### 3.12 DenyAccess

The party evaluating the permission request does not grant the permission and sends the requesting party a notice of the denial. This `Message` inherits from schema.org's `RejectAction`.

- Access Permission being requested
- Intended use of data being requested

{
    "@context": "http://schema.identity.foundation/",
    "@type": "DenyPermissionAction",
    "object": PERMISSION_OCAP,
    "purpose": "I do not want to allow you access at this time",
}

### 3.13 RetractAccess

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 `Message` inherits from schema.org's `DeleteAction`.

- Access Permission being retracted

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "RetractAccess",
    "object": PERMISSION_OCAP,
    "purpose": "I no longer want you to have access to my attestations",
}

### 3.14 RetrieveAttestations

Used by any party that has been granted permission access to a set of Attestations via the GrantPermissionAction to retrieve a set of Attestations.

{
    "@context": "http://schema.entethalliance.org/",
    "@type": "RetrieveAttestations",
    "identifier": "UNIQUE_ID",
    "object": ATTESTATION_PAYLOAD,
    {"description": "ISP Account",
    "tags": ["ISP_DID", "ISP_Name", "Customer_DID", "Account_Type", "Account_Status"]}
}

## 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 Identity's control of its 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 from the Decentralized Identity Foundation

- **UR**: Abbreviation for Universal Resolver

- **User Agent**: a smartphone-based digital wallet, browser

## 5 Technical & Spec Implications

- For the DID Service /permission spec: add optional timeout for access permissions