Organization Entities

What are Entities

Every organization is registered as a member within the blockchain ledger. While invoking any method in the blockchain using REST API or GraphQL API, an Api key is used to authenticate which identifies the organization that is making the call. Sometimes, you would want to invoke a method on behalf of a user, department, sub-organization, vendor or any other entity that belongs to the parent organization. For e.g. a loyalty management organization might have multiple users on behalf of whom transactions have to be conducted or a healthcare organization might be providing services to different pharmacies and prescriptions are managed on behalf of these pharmacies.

In such cases, the API calls can be made on behalf of an Entity. An Entity is identified by a key:value pair. For e.g. "userId:1234", "pharmacy:ph876" or "vendorId:345v" are all valid Entities. Basically, you have the flexibility to specify the Entity key (like userId, pharmacy, vendorId) etc. and the actual value.

How do I use entities

Entities can be used in two different ways:

• Assigning assets to entities: In any API call, where assets can be assigned to organizations, you can assign them to Entities instead. For e.g to assign the ownership of an asset to an organization using the Ownership transfer API, the new owner organization will be specified as below:

{​
  "assetType": "Property",​
  "id": "Prop1",​
  "owners": [​
    {​
      "orgId": "63c912fd5902d6c20ac43c89",​​
    }​
  ]​
​}

To assign the same asset to an entity within the organization, you would do the following. Just add the entity that is part of the organization.

{​
  "assetType": "Property",​
  "id": "Prop1",​
  "owners": [​
    {​
      "orgId": "63c912fd5902d6c20ac43c89",​
      "userId": "1234"​
    }​
  ]​
​}

• API calls on behalf of an Entity: In any API call, if you add the additional query string parameter "actAs=Entity", the call to the blockchain will be made on behalf of that Entity. This means that any permission evaluations will be done in the context of the specified Entity. For e.g. when you add the query parameter "actAs=userId:1234" while calling the GetAsset API, it will only return results if the userId 1234 is an owner of the asset or has read permissions on it. Essentially, the call will be made in the context of userId 1234.

How does it work in Hyperledger Fabric?

The Entity based authentication and authorization uses the Attribute based access control concept in Hyperledger Fabric. The Spydra platform uses the Entity key and value specified in the actAs query parameter to create a certificate that uniquely identifies that Entity by adding the key/value pair as an additional attribute in the certificate. The blockchain calls are made by signing the requests by using this certificate. This additional attribute can then be extracted from the certificate and used in the App/Chaincode (pre-configured or custom) to make access control decisions.