SSI Credential Governance using ENS Domains

Governance frameworks in the IAM stack


Governance provides the rules and procedures to establish behavior, expectations and trust within an environment. While governance is a critical component of any multi-party network, it is especially critical in decentralized environments, where there is no central authority to define and orchestrate governance mechanisms over every component of the ecosystem.

As an example, consider an application built on top of the Energy Web Chain. Each application must ensure that:

  • Components are in compliance with existing digital frameworks that their application depends on (e.g. cryptocurrency wallets, peer-to-peer protocols or smart contracts)

  • The application has a governance framework that is robust enough to garner stakeholder trust and compliant participation within the application itself (i.e. defining and enforcing who is allowed to do what within the application)

Governance Frameworks

Governance in a network is established through a governance framework (also referred to as a trust framework). The framework provides concrete policies, rules and expectations for the stakeholders within the network.

Energy Web IAM Governance Framework

Energy Web’s IAM governance relies on two systems: role-based hierarchies and verifiable credentials. Used together, these components provide a governance framework for users to interact with the digital infrastructure, and with other users in a secure and self-sovereign manner.

Role credentials are associated with a user’s Decentralized Identifier (DID), which is anchored on the Energy Web Chain in the DID registry. This means that a user’s roles and credentials are not siloed within any one application; because a user can use their DID to register with any application built on top of the Energy Web Chain, their roles and credentials are portable.

Role-based Hierarchies

In the Energy Web IAM ecoystem, role-based hierarchies are defined by organizations, applications, and designated roles within them. The tech stack leverages Energy Web’s Ethereum Name Service to define and namespace relational hierarchies within a system. We decided to deploy our own copy of ENS on the Energy Web Chain as it provides a standard set of widely-used, well-tested smart contracts. Read more about the ENS smart contracts deployed on the Energy Web Chain here.

The namespace hierarchy is built on four levels:

  1. Organization: a top-level organizing body

  2. Sub-organization(s)

  3. Application: a distinct service or functionality provided by an organization or sub-organization

  4. Role: a distinct functionality within an application or within an organization

Role-definition properties

When roles are created within an organization or an application, the creator can define conditions or criteria that restrict who is qualified to take on the role. The role creator can also determine which users (by DID or role) are authorized to issue or revoke a role.

Below is a resolved role definition for a role of "install lead". Note that it contains an enrollment precondition that the subject already has the role (credential) of 'project installer'. The role definition also specifies an expiration date, and asserts that only users that have the role of 'install manager' can issue or revoke this role.

    roleName: "installlead",
    defaultValidityPeriod: 31536000000,
    enrolmentPreconditions: [{
        conditions: ['projectinstaller.roles.testdidproject.apps.suborgs.whitney.iam.ewc'],
        type: role 
    issuer: {
        issuerType: "ROLE",
        rolename: "installmanager.roles.suborgs.whitney.iam.ewc"
    revoker: {
        issuerType: "ROLE",
        rolename: "installmanager.roles.suborgs.whitney.iam.ewc"
    roleType: "org",
    version: 1,
    issuerFields: [],
    requestorFields: []

Verifiable Credentials

Verifiable Credentials enable users and their assets to take on roles within a system (that is, within an organization, a sub-organization or an application within a hierarchy, as discussed above).

See more extensive documentation on credentials in the IAM stack here.

IAM Stack Governance Components

Switchboard provides the user interface for creating and defining these hierarchies. See the Switchboard guide on Governance and role creation here.

The supporting IAM libraries provide the functionality for persisting and resolving namespaced domains Namespace domains that are registered and managed in the Energy Web Ethereum Namespace smart contracts. Read more about the role of Ethereum Name Space in Energy Web Digital Infrastructure here.

These libraries also support governance by providing credential verification mechanisms. This is discussed further in the Credential documentation.

Additional Resources

Last updated