docs/index.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4 .. _master_index:
   5
   6 AAF - Application Authorization Framework
   7 ==================================================
   8 .. image:: https://bestpractices.coreinfrastructure.org/projects/2303/badge
   9   :alt: CII Silver Badge
  10   :target: https://bestpractices.coreinfrastructure.org/projects/2303
  11
  12 .. The purpose of AAF (Application Authorization Framework) is to organize software authorizations so that applications, tools and services can match the access needed to perform job functions.
  13
  14 AAF is designed to cover Fine-Grained Authorization, meaning that the Authorizations provided are able to used an Application's detailed authorizations, such as whether a user may be on a particular page, or has access to a particular Pub-SUB topic controlled within the App.
  15
  16 This is a critical function for Cloud environments, as Services need to be able to be installed and running in a very short time, and should not be encumbered with local configurations of Users, Permissions and Passwords.
  17
  18 To be effective during a computer transaction, Security must not only be secure, but very fast. Given that each transaction must be checked and validated for Authorization and Authentication, it is critical that all elements on this path perform optimally.
  19
  20
  21 Sections
  22 ++++++++
  23
  24 .. toctree::
  25    :maxdepth: 1
  26    :glob:
  27
  28    sections/architecture/index
  29    sections/installation/index
  30    sections/configuration/index
  31    sections/development/index
  32    sections/AAF_in_a_Nutshell
  33    sections/logging
  34    sections/release-notes
  35
  36 Introduction
  37 ------------
  38 AAF acronym stands for Application Authorization Framework and initially it was focused on  “Authorization”, but now supports implementations for both Authentication and Authorization. AAF is a set of Client Libraries (CADI Framework) and RESTful Services that support multiple Authentication Protocols and Fine-Grained Authorization.
  39 The goal of AAF project is to provide consistent authentication, authorization and security to various ONAP components. AAF organizes software authorizations so that applications, tools and services can match the access needed to perform job functions. AAF is designed to cover Fine-Grained Authorization, meaning that the Authorizations provided are able to use an Application's detailed authorizations, such as whether a user may be on a particular page, or has access to a particular Pub-Sub topic controlled within the App. This is a critical function for Cloud environments, as Services need to be able to be installed and running in a very short time, and should not be encumbered with local configurations of Users, Permissions and Passwords. The sister framework CADI (Code Access Data Identity) allows Java Applications to utilize Identity Authentication methods as plugins. Certificate Manager delivers X509 certificates in support of 2 way x509 TLS.
  40
  41 AAF contains some elements of Role Based Authorization, but includes Attribute Based Authorization elements as well.
  42
  43 Entities within AAF
  44 -------------------
  45
  46 AAF is an IAM that organizes software authorizations so that applications, tools and services can match the access needed to perform job functions. AAF is more than a typical RBAC. There are Roles, to be sure, but the important Architectural Pattern includes separation of Roles and Permissions.
  47
  48 |image0|
  49
  50 .. |image0| image:: sections/architecture/images/aaf-permission-mapping.png
  51    :height: 200px
  52    :width: 500px
  53
  54 A permission is composed of the following attributes:
  55
  56 * Type: core name of the permission
  57 * Instance: the object that is being interacted
  58 * Action: What is happening with this object
  59
  60 All roles, permissions identities of a given module in ONAP is covered by a Namespace (e.g. roles, permission and identities for the APP-C modules of ONAP)
  61
  62 The permissions, having a 3 part definition, make AAF also like an ABAC (A=Attribute).
  63 Roles, Permissions are stored centrally, but segregated by Application (the proverbial Namespace). The Application Creates Permissions that match their code (for the question "Does User have Permission"). Permissions are granted to Roles, to which the User belongs. AAF is not a Policy Engine, where dynamically based Policies are validated against differing kinds of Data Stores. AAF (Application Authorization Framework) is focused on RealTime Authentication and Authorization.
  64
  65 Namespace
  66 ^^^^^^^^^
  67 A Namespace, in AAF, is the ensemble of Roles, Permissions and Identities. Namespaces are known by domain, example com.onap.dcae or com.onap.appc and they are hierarchically managed. A Namespace is assigned to an application and contains one or more roles and one or more permissions. By default, every namespace has an admin role
  68
  69 **People in Namespaces**
  70
  71 Tasks Owner (Responsible) must do:
  72
  73 * Owners receive by email a notification to Approve
  74 * Owners also receive notifications of time based activities
  75
  76    * Periodic Revalidation of Users in Roles in Namespace
  77    * Periodic Revalidation of Permission in Namespace to Roles
  78
  79 Admins may:
  80
  81 * Create/Delete/Modify Roles in Namespace
  82 * Add/Remove Users from Roles in Namespace
  83 * Create/Delete/Modify Permissions in Namespace
  84 * Grant/Ungrant Permissions in Namespace to any Role in the company (Cross Company Role Grants are possible, but require approvals from both sides).
  85
  86 Only Namespace Admins may manage Roles/Permissions within a Namespace. The Granting process is One-Way. The Namespace Admins must Grant given Permissions to Roles on request.
  87
  88
  89
  90
  91 Object Model
  92 ^^^^^^^^^^^^
  93
  94 |image1|
  95
  96 .. |image1| image:: sections/architecture/images/aaf-hl-object-model.png
  97    :height: 600px
  98    :width: 800px
  99
 100 Resource Owner in ONAP defines permissions:
 101
 102 * He defines and grants permission to roles
 103 * Get notified by a mail when an Identity with a Role asks to be granted a permission
 104
 105
 106
 107 Essential Components
 108 --------------------
 109 The core component to deliver this Enterprise Access is a RESTful service, with runtime instances registered in a Cloud Directory (DME2) and backed by a resilient Datastore (Cassandra as of release 1.3)
 110
 111 The Data is managed by RESTful API, with Admin functions supplemented by Character Based User interface and certain GUI elements.
 112
 113 CADI Framework
 114 ^^^^^^^^^^^^^^
 115
 116 CADI is a framework for providing Enterprise Class Authentication and Authorization with minimal configuration to Containers and Standalone Services
 117 It is in fact a library used by services to:
 118
 119 * Authenticate with one or more Authentication Protocols
 120 * Authorize in a FINE-GRAINED manner using AAF Components
 121
 122 AAF Components – RESTful Services
 123 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 124
 125 Service (primary) – All the Authorization information, it is accessible by provided Caching Clients and by specialized plugins:
 126
 127 * Locate – how to find ANY OR ALL AAF instances across any geographic distribution
 128 * OAuth 2.0 – new component providing Tokens and Introspection
 129 * GUI – Tool to view and manage Authorization Information, and create Credentials
 130 * Certman – Certificate Manger, create and renew X509 with Fine-Grained Identity
 131 * FS – File Server to provide access to distributable elements (like well known certs)
 132 * Hello - Test your client access (certs, OAuth 2.0, etc.)
 133
 134 Cassandra as global replicating Data Store
 135 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 136
 137
 138 How AAF works
 139 ---------------------
 140 To understand how AAF works, let's describe its workflow through a high level "three tiered web app" use case:
 141
 142 |image2|
 143
 144 .. |image2| image:: sections/architecture/images/aaf-use-case.png
 145    :height: 400px
 146    :width: 800px
 147
 148
 149 1. Browser client goes to GUI using for instance SSO plugin (or Basic Auth)
 150 2. App goes directly to a Service using x509 or Basic Auth (or other)
 151 3. CADI Filter coverts credential to “Principal”. If not in cache, AAF is contacted for Permissions protecting GUI with Service ID/Credential (MechID of App/Pass or X.509 Client Cert (preferred)).
 152 4. AAF does provide User/Password features, or can be delegated to other credential service via Plugin
 153 5. If information is not in Service Cache, AAF’s DB is contacted using AAF Service ID/Credential.
 154 6. Client App uses Permission Attributes delivered by AAF/AAF Cache for protecting sensitive data/functions (using J2EE method).
 155 7. If not in Cache, Client contacts App Service, using App ID/Credential.
 156 8. CADI Filter converts App ID/Credential to Principal. If not in cache, contacts with AAF (with App ID/Credential) for Permissions of Client.
 157 9. App protects data based on Client Permissions.
 158 10. Component contacts next layer using Service ID/Credential.
 159 11. If ID or Permissions of AppServer are not in Cache, contact AAF using AAF Security Plugin for Cassandra, which uses AAF Java Client.
 160 12. Cassandra protects Cluster/Keyspace/ColumnFamily w/Permissions.
 161
 162