Add changelog and docs for 6.0.0 release

CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 6.0.0
+
+* This release is a breaking release. This release slightly changes the API
+  responses. Though the changes should be backwards incompatible, we're now
+  explicitly returning all fields in returns, rather than not including
+  fields that have nil values in the json. Clients that expect fields to not
+  exist could be affected by this change. The offical python client has been
+  tested against these changes, but there's a number of unofficial libraries
+  that you will want to test, if you're using one of them.
+* DEPRECATION NOTICE: This will be the last confidant release that will support
+  python2.
+* DEPRECATION NOTICE: This will be the last confidant release that will support
+  blind credentials. If you're using blind credentials, we recommend switching
+  to standard credentials, and protecting access to them using the new access
+  control (ACL) support hooks to provide fine-grained access control.
+* Confidant is now python3 compatible, and tested against python 3.6, 3.7 and
+  3.8. If you see any python3 related issues, please open an issue.
+* Confidant now includes an access control plugin framework, with a default
+  plugin, `confidant.authnz.rbac:default_acl`, which implements the existing
+  access control behavior of confidant. The `ACL_MODULE` setting can be used
+  to define your own ACL behavior; see the [ACL docs](https://lyft.github.io/confidant/advanced/acls/)
+  for information about how to apply fine-grained access controls to specific
+  resources and actions.
+* kmsauth was upgraded with a more efficient LRU implementation, which allows
+  for higher concurrency.
+* The frontend and backend have been refactored to only provide sensitive data
+  where necessary. For example, previously, when viewing a service, the
+  credentials for that service were included in the response. Now when the
+  frontend fetches a service, it only fetches credential metadata that it uses
+  for display purposes. Similarly, the history view no longer fetches or
+  displays sensitive information. These changes were made to support fine-grained
+  access controls.
+* The resources and history view list panels no longer combine resources in the
+  view, but include a resource type toggle, to make it easier to find resources.
+* The history backend endpoints that list resources now support paged results.
+  Future releases will expand this to all endpoints that list resources. Default
+  behavior for these endpoints is to not page results. Clients can limit the
+  page size via an argument. It's also possible to force paging for these
+  via the `HISTORY_PAGE_LIMIT` setting.
+* New backend endpoints have been added to support reverting credential and
+  service resources, rather than needing to do an edit of resources, with all
+  fields. This was in support of adding fine-grained access controls, but also
+  makes reverting resources trivial from the client side.
+* `GET /v1/services/<id>` now supports a `metadata_only=[True|False]` argument
+  which can be used to only include metadata in the response.
+* Permissions hints are included in the response of resource endpoints, to
+  allow the UI (and other clients) to adjust their behavior based on permissions
+  available.
+* More detailed audit logs have been added for user actions, such as get/update credential,
+  and get/update service.
+* Google OAuth support has been updated to work with the new Google Sign-In APIs,
+  rather than the older Google+ Sign-In APIs.
+
 ## 5.2.0
 
 * Python3 fix in function ``load_private_key_pem`` in ``confidant.lib.cryptolib``

docs/root/acls.md

@@ -0,0 +1,210 @@
+# Access Controls (ACLs)
+
+## Design
+
+The design for managing fine-grained ACLs in confidant is relatively simple. Hookpoints are called whenever a resource type will be accessed by an end-user; these hookpoints look like:
+
+```python
+check = acl_module_check(
+    resource_type='credential',
+    action='metadata',
+    resource_id=id,
+)
+if not check:
+    ...
+```
+
+Some hookpoints include extra information, via kwargs:
+
+```python
+check = acl_module_check(
+    resource_type='service',
+    action='update',
+    resource_id=id,
+    kwargs={
+        'credential_ids': combined_cred_ids,
+    },
+)
+if not check:
+    ...
+```
+
+These hookpoints all call back to the same function, which by default is:
+
+```python
+def default_acl(*args, **kwargs):
+    """ Default ACLs for confidant: always return true for users, but enforce
+    ACLs for services, restricting access to:
+    * resource_type: service
+      actions: metadata, get
+    """
+    resource_type = kwargs.get('resource_type')
+    action = kwargs.get('action')
+    resource_id = kwargs.get('resource_id')
+    # Some ACL checks also pass extra args in via kwargs, which we would
+    # access via:
+    #    resource_kwargs = kwargs.get('kwargs')
+    if authnz.user_is_user_type('user'):
+        return True
+    elif authnz.user_is_user_type('service'):
+        if resource_type == 'service' and action in ['metadata', 'get']:
+            # Does the resource ID match the authenticated username?
+            if authnz.user_is_service(resource_id):
+                return True
+        # We currently only allow services to access service get/metadata
+        return False
+    else:
+        # This should never happen, but paranoia wins out
+        return False
+```
+
+This function is defined by the `ACL_MODULE` setting, which by default is `confidant.authnz.rbac:default_acl`. The format is `python.path.to.module:function_in_module`. You can use this to implement an ACL approach that integrates with your own enviroment, or adjusts confidant's behavior to your needs.
+
+When implementing a new ACL module, remember that there's two types of users: `user` and `service`. By default `service` users are through kmsauth, whereas `user` users can come through kmsauth, or through one of the other forms of auth intended for the UI. You need to implement ACLs for both user types. Additionally, you should likely default your return to False, unless you're intending to only restrict features.
+
+## ACL Hookpoints
+
+The following hookpoints are currently available:
+
+### Credentials
+
+#### List credentials
+
+```python
+acl_module_check(resource_type='credential', action='list')
+```
+
+This check controls access to lists of credential metadata.
+
+#### Get credential metadata
+
+```python
+acl_module_check(
+    resource_type='credential',
+    action='metadata',
+    resource_id=id,
+)
+```
+
+This check controls access to specific credential metadata, which does not include credential pairs. Fine-grained controls can be applied using the provided `resource_id`.
+
+#### Get credential
+
+```python
+acl_module_check(
+    resource_type='credential',
+    action='get',
+    resource_id=id,
+)
+```
+
+This check controls access to specific credentials, which includes credential pairs. Fine-grained controls can be applied using the provided `resource_id`.
+
+#### Create credential
+
+```python
+acl_module_check(
+    resource_type='credential',
+    action='create',
+)
+```
+
+This check controls create access to credentials. This is a global permission, so no fine-grained ID is provided.
+
+#### Update credential
+
+```python
+acl_module_check(
+    resource_type='credential',
+    action='update',
+    resource_id=id,
+)
+```
+
+This check controls update access to specific credentials. Fine-grained controls can be applied using the provided `resource_id`. Note that if you're controlling access to this, you probably also want to control access to [Revert credential](#revert-credential).
+
+#### Revert credential
+
+```python
+acl_module_check(
+    resource_type='credential',
+    action='revert',
+    resource_id=id,
+)
+```
+
+This check controls revert access to specific credentials. Fine-grained controls can be applied using the provided `resource_id`. Note that if you're controlling access to this, you probably also want to control access to [Update credential](#update-credential).
+
+This action does not require access to view or edit credential pairs, so it can be used to allow folks to rollback changes to resources without access to view/edit them.
+
+### Services
+
+#### List services
+
+```python
+acl_module_check(resource_type='service', action='list')
+```
+
+This check controls access to lists of service metadata.
+
+#### Get service metadata
+
+```python
+acl_module_check(
+    resource_type='service',
+    action='metadata',
+    resource_id=id,
+)
+```
+
+This check controls access to specific service metadata, which includes service data, and credential metadata, for credentials that are mapped to the service, but does not include credential pairs in the credentials. Fine-grained controls can be applied using the provided `resource_id`.
+
+#### Get service
+
+```python
+acl_module_check(
+    resource_type='service',
+    action='get',
+    resource_id=id,
+)
+```
+
+This check controls access to specific service data, which includes service data, and credential that are mapped to the service, including credential pairs in the credentials. Fine-grained controls can be applied using the provided `resource_id`.
+
+#### Create service
+
+```python
+acl_module_check(
+    resource_type='service',
+    action='create',
+    resource_id=id,
+)
+```
+
+This check controls create access to specific services. Fine-grained controls can be applied using the provided `resource_id`.
+
+#### Update service
+
+```python
+acl_module_check(
+    resource_type='service',
+    action='update',
+    resource_id=id,
+)
+```
+
+This check controls update access to specific services. Fine-grained controls can be applied using the provided `resource_id`. Note that if you're controlling access to this, you probably also want to control access to [Revert service](#revert-service).
+
+#### Revert service
+
+```python
+acl_module_check(
+    resource_type='service',
+    action='revert',
+    resource_id=id,
+)
+```
+
+This check controls revert access to specific services. Fine-grained controls can be applied using the provided `resource_id`. Note that if you're controlling access to this, you probably also want to control access to [Update service](#update-service).
+
+This action does not require access to view or update services, so it can be used to allow folks to rollback changes to resources without access to view/update them.

docs/root/contents.rst

@@ -13,6 +13,7 @@ Confidant
 .. toctree::
   :caption: Advanced
 
+  acls
   blind_secrets
   kms_auth
   threat_model