Participants and identities

Participants and identities

Concepts

A Participant is an actor in a business network. A participant might be an individual an organization. A participant can create assets, and also exchange assets with other participants. A participant works with assets by submitting transactions.

A participant has a set of Identity documents that can be validated to prove the identity of that participant. For example, an individual may have one or more of the following identity documents that prove who they are:

  • Passport
  • Driving license
  • Fingerprints
  • Retina scan
  • SSL certificate

In Hyperledger Composer, participants are separated from the set of identity documents that they can use to interact with a business network.

In order for a new participant to join a business network, a new instance of that participant must be created in the business network. The participant instance stores all of the required information about that participant, but it does not give that participant access to interact with the business network.

In order to grant the participant access to interact with the business network, an identity document must then be Issued to that participant. The new participant can then use that identity document to interact with the business network.

A participant may have an existing identity document that they use to interact with other business networks or other external systems. These identity documents can be reused and Bound to that participant. The new participant can then use their existing identity document to interact with the business network.

Identity documents usually expire after a set period of time. Identity documents may also be lost or stolen. If the identity document expires, or if it needs to be replaced, then it must be Revoked so it can no longer be used to interact with the business network.

However, revoking an identity document does not remove the information about that participant and any assets that they own. Revoking the identity document simply removes the participants ability to interact with the business network using that identity document. Access to the business network can be restored by issuing the participant with a new identity document.

These participant and identity management actions are performed by an existing participant in the business network, for example a regulatory body, or a participant in the same organization who has been trusted to manage participants/identities in that organization.

Participants and identities in Hyperledger Composer

In Hyperledger Composer, the structure of a participant is modeled in a model file. This structure may include various information about the participant, for example the participants name, address, e-mail address, date of birth, etc. New instances of that modeled participant can then be created and added to a participant registry.

Hyperledger Composer requires the use Blockchain identities as the form of identity documents. For example, when deploying a business network to Hyperledger Fabric, enrollment certificates are used as the form of identity document. These enrollment certificates are used to cryptographically sign the transactions that are submitted to the deployed business network.

A deployed business network maintains a set of mappings of identities to participants in the Identity Registry. When an identity is Issued or Bound to a participant, a new mapping is added to the identity registry. When that participant uses that identity to submit transactions to the deployed business network, the Composer runtime looks for a valid mapping for that identity in the identity registry. This lookup is done using the public key signature or fingerprint, essentially a hash of the certificate contents that is unique to that certificate and identity.

Once a mapping is found in the identity registry, the participant for that identity is retrieved from that mapping. That participant becomes the Current Participant, the participant who submitted the transaction. All access control in Hyperledger Composer is based around the current participant. Access control rules that define which participants can perform which operations on which resources all operate on the current participant.

When a participant uses an identity to submit a transaction to the deployed business network for the first time, that identity is Activated. This means that the entry in the identity registry is updated to record the fact that the identity was used for the first time. Additional information about the identity, such as the certificate, may also be recorded in the identity registry during activation if it was not available when the identity was issued or bound to the participant.

If and when an identity is revoked, the entry in the identity registry for that identity is updated to change the status to Revoked. After an identity is revoked, if a participant tries to use that identity to submit a transaction to the deployed business network, that transaction will be rejected.

Identities and Business network cards in the Hyperledger Composer Playground

In the Hyperledger Composer Playground, there is a wallet containing locally stored Business network cards. A Business network card is an access card to a business network, comprising identity data, a connection profile, and the correct certificates for business network access. ID cards can be exported to allow the assignment of identities to others.

Performing identity management tasks in Hyperledger Composer

The Hyperledger Composer Node.js client APIs, REST APIs, and command line interfaces can all be used to perform identity management operations. For example, the following identity management operations are available through all Hyperledger Composer interfaces:

  • Adding a new participant to a participant registry
  • Issuing a new identity to a participant
  • Binding an existing identity to a participant
  • Revoking an identity from a participant
  • Listing all identities in a deployed business network

For more information, see the related tasks and reference material at the bottom of this document.

Business Network

Create a Business Network Definition
Adding participants
Issuing an new identity to a participant
Binding an existing identity to a participant
Listing all identities in a business network
Revoking an identity from a participant

composer participant add
composer identity issue
composer identity bind
composer identity revoke
composer identity list