docs/sections/architecture/security.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
   5 Security Architecture
   6 =====================
   7 Communicating
   8 -------------
   9 When one compute process needs to communicate to another, it does so with networking.
  10
  11 The service side is always compute process, but the client can be of two types:
  12  * People (via browser, or perhaps command line tool)
  13  * Compute process talking to another computer process.
  14
  15 In larger systems, it is a typical to have just one connection, but will the call initiated by the initial actor will cause additional calls after it.  Thus, we demonstrate both a client call, and a subsequent call in the following:
  16
  17 Thus, the essential building blocks of any networked system is made up of a caller and any subsquent calls.
  18
  19 .. image:: images/SecurityArchBasic_1.svg
  20         :width: 70%
  21         :align: center
  22
  23
  24 Communicating *Securely*
  25 ------------------------
  26 Whenever two processing entities exist that need to communicate securely, it is *essential* that
  27  * The communications between the two are encrypted
  28  * The identities of the caller and callee are established (authentication)
  29  * The caller must be allowed to do what it is asking to do (authorization)
  30
  31
  32 **Encryption**
  33
  34 Encryption is provided by HTTP/S with the TLS 1.2+ protocol. Lesser protocols can also be added, but it is highly recommended that the protocol go no lower than TLS 1.1
  35
  36 .. image:: images/SecurityArchBasic_TLS.svg
  37         :width: 70%
  38         :align: center
  39
  40 **Establishing Identity**
  41
  42 *Client Side*
  43
  44 In order to be secure of the Server Identity, the client will:
  45  * Carefully select the Endpoint for the server (URL)
  46  * The Service side Certificate chain obtained by TLS must ultimately be signed by a Certificate Authority that is trusted.
  47
  48 *Server Side*
  49
  50 The server side is a little harder to accomplish, because, while a client can choose carefully whom he contacts, the server, ultimately, might be contacted by literally anyone.
  51
  52 To solve this difficult problem, the CADI Framework Filter is attached to the incoming transaction before any code by Application 1 or Application 2 is invoked. The CADI Framework does the following:
  53  A) Establishes the claimed Identity (this differs by Protocol)
  54
  55    i) The Identity needs to be a Fully Qualified Identity (FQI), meaning it has
  56
  57     #) An ID approved by Organization (such as bob)
  58     #) A Domain establishing where the Credential is defined (ex: @bobs.garage.com)
  59     #) FQI Example: bob@bobs.garage.com
  60
  61  B) Validates the credential of the FQI ( *Authentication* )
  62
  63    i) Basic Auth (User/Password) is validated against the system supporting the domain
  64    ii) AAF Certman can create a fine-grained X509 certificate, which can derive FQI
  65    iii) If the FQI fails the Credential test in any way, the transaction is terminated
  66
  67  C) Obtain *Authorization* information
  68
  69    i) This might include a call to AAF which will return all the Permissions of the User per Application Context
  70    ii) This might involve pulling these from Cache
  71    iii) This also might be pulled from Token
  72
  73 .. image:: images/SecurityArchCADI.svg
  74         :width: 70%
  75         :align: center
  76
  77 Enabling the Client to Send Securely
  78 ------------------------------------
  79
  80 Once a secure scenario is in place, the client must provide more information, or he will be rejected by the secured server.
  81
  82  * FQI (Fully Qualified Identity)
  83  * Credential
  84    * If User/Password, then the client must send via "BasicAuth" Protocol
  85    * If two-way X509 identity, then the client must load the Cert and Private Key into the Client Software outside of the calling process.
  86    * If Token based Identity, such as OAuth2, the token must be placed on the call in just the right way.
  87  * Upstream Identity
  88    * Application Two might well want to process Authorizations based on the *end-user*, not the current caller.  In this scenario, Application One must provide the End User FQI in addition to its own before Application Two will accept.
  89
  90 In order to do this efficiently, ONAP services will use the CADI Client, which includes
  91   * Connection Information by Configuration
  92   * Encryption of any sensitive information in Configuration, such as Password, so that Configuration files will have no clear-text secrets.
  93   * Highly scalable Endpoint information (at the very least, of AAF components)
  94   * The ability to propogate the Identity of originating Caller (User One)
  95
  96 .. image:: images/SecurityArchCADIClient.svg
  97         :width: 70%
  98         :align: center
  99
 100
 101 Obtaining Security Information
 102 ------------------------------
 103
 104 In order for the client and server to perform securely, the need information they can trust, including
 105  * TLS needs X509 Certificate for the Server and any Client wishing to authenticate using Certificates
 106  * Any User/Password Credentials need to be validated real time
 107  * The server needs comprehensible Authorization information, preferably at the Application Scope
 108  * The client needs to find a server, even if the server must be massively geo-scaled
 109
 110 The AAF Suite provides the following elements:
 111  * AAF Service
 112         This service provides fine-grained Authorization information, and can, if required, also provide specialized Passwords for Applications (that allow for configuration migrations without a maintainance window)
 113  * OAuth
 114         AAF provides Token and Introspection service, but can also delegate to Organizatinally defined OAuth Services as well.
 115  * Locator
 116         Provides machine and port information by geo-location for massively scalable services.  This is optional for ONAP services, but required for AAF as part of its reliability and scalability solution.
 117  * GUI
 118         AAF provides a GUI for managing Namespaces (for Applications), Roles, Permissions and Credentials.
 119  * Certificate Manager
 120         Since AAF has fine-grained information about Identities, it can provide Certificates with FQIs embedded.  CADI Framework understands when and how to trust these FQIs.  When used, these Certificates provide enhanced speed and additional resiliency to the system, as they do not require network connections to validate.
 121
 122 .. image:: images/SecurityArchAAF.svg
 123         :width: 30%
 124         :align: center
 125
 126 The Organization
 127 ----------------
 128
 129 AAF is only a tool to reflect the Organization it is setup for.  AAF does not, for instance, know what IDs are acceptable to a particular company.  Every Organization (or Company) will also likely have its own Certificate Authority and DNS. Most importantly, each Organization will have a hierarchy of who is responsible for any give person or application.
 130
 131  * AAF's Certman connects to the Organization's CA via SCEP protocol (Others can be created as well)
 132  * AAF ties into the Organizational hierarchy.  Currently, this is through a feed of IDs and relationships.
 133  * AAF can process some Passwords, but delegate off others based on domain.
 134
 135 .. image:: images/SecurityArchAAFOrg.svg
 136         :width: 70%
 137         :align: center
 138
 139 The Whole Picture
 140 -----------------
 141
 142 CADI is a framework that enforces validations of Identities, and uses those Identities to obtain Authorization information for the Server.  The CADI client ensures that the right information is passed during secure connections.
 143
 144 AAF provides essential information based on the Organization to services in order to enable secure transactions between components.  It also provides sustaining processing capabilities to ensure that Credentials and Authorization relationships are maintained.
 145
 146 .. image:: images/SecurityArchFull.svg
 147         :width: 90%
 148         :align: center
 149
 150