Access Control Lists (ACL)¶
What is an Access Control List?¶
Note: This topic deals with access control and policies on a channel administration level. To learn about access control within a chaincode, check out our chaincode for developers tutorial.
Fabric uses access control lists (ACLs) to manage access to resources by associating a Policy with a resource. Fabric contains a number of default ACLs. In this document, we”ll talk about how they”re formatted and how the defaults can be overridden.
But before we can do that, it”s necessary to understand a little about resources and policies.
Resources¶
Users interact with Fabric by targeting a user chaincode, or an events stream source, or system chaincode that are called in the background. As such, these endpoints are considered «resources» on which access control should be exercised.
Application developers need to be aware of these resources and the default
policies associated with them. The complete list of these resources are found in
configtx.yaml
. You can look at a sample configtx.yaml
file here.
The resources named in configtx.yaml
is an exhaustive list of all internal resources
currently defined by Fabric. The loose convention adopted there is <component>/<resource>
.
So cscc/GetConfigBlock
is the resource for the GetConfigBlock
call in the CSCC
component.
Policies¶
Policies are fundamental to the way Fabric works because they allow the identity (or set of identities) associated with a request to be checked against the policy associated with the resource needed to fulfill the request. Endorsement policies are used to determine whether a transaction has been appropriately endorsed. The policies defined in the channel configuration are referenced as modification policies as well as for access control, and are defined in the channel configuration itself.
Policies can be structured in one of two ways: as Signature
policies or as an
ImplicitMeta
policy.
Signature
policies¶
These policies identify specific users who must sign in order for a policy to be satisfied. For example:
Policies:
MyPolicy:
Type: Signature
Rule: "OR('Org1.peer', 'Org2.peer')"
This policy construct can be interpreted as: the policy named MyPolicy
can
only be satisfied by the signature of an identity with role of «a peer from
Org1» or «a peer from Org2».
Signature policies support arbitrary combinations of AND
, OR
, and NOutOf
,
allowing the construction of extremely powerful rules like: «An admin of org A
and two other admins, or 11 of 20 org admins».
ImplicitMeta
policies¶
ImplicitMeta
policies aggregate the result of policies deeper in the
configuration hierarchy that are ultimately defined by Signature
policies. They
support default rules like «A majority of the organization admins». These policies
use a different but still very simple syntax as compared to Signature
policies:
<ALL|ANY|MAJORITY> <sub_policy>
.
For example: ANY
Readers
or MAJORITY
Admins
.
Note that in the default policy configuration Admins
have an operational role.
Policies that specify that only Admins — or some subset of Admins — have access
to a resource will tend to be for sensitive or operational aspects of the network
(such as instantiating chaincode on a channel). Writers
will tend to be able to
propose ledger updates, such as a transaction, but will not typically have
administrative permissions. Readers
have a passive role. They can access
information but do not have the permission to propose ledger updates nor do can
they perform administrative tasks. These default policies can be added to,
edited, or supplemented, for example by the new peer
and client
roles (if you
have NodeOU
support).
Here”s an example of an ImplicitMeta
policy structure:
Policies:
AnotherPolicy:
Type: ImplicitMeta
Rule: "MAJORITY Admins"
Here, the policy AnotherPolicy
can be satisfied by the MAJORITY
of Admins
,
where Admins
is eventually being specified by lower level Signature
policy.
Where is access control specified?¶
Access control defaults exist inside configtx.yaml
, the file that configtxgen
uses to build channel configurations.
Access control can be updated in one of two ways, either by editing configtx.yaml
itself, which will be used when creating new channel configurations, or by updating
access control in the channel configuration of an existing channel.
How ACLs are formatted in configtx.yaml
¶
ACLs are formatted as a key-value pair consisting of a resource function name followed by a string. To see what this looks like, reference this sample configtx.yaml file.
Two excerpts from this sample:
# ACL policy for invoking chaincodes on peer
peer/Propose: /Channel/Application/Writers
# ACL policy for sending block events
event/Block: /Channel/Application/Readers
These ACLs define that access to peer/Propose
and event/Block
resources
is restricted to identities satisfying the policy defined at the canonical path
/Channel/Application/Writers
and /Channel/Application/Readers
, respectively.
Updating ACL defaults in configtx.yaml
¶
In cases where it will be necessary to override ACL defaults when bootstrapping
a network, or to change the ACLs before a channel has been bootstrapped, the
best practice will be to update configtx.yaml
.
Let”s say you want to modify the peer/Propose
ACL default — which specifies
the policy for invoking chaincodes on a peer – from /Channel/Application/Writers
to a policy called MyPolicy
.
This is done by adding a policy called MyPolicy
(it could be called anything,
but for this example we”ll call it MyPolicy
). The policy is defined in the
Application.Policies
section inside configtx.yaml
and specifies a rule to be
checked to grant or deny access to a user. For this example, we”ll be creating a
Signature
policy identifying SampleOrg.admin
.
Policies: &ApplicationDefaultPolicies
Readers:
Type: ImplicitMeta
Rule: "ANY Readers"
Writers:
Type: ImplicitMeta
Rule: "ANY Writers"
Admins:
Type: ImplicitMeta
Rule: "MAJORITY Admins"
MyPolicy:
Type: Signature
Rule: "OR('SampleOrg.admin')"
Then, edit the Application: ACLs
section inside configtx.yaml
to change
peer/Propose
from this:
peer/Propose: /Channel/Application/Writers
To this:
peer/Propose: /Channel/Application/MyPolicy
Once these fields have been changed in configtx.yaml
, the configtxgen
tool
will use the policies and ACLs defined when creating a channel creation
transaction. When appropriately signed and submitted by one of the admins of the
consortium members, a new channel with the defined ACLs and policies is created.
Once MyPolicy
has been bootstrapped into the channel configuration, it can also
be referenced to override other ACL defaults. For example:
SampleSingleMSPChannel:
Consortium: SampleConsortium
Application:
<<: *ApplicationDefaults
ACLs:
<<: *ACLsDefault
event/Block: /Channel/Application/MyPolicy
This would restrict the ability to subscribe to block events to SampleOrg.admin
.
If channels have already been created that want to use this ACL, they”ll have to update their channel configurations one at a time using the following flow:
Updating ACL defaults in the channel config¶
If channels have already been created that want to use MyPolicy
to restrict
access to peer/Propose
— or if they want to create ACLs they don”t want
other channels to know about — they”ll have to update their channel
configurations one at a time through config update transactions.
Note: Channel configuration transactions are an involved process we won”t delve into here. If you want to read more about them check out our document on channel configuration updates and our «Adding an Org to a Channel» tutorial.
After pulling, translating, and stripping the configuration block of its metadata,
you would edit the configuration by adding MyPolicy
under Application: policies
,
where the Admins
, Writers
, and Readers
policies already live.
"MyPolicy": {
"mod_policy": "Admins",
"policy": {
"type": 1,
"value": {
"identities": [
{
"principal": {
"msp_identifier": "SampleOrg",
"role": "ADMIN"
},
"principal_classification": "ROLE"
}
],
"rule": {
"n_out_of": {
"n": 1,
"rules": [
{
"signed_by": 0
}
]
}
},
"version": 0
}
},
"version": "0"
},
Note in particular the msp_identifer
and role
here.
Then, in the ACLs section of the config, change the peer/Propose
ACL from
this:
"peer/Propose": {
"policy_ref": "/Channel/Application/Writers"
To this:
"peer/Propose": {
"policy_ref": "/Channel/Application/MyPolicy"
Note: If you do not have ACLs defined in your channel configuration, you will have to add the entire ACL structure.
Once the configuration has been updated, it will need to be submitted by the usual channel update process.
Satisfying an ACL that requires access to multiple resources¶
If a member makes a request that calls multiple system chaincodes, all of the ACLs for those system chaincodes must be satisfied.
For example, peer/Propose
refers to any proposal request on a channel. If the
particular proposal requires access to two system chaincodes that requires an
identity satisfying Writers
and one system chaincode that requires an identity
satisfying MyPolicy
, then the member submitting the proposal must have an identity
that evaluates to «true» for both Writers
and MyPolicy
.
In the default configuration, Writers
is a signature policy whose rule
is
SampleOrg.member
. In other words, «any member of my organization». MyPolicy
,
listed above, has a rule of SampleOrg.admin
, or «any admin of my organization».
To satisfy these ACLs, the member would have to be both an administrator and a
member of SampleOrg
. By default, all administrators are members (though not all
administrators are members), but it is possible to overwrite these policies to
whatever you want them to be. As a result, it”s important to keep track of these
policies to ensure that the ACLs for peer proposals are not impossible to satisfy
(unless that is the intention).