Credential Based Authorization

Background

The initial version of Cherrytwist platform used centralized groups for managing roles, which then determined what access and actions could be carried out.

All roles at the moment are global roles, which means that a user either has the role or not. There is no notion of a user having a particular role within a given context e.g. Challenge Admin. This will be needed for any production version of the platform with many Challenges.

The medium term goal is to move to using full SSI with Verified Credentials. However as an intermediate step the platform is moving to using simple Credentials, so not cryptographically secure. This works as the platform is still centralized but it is important to switch already to Credential based authorization now so that the path to using decentralized authorisation is clear moving forward.

Terminology

The terminology in this section borrows heavily from the CBAS material detailed out below. This is to both learn from the experience within the wider SSI field, as well as to make the subsequent move to using Verified Credentials easier.

Terms:

• Resource: the Entity to which access is being delegated
• Privilege: A particular type of access that is being granted (e.g. addMember, update, read, delete etc)
• Role: an aggregate of a particular set of Privileges.
  • Question: could it be that this is simply an input and that the role + the context + business rules determine the privileges granted?
• Subject: the actor to whom access is being delegaged.
• Credential: holds the details of what role / privileges for Resources have been assigned to a Subject
• Trust Framework: a definition of privileges and how access is delegated in the system

Phrasing it differently: The resource to which a given actor is being granted a privilege is identified as the subject in the grant call.

Note: For now the Subject is implicit in Cherrytwist by virtue of the Credential being held by a User. For Verified Credentials this needs to be part of the cyrptographically secured credential.

Phasing

Now:

• Switch to Credentials for Authorization: Remove usage of Groups for global authorization
• Extend to Context Aware Authorization: Add support for context aware authorization, and expand to usage in Lifecycle triggered actions

Note by context aware authorization is meant that the authorization can check the actual instance of a particular entity e.g. challenge-7 vs Challenge, neil-smyth vs User.

Later:

• Trust Framework: declaratively specify the trust framework, with defined privileges, roles etc similar to what is done in the Simple Grant Language. The Trust Framework would then be used at runtime to evaluate authorization.
• Customizable Trust Frameworks: Allow different contexts to have the different Trust frameworks.

Implementation

Phase 1 - Global Credentials; Initial context guards

Server

Add support for Credentials being held by Users:

• Add a Credential entity to the domain model
• Add an Agent entity to the domain model that holds + manages Credentials
• Extend the User entity to have a single Agent

Note: the implementation of Credentials is generic, and not tied to Authorization i.e. other Credential types could easily also be stored in the same mechanism.

Expand Authorization to use AuthorizationCredentials

• New AuthorizationService that takes care of
  • Assigning and removing AuthorizationCredentials from Users
  • Retrieving all Users that hold a particular AuthorizationCredential
• New AuthorizationRules guard that can work with Credentials as for granting / refusing access
  • This replaces the usage of UserGroups
  • Essentially this is an array of checks that is executed to see if the User is authorized
• New Decorator for specifying what Global roles are allowed
• New AuthorizationRule implementations for
  • Checking if a user holds a Credential for a global role
  • Checking if the access is allowed in the context of self-management

Authorization definitions and assignment:

• Global Roles:
  • global-admin: able to assign global-community-admin && global-challenge-admin credentials; able to do everything.
  • global-registered: for if we allow other types of access later
  • global-community-admin: albl to create users, groups; able to assign users to groups, update organisations
  • global-challenge-admin: able to add create Ecoverse's / challenges / opportunities

Functionality updates:

• Bootstrap to assign Credentials to newly created users
  • Replacing usage of UserGroups for ecoverse-admin, global-admin etc.
• Creating a new user autotmatically assigns the new user the credential global-registered
• Authorization api
  • Add new query to get all users that match a credential search input
  • Expand AuthorizationService to support querying all users with a given Authorizationredential
• Credentials instead of Restricted UserGroup names
  • Replace usage of members UserGroup by checking for users with a credential for a given community
  • Remove usage of restricted groups on Community, Organisation.
  • Also remove supporting functions that were on UserGroup service.
• Context dependendent authorization
  • New authorization rule to check for community membership
• Dropped focal point from UserGroup? Never been used
• Remove memberOf as can now use credentials instead of group memberships
• Dropped UpdateReference / UpdateTagset mutations as they should only be called in the context of a higher level update.

Phase 2 - Expand Context Dependent Authorization

Extend functionality to support the issuing and usage of context credentials i.e. a credential that is tied to a particular resource(s).

Givens

Distinguish between the granting of a Credential, and validating

Granting:

Specifies the resource to which access is being delegated.

• Assigns a credential to an Agent to represent the access being granted

Validating

Validating is the action checking whether a particular action is authorized. It has the following parts:

• Agent: The Agent carrying out the action has credentials that determine if it has sufficient privileges to be able to carry out that action
  • The Agent is available via the User that is authenticated i.e. it comes from the request / event that the server is responding to
  • Note: the credentials are on the Agent so that other entities such as Challenges / Organisations can also carry out actions.
• Target: The context is the particular entity upon which a command (action) is being carried out.
  • In particular the fact that the actual entity being acted on is not guaranteed to available to guards on the GraphQL implies that doing authorization via guards on the Graphql api is not sufficient.
  • For global roles this was not an issue hence graphql guards were sufficent.
  • However for context aware authorization (e.g. an agent can update a particular ecoverse) then using graphql guards is not sufficient.
    • Note: context aware authorization also works well with the actor model in general, which is expected to be expanded on near term.
• Rules: The authorization rules that are determine which privileges are granted in a particular context.
  • Importantly the set of Rules is fairly fixed, at least for now.
    • Later there may need to be some flexibility / make the rules data dependent.
  • The set of rules are picked up from the Target that is being acted upn.

Server

The key design elements are:

• All entities to have an authorizationRules field, that stores a JSON string description of the authorization rules for that entity
• Authorization service extended to have the following function:
  • grantAccessOrFail(agent: IAgent, authorizationRules: string, privilege: Privilege, msg: string): Promise<Boolean>
    • agent: the holder of credentials that is carrying out the action
    • authorizationRules: the JSON representation of what actions are allowed on the entity
    • privilege: the type of action being carried out: create, read, update, delete
    • msg: a helper string that will be returned as part of the ForbiddenException if access is not granted.

Key is that the rules are fairly static, and they are assigned to an entity at the time that it is created. A worked example:

• A Community entity is created as part of creating a Challenge
• The Community entity receives a rule that states that an agent with a credential matching (ecoverse-admin, ecoverse-uuid) can have the privileges "create, read, update, delete".
• When a UserGroup is created on the Community that entity receives a copy of the rules from the Community
  Thus ensuring that an Ecoverse-admin for that Ecoverse is able to update all aspects of the Community and its containing entities.

A sample authorization rules:
cerdentialRules: [
{
type: ecoverse-admin,
resourceID: '1234',
authorizations: ['read', 'update'],
},
{
type: global-admin,
resourceID: '',
authorizations: ['create', 'read', 'update', 'delete'],
}
]

Contextual AuthorizationCredentials

The following context credentials are initially supported:

• ecoverse-admin
• ecoverse-member
• challenge-admin
• challenge-member
• user-update: grants a user the privilege to be able to update their own profile

Authorization Logic update

The key change is that all guard based authorization logic will be replaced by calls within the Services.

Phase 3: Leverage a claims framework

It is likely that there will need to be additional flexibility later regarding the authorization rules that are supported by the platform. The rules introduced in phase 2 are fairly rigid and custom - so later would like to move to leverage a claims authorisation package.

One such candidate is CASL, which is also supported by NestJS.

Reference

NestJS / Passport

• UseGuards decorator, from NestJS framework, injects a guard around a class or method.
  • Pass in the guard implementation to use
  • A new instance is created for each time it occurs on the execution path
• Our implementation, GqlGuard, is derived from the PassportGuard
  • Actually it does not have any real GraphQL knowledge in there
  • Usable for simple method authorization?
• If put mutliple guards then they are an 'And', but inside a Guard the logic is flexible

Material

• Machine Readable Governance Frameworks
• Simple Grant Language (SGL)
• Capability Based Access System (CBAS)
• Trust Framework RFC

CBAS docs

Components, provisional API definition:

The CBAS component will allow the developer to easily create and consume Verifiable Credentials granting authority to perform specific actions on resources (guided by grant and delegation rules described in a corresponding Trust Framework document). The CBAS component will allow developers to specify if the permissions they issue can be delegated further, as well as specify additional constraint objects which will be evaluated when the capability is verified.

Please note that while the functionality supported by CBAS is not intended to change, the described API is provisional, and might be modified as development furthers and based on new learnings (both from the attempted use cases, as well as from communication with partners).

The following subsections describe the functions exposed by the CBAS module, detailing the expected inputs / outputs, and dependencies (in terms of other ESSIF Lab functional components, or other specifications)

Granting Authorization

Given a resource trust framework document, CBAS offers an API to enable developers to create Verifiable Credentials delegating authority / permissions:

  const cbas = new CBAS({
    trustFramework,
    createVC,
    verifyVC,
    createVP,
    verifyVP
  })

  const capability = await cbas.issueCapability({
      "type": "UBS-backup",
      "backupID": "aaabbbccc",
      "vaultID": "bbbcccfff",
      "locations": ["https://ubs.jolocom.io"]
    },
    {
      authorizations: ["read", "write"]
      // Constraints are currently not evaluated by the CBAS module.
      constraints: [{
        dailyUploadLimit: "1024MB",
      }],
    },
    'did:example:alice', 
  )

Inputs:

• resourceDescription - a JSON object describing the resource to which access is being delegated. The resource description is embedded in the issued credential.
• delegationOptions - a JSON object containing the following fields:
  • authorizations - a JSON array listing delegated authorizations. The listed permissions can be the same, or more restricted, than the ones held by the delegator. The permissions should either match privileges defined in the governance framework document, or be mentioned in rules.
  • constraints - a object encoding additional constraints to be included in the capability during delegation. These constraints must be defined in the corresponding governance framework document.
• subject - the DID of the intended subject / holder.

Output:

• A Signed Verifiable Credential delegating did:example:alice the authorization to "read", "write" the described resource.

This credential can be presented when accessing the protected resource, as well as used as a base for further attenuated authorization delegations.

This method requires a createVC implementation to be configured on the cbas instance.

Evaluating capabilities

A CBAS instance configured with a governance framework document can be used to verify capabilities and return associated privileges as follows:

await cbas.evaluateCapability(capability)

const expectedReturnValue = {
  resource: {
    "type": "UBS-backup",
    "backupID": "aaabbbccc",
    "vaultID": "bbbcccfff",
    "locations": ["https://ubs.jolocom.io"]
  },
  privileges: ['update-backup', 'delete-backup', 'read-backup'],
  issuer: 'did:example:ubsServer',
  subject: 'did:example:ubsUser',
  constraints: [{
    dailyUploadLimit: "1024MB",
  }]
}

Inputs:

• capability - a Verifiable Credential to be evaluated against the rules defined in the governance framework document.

In case the verification succeeded, a JSON object containing the following properties is returned:

• resource - the resource description embedded in the credential
• privileges - a JSON array of privileges for which at least one of the associated grant rules (defined in the governance framework document) passed validation
• issuer and subject
• constraints - a JSON array encoding additional constraints associated with the capability

If the evaluation result lists the required privilege, access to the resource described in the capability can be granted.
Evaluating constraints is currently delegated to the application developer.

This method requires a verifyVC implementation to be configured on the cbas instance.

Creating an invocation

When a capability needs to be used in a request, a signed Verifiable Presentation of the corresponding Verifiable Credential must be created. This can be achieved as follows:

const invocation = await cbas.invokeCapability(capability)

Returns a signed Verifiable Presentation in JSON form. The invocation can be included with the request in various ways depending on the use case (e.g. via HTTP signatures, or via a DIDComm based protocol).

This method requires a createVP and createVC implementation to be configured on the cbas instance.

Evaluating an invocation

A CBAS instance configured with a governance framework document can be used to verify capability invocations and return associated privileges. This function delegates to evaluateCapability after performing the required validation on the Verifiable Presentation.

await cbas.evaluateInvocation(invocation)

const expectedReturnValue = {
  resource: {
    "type": "UBS-backup",
    "backupID": "aaabbbccc",
    "vaultID": "bbbcccfff",
    "locations": ["https://ubs.jolocom.io"]
  },
  privileges: ['update-backup', 'delete-backup', 'read-backup'],
  issuer: 'did:example:ubsServer',
  subject: 'did:example:ubsUser',
  constraints: [{
    dailyUploadLimit: "1024MB",
  }]
}

The return value is the same as when calling cbas.evaluateCapability.

This method requires a verifyVC and verifyVP implementation to be configured on the cbas instance.

Delegating a capability

Given a capability, the CBAS module allows the developers to further delegate the associated authorizations to other agents. Additional constraints can be added during the delegation process.

// Provisional API,
// CBAS is exposed through the SSI Protocols and Crypto layer

const delegatedCapability = CBAS.delegateCapability(rootCapability, {
authorizations: ["read", "write"]
constraints: [{
  "startTime": "2020-05-20T14:00Z",
  "endTime": "2020-06-20T14:00Z",
}],
}, 'did:example:bob')

The inputs are:

• parentCapability - a Verifiable Credential which describes a capability. The parentCapability must include the authorization to delegate.
• An object with delegation options, these include:
  • The delegated authorizations (must be the same, or restricted compared to the authorizations on the root capability)
  • Additional constraints which will be added to the existing constraints defined on the delegation chain. At each delegation step new constraints may be added, and can not be removed through delegation. When the Verifiable Credential is being verified (e.g. as part of a request to a protected resource), the constraints must be validated in the context of the request. Outside of a set of commonly useful predicates, constraints are expected to be application / use case specific, and can be described in the corresponding machine-readable Trust Framework document.

Output:

• A Signed Verifiable Credential delegating did:example:bob the authorization to "read" and "write" from / to the described resource location. The returned credential references the capability from which it was derived via the delegationProofSection, as described in the [data model] section.

Data interface specification of the CBAS component

===============================================

Trust Framework Document

In order to define the authorization policies relevant for the CBAS component, a collection of authorization rules describing the various privileges (as well as rules associated with granting and delegating them) is required / defined. The document is expected to list a number of SGL statements.

The aforementioned rules can be embedded in issued capabilities directly, as well as advertised publicly. For this purpose, a machine-readable ARIES Governance Framework document (Trust Framework RFC, machine-readable Governance Framework ) can be employed (this is also mandated by the Chained Credentials. Although the standardization / definition efforts are in early stages, the current example structure can suit the needs of the CBAS component.

A provisional version of a machine-readable document listing the privileges, and the associated granting rules, can look as follows:

{
   "@context": [
     "https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0430-machine-readable-governance-frameworks/context.jsonld", 
     "https://ubs.org/access-trust-fw"
   ],
   "name": "Universal Backup Service Resource Control"
   "version": "1.0",
   "logo": "http://ubs.org/logo.png",
   "description": "Governs access control for a Backup Service",
   "docs_uri": "http://ubs.org/access-trust-fw/v1",
   "data_uri": "http://ubs.org/access-trust-fw/v1/tf.json",
   "topics": ["utility", "backup"],
   "roles":["ubs-user", "ubs-operator"],
   "privileges":[
      {
         "name":"create-vault",
         "uri":""
      },
      {
         "name":"read-vault-config",
         "uri":""
      },
      // ... skipped for brevity
      {
         "name":"delete-backup",
         "uri":""
      }
   ],
   "rules":[
      {
        "grant":["create-vault"],
         "when":
         {
            "all":[
               {"resource.type":"vault-management-api"},
               {"permissions.authorizations":"write"},
               {"resource.locations":"http://localhost:8080/"}
            ]
         }
      },
      {
         "grant":[
            "query-vault"
         ],
         "when":{
            "all":[
               {"resource.type":"vault-management-api"},
               {"permissions.authorizations":"read"},
               {"resource.locations":"http://localhost:8080/"}
            ]
         }
      },
      // ... skipped for brevity
      {
         "grant":[
            "read-backup"
         ],
         "when":{
            "all":[
               {"resource.type":"UBS-backup"},
               {"permissions.authorizations":"read"},
               {"resource.locations":"http://localhost:8080/"}
            ]
         }
      }
   ]
}

The CBAS component will most likely impose some restrictions on the supported structures of listed SGL statements in order to simplify the APIs and implementation efforts.

The exact semantics for describing privileges and associated rules are not final.

Verifiable Credential Data Model

We intend to use the Verifiable Credentials (VC) specification as a foundation for expressing object capabilities. By doing so, we hope to be able to reuse existing tooling (e.g. libraries for creating / consuming Verifiable Credentials) and infrastructure (e.g. the Universal Issuer / Verifier, Credential schema / metadata registries, revocation registries, backup services, etc.). We also hope to benefit from previous / ongoing / future interoperability efforts in the Verifiable Credential area.

For the initial implementation of the CBAS module, we intend to support the JSON-LD representation of Verifiable Credentials (example), as well
as JSON-LD Verifiable Presentations (example) for expressing (potentially delegated) object capabilities. At later stages of development, alternative Verifiable Credential formats (e.g. Zero Knowledge based implementations) as well as alternative Verifiable Presentation variants can be integrated.

CBAS imposes additional requirements on the Verifiable Credential structure (mandated by specifications it builds upon) in order to model authorizations, constraints, and delegation of authority.

Granting permissions using VCs

The CBAS module relies on Verifiable Credentials to encode permissions and permissions / capabilities. Permissions are expressed in the credentialSubject field in the Credential, structured similar to the one described in the Chained Credentials ARIES RFC.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "claim:rootCapability",
  "type": ["VerifiableCredential", "Proxy.D/ExampleBackupTF"],
  "issuer": "did:example:backup_service_operator",
  "issuanceDate": "2020-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:backup_service_user"
    "permissions": {
      "constraints": [],
      "authorizations": ['create-backup', 'query-backups']
    },
    "resource": {
      "type": "UBS-backup-management-api",
      "vaultID": "aaabbbccc",
      "backupID": "cccdddfff",
      "locations": ["https://ubs.jolocom.io"]
    }
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:example:backup_service_operator#keys-1",
    "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
      sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
      X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
      PAYuNzVBAh4vGHSrQyHUdBBPM"
  }
}

The contents of the credential are:

• permission - lists privileges granted to the holder as well as associated constraints.
• resource - field is used to associate information with the resource to which access is being granted. This information can aid the client in initiating interactions / presenting capabilities.

Delegation

As outlined in the Chained Credentials Aries RFC, obeying a number of special conventions (e.g. including a "provenance proof") above the core requirements of an ordinary Verifiable Credential can be used to model delegation (potentially constrained) of authority.

Below is an example of a delegated capability derived from the Verifiable Credential created in a previous example:

{{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "claim:delegatedCredential",
  "provenanceProofs": {
    [["authorization"], {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
      ],
      "type": "VerifiablePresentation",
      "verifiableCredential": [{
        // Parent Verifiable Credential
      }],
    }]
  },
  "type": ["VerifiableCredential", "AlumniCredential"],
  "issuer": "https://example.edu/issuers/565049",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
  // Clipped for brevity
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "https://example.edu/issuers/keys/1",
    "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
      sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
      X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
      PAYuNzVBAh4vGHSrQyHUdBBPM"
  }
}

The provenanceProofs property of the Verifiable Credential includes a Verifiable Presentation of the Verifiable Credential created in a previous example. The presentation serves as a base / root for the derived capability.

Besides linking the derived credential to the root credential, a number of extra properties can be modified during delegation, specifically in the form of adding constraints:

A capability VC may include one or more constraint objects, which describe additional restrictions which must be considered when evaluating the Verifiable Credential.

  "credentialSubject": {
    "permissions": {
      "constraints": {
        "startTime": "2020-05-20T14:00Z",
        "endTime": "2020-06-20T14:00Z",
      }
    }
  }

Functional specification of the CBAS component

===========================================

Outline

The CBAS component will allow the developer to easily create and consume Verifiable Credentials granting authority to perform specific actions on resources (guided by grant and delegation rules described in a corresponding Trust Framework document). The CBAS component will allow developers to specify if the permissions they issue can be delegated further, as well as specify additional constraint objects which will be evaluated when the capability is invoked.

The following sections will describe the core functions exposed by the CBAS module.

Please note that the API is provisional

Trust Framework document(Resource description)

The CBAS module allows the developers to leverage their existing Verifiable Credential implementations (including existing credential exchange protocols for issuing and requesting capabilities).

In order to simplify issuance / verification of credentials encoding various access rights for developers, the definition of authorization policies relevant for the CBAS user, a configuration / definition document describing the offered resources / services, as well as the associated authorization policies is required.

For this purpose, we intend to use a ARIES Trusft Framework document (specifically the Machine Readable variant)[LINK1, LINK2].

The CBAS component will allow developers to make use of Trust Framework documents they define to easily grant (potentially delegatable) Verifiable Credentials encoding permissions to perform certain actions outlined in the Framework document. The CBAS component also offers developers a simple way to evaluate presented Verifiable Credentials in the context of a Trust Framework document and get a list of allowed actions on resources.

Developers should be free to define custom authorization policies as they see fit to satisfy diverse use cases of varying complexity.

Granting Authorizations

The CBAS component can make use of an underlying Verifiable Credential implementation (i.e. module or service for capable of issuing and verifying VCs) and an associated Trust Framework document to aid / simplify the issuance of object capabilities encoded as Verifiable Credentials.

The CBAS component will allow the developer to easily create Verifiable Credentials granting authorizations to perform specific actions on resources (guided by the listed grants and delegation rules encoded in a Trust Framework document).

The CBAS component will also allow developers to specify if the permissions they issue can be delegated further (given this is allowed by the Trust Framework / original authorizations set), as well as specify additional constraint objects (attenuations) which will be evaluated when the capability is presented.

The developer will be able to use their preferred Verifiable Credential issuance protocol (e.g. ARIES RFC 0036) to issue the delegated capabilities to the delegatee.

The developer will be able to use existing / integrated Verifiable Credential revocation mechanisms to revoke delegated authorizations (as well as all Verifiable Credentials derived from it).

Evaluating Authorizations

Besides issuing delegated authorizations, the developer will frequently generate requests for Verifiable Presentations proving the counterparty is authorized to perform certain actions on a resource. The CBAS module aims to simplify this process by allowing the developer to easily generate queries for Verifiable Credentials (as defined by the underlying credential exchange protocol) based on defined authorizations. The resulting requests for credentials can be communicated to the counterparty attempting to access a prottected resource.

The CBAS module will also expose developer friendly APIs to determine what actions are permitted / if a particular action is permitted given a Verifiable Credential (presented by the counterparty) and a Trust Framework document.

The evaluation process consists of first ensuring all presented Verifiable Credentials have been correctly signed, and are not mallformed. This step can be delegated to an underlying Verifiable Credential module.

CBAS must ensure that delegation happened correctly (i.e. constraints were only added, all delegations were authorized, no authorizations were added, etc.). Lastly, the presented capability can be evaluated against the policies / rules embedded within / advertised via a machine readable Trust Framework document.

Capability Delegation, Attenuation, Revocation

In order to allow for more flexible and complex use cases, the capabilities issued by the CBAS library can be further delegated, by the subject / holder, to other agents (if the appropriate authorizations are allowed in the corresponding Trust Framework document).

As part of delegating authorization, the delegator can choose to restrict / modify the delegatee's resulting authorizations, e.g. via restricting the proxied permissions.

For instance, a developer holding a capability allowing them to "read", "write", and "delete" a resource can derive and delegate capabilities with restricted access (e.g. only granting the permission to "read") the resource to other agents / internal system components without having to share the original, more permissive, capability.

The developer should also be able to add additional constraints (outlined in the Trust Framework)[link] document to the Verifiable Credential during the delegation phase. These constraints can serve as additional restrictions which must be considered / verified when evaluating the Verifiable Credential

Lastly, traditional Verifiable Credential revocation approaches can be employed within this component as well, to hanlde revocation of capabilities.

Configuration / dependencies

The developer will be able to configure CBAS to use existing Verifiable Credential implementations (i.e. libraries for generating and consuming W3C Verifiable Credentials). This would allow developers to easily integrated with existing systems (without having to adopt a new Verifiable Credential format / representation), as well as select implementations catering to specific goals (e.g. privacy preserving ZKP based impelemtations, using JSON representation for VCs for smaller payload sizes and simpler signature verification / generation algorithms).

The CBAS component will be designed so that integration with remote VC issuance / verification services is supported as well (e.g. for simpler integration with existing ESSIF Lab software / functional componenets). to integrate the issuer and verifier functional components defined within the ESSIF Lab Functioanl architecture document to

Since capabilities generated by CBAS are Verifiable Credentials, the developers should be free to use their preferred credential exchange protocols and credential revocation mechanisms, which should offer the aforementioned advantages as well.

Prototype

In order to show how the CBAS module can be used in the context of an example use case, a set of tests were written and included in the repository. These tests showcase the currently supported API, and serve as a good example of how a developer would use the CBAS library to implement authorization for their use case. We are also currently integrating the CBAS module with the UBS server / client components. We hope that the resulting integration can serve as a more complete usage example.*

The following supporting data structures are defined to enable the test use case:

• A governance framework document describing a generic backup service. This document includes definitions for the privileges relevant to the use case and associated grant rules. These rules are used in the tests to evaluate capabilities.
• A set of objects describing resources relevant to the test use case. These represent access to API endpoints (in the case of "backup-management-api" and "vault-management-api") and specific resource (in case of "UBS-backup", "UBS-vault"). Access to these resources is granted during the tests.

We first show how an instance of the CBAS library can be used to issue capabilities authorizing the holder to perform some actions on certain resources.
The tests for getGrantsForCapability and canGrantPrivilege further show how the issued capability can be evaluated against a governance framework document (specifically the SGL statements in the rules section) to grant certain defined privileges. These useful helpers can aid the client in finding the appropriate capabilities for a request, and the server in evaluating / verifying received capabilities.

The rest of the tests focus on the evaluateCapability and evaluateInvocation functions, which can be used to verify the signature and expiry date on a capability / invocation, and evaluate it against the rules defined in the governance framework.

The tested API is further described in the "Interface Specification document"

We are currently focusing on the following areas of research / development for the next iteration of the CBAS module:

• Adding support for defining and processing constraints (as shown here) (which can be included in a credential during the issuance process or delegation) using a governance framework document.
• Further research on how delegation rules can be associated with privileges via a governance framework document. Combined with the ability to add constraints to credentials, this would allow for use cases where the client wants to share access to a resources stored on a backup server with other SSI agents (perhaps with additional restrictions / constraints).
• Align the VC / VP issuance interface required by the CBAS module with the Universal Wallet specification document.

We intend to explore some of these topics in more detail as part of upcoming interoperability sessions.

===========================

Examples

Amazon

CBAS