ATLAS-2463: documentation of Atlas authorization model

docs/src/site/twiki/Authentication-Authorization.twiki → docs/src/site/twiki/Atlas-Authentication.twiki

----++ Authentication & Authorization in Apache Atlas.
+---++ Authentication in Apache Atlas.
 
 ---+++ Authentication
 
@@ -111,56 +111,3 @@ atlas.authentication.method.ldap.user.searchfilter=(uid={0})
 atlas.authentication.method.ldap.default.role=ROLE_USER
 </verbatim>
 
----+++ Authorization
-
-
----++++ Atlas Authorization Methods [Simple/Ranger]
-To set authorization in atlas, update the =atlas.authorizer.impl= properties in =atlas-application.properties=
-   * *Simple*
-   * *Ranger*
-
-
-
-<verbatim>
-atlas.authorizer.impl=simple | ranger | <Qualified Authorizer Class Name>
-</verbatim>
-
----++++ Simple Authorizer.
-
-In Simple Authorizer the policy store file is configured locally. The path of policy store file is set in
-=atlas.auth.policy.file= property of =atlas-application.properties=
-
-<verbatim>
-atlas.auth.policy.file={{conf_dir}}/policy-store.txt
-</verbatim>
-
-The policy store file format is as follows:
-
-<verbatim>
-Policy_Name;;User_Name:Operations_Allowed;;Group_Name:Operations_Allowed;;Resource_Type:Resource_Name
-</verbatim>
-
-eg. of admin policy:
-<verbatim>
-adminPolicy;;admin:rwud;;ROLE_ADMIN:rwud;;type:*,entity:*,operation:*,taxonomy:*,term:*
-</verbatim>
-
-Note : The User_Name, Group_Name and Operations_Allowed are comma(,) separated lists.
-
-Authorizer Resource Types:
-   * Operation
-   * Type
-   * Entity
-   * Taxonomy
-   * Term
-   * Unknown
-
-
-Operations_Allowed are  r = read, w = write, u = update, d = delete
-
-
----++++ Ranger Authorizer.
-
-Ranger Authorizer is enabled by activating Atlas-Ranger plugin from Ambari.
-
-For more details visit the [[http://ranger.apache.org/][Apache-Ranger documentation]].

docs/src/site/twiki/Atlas-Authorization-Model.twiki

+
+
+---++ Atlas Authorization Model
+
+
+
+---+++  Introduction
+
+Atlas is a scalable and extensible set of core foundational governance services – enabling enterprises to effectively and
+efficiently meet their compliance requirements within Hadoop and allows integration with the whole enterprise data ecosystem.
+Apache Atlas provides open metadata management and governance capabilities for organizations to build a catalog of their
+data assets, classify and govern these assets and provide collaboration capabilities around these data assets for data
+scientists, analysts and the data governance team.
+
+This document covers details of the authorization model supported by Apache Atlas to control access to metadata managed by Atlas.
+
+---+++ Authorization of access to Types
+Apache Atlas provides a type system that allows users to model the metadata objects they would like to manage. The model
+is composed of definitions called ‘types’. Apache Atlas type system supports following categories of types:
+   * Entity
+   * Classification
+   * Relationship
+   * Struct
+   * Enum
+
+The authorization model enables control of which users, groups can perform the following operations on types, based on
+type names and type categories:
+   * create
+   * update
+   * delete
+
+Here are few examples of access controls supported by the model:
+   * Admin users can create/update/delete types of all categories
+   * Data stewards can create/update/delete classification types
+   * Healthcare data stewards can create/update/delete types having names start with “hc”
+
+
+---+++ Authorization of access to Entities
+An entity is an instance of an entity-type and such instances represent objects in the real world – for example a table
+in Hive, a HDFS file, a Kafka topic. The authorization model enables control of which users, groups can perform the
+following operations on entities – based on entity-types, entity-classifications, entity-id:
+
+   * read
+   * create
+   * update
+   * delete
+   * read classification
+   * add classification
+   * update classification
+   * remove classification
+
+Here are few examples of access controls supported by the model:
+   * Admin users can perform all entity operations on entities of all types
+   * Data stewards can perform all entity operations, except delete, on entities of all types
+   * Data quality admins can add/update/remove DATA_QUALITY classification
+   * Users in specific groups can read/update entities with PII classification or its sub-classification
+   * Finance users can read/update entities whose ID start with ‘finance’
+
+---+++  Authorization of Admin operations
+The authorization model enables control of which users, groups can perform the following administrative operations:
+   * import entities
+   * export entities
+
+Users with above accesses can import/export entities without requiring them to be granted with fine-grained entity level accesses.
+
+---+++ Pluggable Authorization
+Apache Atlas supports a pluggable authorization interface, as shown below, that enable alternate implementations to handle authorizations.
+
+The name of the class implementing the authorization interface can be registered with Apache Atlas using configuration =atlas.authorizer.impl=. When this property is not set, Apache Atlas will use its default implementation in =org.apache.atlas.authorize.simple.AtlasSimpleAuthorizer=.
+
+<verbatim>
+
+package org.apache.atlas.authorize;
+
+public interface AtlasAuthorizer {
+    void init();
+
+    void cleanUp();
+
+    boolean isAccessAllowed(AtlasAdminAccessRequest request) throws AtlasAuthorizationException;
+
+    boolean isAccessAllowed(AtlasEntityAccessRequest request) throws AtlasAuthorizationException;
+
+    boolean isAccessAllowed(AtlasTypeAccessRequest request) throws AtlasAuthorizationException;
+}
+</verbatim>
+
+---+++ Simple Authorizer
+
+Simple authorizer is the default authorizer implementation included in Apache Atlas. For details of setting up Apache Atlas
+to use simple authorizer, please see [[Atlas-Authorization-Simple-Authorizer][Setting up Atlas to use Simple Authorizer]]
+
+---+++ Ranger Authorizer
+
+To configure Apache Atlas to use authorization implementation provided by Apache Ranger, include the following property
+in application.properties config file:
+
+<verbatim>
+atlas.authorizer.impl=ranger
+</verbatim>
+
+Apache Ranger Authorizer requires configuration files to be setup, for example to specify Apache Ranger admin server URL,
+name of the service containing authorization policies, etc. For more details on this, please refer to Apache Ranger documentation.
+
+
+---+++  None authorizer
+In addition to the default authorizer, Apache Atlas includes an authorizer that permits all accesses to all users. This authorizer can be useful in test environments and unit tests. To use this authorizer, set the following configuration:
+<verbatim>
+atlas.authorizer.impl=NONE
+</verbatim>

docs/src/site/twiki/Atlas-Authorization-Simple-Authorizer.twiki

+---+++ Setting up Atlas to use Simple Authorizer
+
+As detailed in [[Atlas-Authorization-Model][Atlas Authorization Model]], Apache Atlas supports a pluggable authorization
+model. Simple authorizer is the default authorizer implementation included in Apache Atlas. Simple authorizer uses
+policies defined in a JSON file. This document provides details of steps to configure Apache Atlas to use the simple
+authorizer and details of the JSON file format containing authorization policies.
+
+
+---++++  Configure Apache Atlas
+
+To configure Apache Atlas to use simple authorizer, include the following properties in application.properties config file:
+
+<verbatim>
+atlas.authorizer.impl=simple
+atlas.authorizer.simple.authz.policy.file=/etc/atlas/conf/atlas-simple-authz-policy.json
+</verbatim>
+
+Please note that if the policy file location specified is not an absolute path, the file will be looked up in following paths:
+   * Apache Atlas configuration directory (specified by system property =atlas.conf=)
+   * Apache Atlas server's current directory
+   * CLASSPATH
+
+---++++  Policy file format
+
+Simple authorizer uses =roles= to group permissions, which can then be assigned to users and user-groups. Following examples
+would help to understand the details of the policy file format:
+
+---+++++  Roles
+Following policy file defines 3 roles:
+   * ROLE_ADMIN: has all permissions
+   * PROD_READ_ONLY: has access to read entities having qualifiedName ending with "@prod"
+   * TEST_ALL_ACCESS: has all access to entities having qualifiedName ending with "@test"
+
+Simple authorizer supports Java reg-ex to specify values for privilege/entity-type/entity-id/classification/typeName/typeCategory.
+
+<verbatim>
+{
+  "roles": {
+    "ROLE_ADMIN": {
+      "adminPermissions": [
+        {
+          "privileges": [ ".*" ]
+        }
+      ],
+
+      "entityPermissions": [
+        {
+          "privileges":      [ ".*" ],
+          "entityTypes":     [ ".*" ],
+          "entityIds":       [ ".*" ],
+          "classifications": [ ".*" ]
+        }
+      ],
+
+      "typePermissions": [
+        {
+          "privileges":     [ ".*" ],
+          "typeCategories": [ ".*" ],
+          "typeNames":      [ ".*" ]
+        }
+      ]
+    },
+
+    "PROD_READ_ONLY" : {
+      "entityPermissions": [
+        {
+          "privileges":      [ "entity-read", "entity-read-classification" ],
+          "entityTypes":     [ ".*" ],
+          "entityIds":       [ ".*@prod" ],
+          "classifications": [ ".*" ]
+        }
+    }
+
+    "TEST_ALL_ACCESS" : {
+      "entityPermissions": [
+        {
+          "privileges":      [ ".*" ],
+          "entityTypes":     [ ".*" ],
+          "entityIds":       [ ".*@test" ],
+          "classifications": [ ".*" ]
+        }
+    }
+  },
+
+  "userRoles": {
+   ...
+  },
+
+  "groupRoles": {
+   ...
+  }
+}
+
+</verbatim>
+
+---+++++  Assign Roles to Users and User Grips
+
+Roles defined above can be assigned (granted) to users as shown below:
+
+<verbatim>
+{
+  "roles": {
+   ...
+  },
+
+  "userRoles": {
+    "admin":   [ "ROLE_ADMIN" ],
+    "steward": [ "DATA_STEWARD" ],
+    "user1":   [ "PROD_READ_ONLY" ],
+    "user2":   [ "TEST_ALL_ACCESS" ],
+    "user3":   [ "PROD_READ_ONLY", "TEST_ALL_ACCESS" ],
+  },
+
+  "groupRoles": {
+   ...
+  }
+}
+</verbatim>
+
+Roles can be assigned (granted) to user-groups as shown below. An user can belong to multiple groups; roles assigned to
+all groups the user belongs to will be used to authorize the access.
+
+<verbatim>
+{
+  "roles": {
+   ...
+  },
+
+  "userRoles": {
+   ...
+  },
+
+  "groupRoles": {
+    "admins":        [ "ROLE_ADMIN" ],
+    "dataStewards":  [ "DATA_STEWARD" ],
+    "testUsers":     [ "TEST_ALL_ACCESS" ],
+    "prodReadUsers": [ "PROD_READ_ONLY" ]
+  }
+}
+</verbatim>
+

docs/src/site/twiki/index.twiki

@@ -55,7 +55,9 @@ capabilities around these data assets for data scientists, analysts and the data
    * [[Search - Basic][Search: Basic]]
    * [[Search - Advanced][Search: Advanced]]
    * [[security][Security]]
-   * [[Authentication-Authorization][Authentication and Authorization]]
+   * [[Atlas-Authentication][Authentication]]
+   * [[Atlas-Authorization-Model][Atlas Authorization Model]]
+      * [[Configure-simple-authorizer][Steps to configure Atlas Simple Authorizer]]
    * [[Configuration][Configuration]]
    * [[Notifications][Notifications]]
    * Hooks & Bridges