github.com/mmatczuk/gohan@v0.0.0-20170206152520-30e45d9bdb69/docs/policy.md (about)

     1  # Policy
     2  
     3  You can configure API access policy using this resource.
     4  A policy has following properties.
     5  
     6  - id : ID of the policy
     7  - principal : Keystone Role
     8  - action: one of `create`, `read`, `update`, `delete` for CRUD operations
     9    on the resource or any custom actions defined by schema performed on a
    10    resource or `*` for all actions
    11  - effect : Allow API access or not
    12  - resource : target resource
    13    you can specify target resource using "path" and "properties"
    14  - condition : additional condition (see below)
    15  - tenant_id : regexp matching the tenant, defaults to ``.*``
    16  
    17  ## Conditions
    18  
    19  Gohan supports several types of conditions
    20  
    21  - `is_owner` - Gohan will enforce access privileges for the resources specified in the policy. By default access to resources of all other tenants would be blocked.
    22  
    23  - belongs_to - Gohan will apply the policy if the user tries to access resources belonging to the tenant specified in condition (see the example below). The condition has no effect if the access privileges are not enforced by specifying the `is_owner` condition. The full condition looks like:
    24  
    25    - `action: (*|create|read|update|delete)`
    26       `tenant_id: 8bab8453-1bc9-45af-8c70-f83aa9b50453`
    27       `type: belongs_to`
    28  
    29  Example policy
    30  
    31  ``` yaml
    32    policies:
    33    - action: '*'
    34      effect: allow
    35      id: admin_statement
    36      principal: admin
    37      resource:
    38        path: .*
    39    - action: 'read'
    40      condition:
    41      - is_owner
    42      - type: belongs_to
    43        action: '*'
    44        tenant_id: 8bab8453-1bc9-45af-8c70-f83aa9b50453
    45      effect: allow
    46      id: member_statement
    47      principal: Member
    48      resource:
    49        path: /v2.0/network/[^/]+/?$
    50        properties:
    51        - id
    52        - description
    53        - name
    54    - action: '*'
    55      condition:
    56      - is_owner
    57      effect: allow
    58      id: member_statement2
    59      principal: Member
    60      resource:
    61        path: /v2.0/networks/?$
    62        properties:
    63        - id
    64        - description
    65        - name
    66    - action: 'reboot'
    67      condition:
    68      - is_owner
    69      effect: allow
    70      id: member_statement2
    71      principal: Member
    72      resource:
    73        path: /v2.0/server/?$
    74  ```
    75  
    76  -  type `property` - You can add a condition based on resource value.
    77  
    78    You can specify allowed values in a match.
    79    if it is a value, we check exact match.
    80    if it is a list, we check if the value is in the list
    81    if it is a dict, we check if we have a key for this value and, updated value matches it.
    82    Note that this is only valid for update action.
    83  
    84  ``` yaml
    85      policy:
    86        - action: 'read'
    87          condition:
    88          - type: property
    89            match:
    90              status:
    91                - ACTIVE
    92                - CREATE_IN_PROGRESS
    93                - UPDATE_IN_PROGRESS
    94                - DELETE_IN_PROGRESS
    95                - ERROR
    96          effect: allow
    97          id: member
    98          principal: Member
    99        - action: 'update'
   100          condition:
   101          - type: property
   102            match:
   103              status:
   104                ACTIVE:
   105                - UPDATE_IN_PROGRESS
   106                - ERROR
   107          effect: allow
   108          id: member
   109          principal: Member
   110        - action: 'reboot'
   111          condition:
   112          - type: property
   113            match:
   114              status: ACTIVE
   115          effect: allow
   116          id: member
   117          principal: Member
   118        - action: 'delete'
   119          condition:
   120          - type: property
   121            match:
   122              status:
   123              - ACTIVE
   124              - ERROR
   125          effect: allow
   126          id: member
   127          principal: Member
   128  ```
   129  
   130  ## Resource paths with no authorization (nobody resource paths)
   131  
   132  With a special type of policy one can define a resource path that do not require authorization.
   133  In this policy only 'id', 'principal' and 'resource.path' properties are used. Policy 'principal'
   134  is always set to 'Nobody'.
   135  
   136  ``` yaml
   137  policies:
   138  - id: no_auth_favicon
   139    principal: Nobody
   140    resource:
   141      path: /favicon.ico
   142  - id: no_auth_member_resources
   143    action: '*'
   144    principal: Nobody
   145    resource:
   146      path: /v0.1/member_resources*
   147  ```
   148  
   149  In the above example, the access to favicon is always granted and never requires an authorization.
   150  This feature is useful for web browsers and it is a good practice to set this policy.
   151  In the second policy, no-authorization access is granted to all member resources defined by a path wildcard.