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 ALL components of AAF are accessible only by HTTP/S (service, locate, oauth, gui, certman), EXCEPT the component "FS".
  37
  38 FS *must* be HTTP, because it is responsible for being accessible DURING the TLS process for recent RCLs.  (Revocation lists).  Since it is part of the TLS process, it cannot be TLS itself.
  39
  40 .. image:: images/SecurityArchBasic_TLS.svg
  41         :width: 70%
  42         :align: center
  43
  44 **Establishing Identity**
  45
  46 *Client Side*
  47
  48 In order to be secure of the Server Identity, the client will:
  49  * Carefully select the Endpoint for the server (URL)
  50  * The Service side Certificate chain obtained by TLS must ultimately be signed by a Certificate Authority that is trusted.
  51
  52 *Server Side*
  53
  54 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.
  55
  56 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:
  57  A) Establishes the claimed Identity (this differs by Protocol)
  58
  59    i) The Identity needs to be a Fully Qualified Identity (FQI), meaning it has
  60
  61     #) An ID approved by Organization (such as bob)
  62     #) A Domain establishing where the Credential is defined (ex: @bobs.garage.com)
  63     #) FQI Example: bob@bobs.garage.com
  64
  65  B) Validates the credential of the FQI ( *Authentication* )
  66
  67    i) Basic Auth (User/Password) is validated against the system supporting the domain
  68    ii) AAF Certman can create a fine-grained X509 certificate, which can derive FQI
  69    iii) If the FQI fails the Credential test in any way, the transaction is terminated
  70
  71  C) Obtain *Authorization* information
  72
  73    i) This might include a call to AAF which will return all the Permissions of the User per Application Context
  74    ii) This might involve pulling these from Cache
  75    iii) This also might be pulled from Token
  76
  77 .. image:: images/SecurityArchCADI.svg
  78         :width: 70%
  79         :align: center
  80
  81 Enabling the Client to Send Securely
  82 ------------------------------------
  83
  84 Once a secure scenario is in place, the client must provide more information, or he will be rejected by the secured server.
  85
  86  * FQI (Fully Qualified Identity)
  87  * Credential
  88    * If User/Password, then the client must send via "BasicAuth" Protocol
  89    * If two-way X509 identity, then the client must load the Cert and Private Key into the Client Software outside of the calling process.
  90    * If Token based Identity, such as OAuth2, the token must be placed on the call in just the right way.
  91  * Upstream Identity
  92    * 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.
  93
  94 In order to do this efficiently, ONAP services will use the CADI Client, which includes
  95   * Connection Information by Configuration
  96   * Encryption of any sensitive information in Configuration, such as Password, so that Configuration files will have no clear-text secrets.
  97   * Highly scalable Endpoint information (at the very least, of AAF components)
  98   * The ability to propogate the Identity of originating Caller (User One)
  99
 100 .. image:: images/SecurityArchCADIClient.svg
 101         :width: 70%
 102         :align: center
 103
 104
 105 Obtaining Security Information
 106 ------------------------------
 107
 108 In order for the client and server to perform securely, the need information they can trust, including
 109  * TLS needs X509 Certificate for the Server and any Client wishing to authenticate using Certificates
 110  * Any User/Password Credentials need to be validated real time
 111  * The server needs comprehensible Authorization information, preferably at the Application Scope
 112  * The client needs to find a server, even if the server must be massively geo-scaled
 113
 114 The AAF Suite provides the following elements:
 115  * AAF Service
 116         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)
 117  * OAuth
 118         AAF provides Token and Introspection service, but can also delegate to Organizatinally defined OAuth Services as well.
 119  * Locator
 120         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.
 121  * GUI
 122         AAF provides a GUI for managing Namespaces (for Applications), Roles, Permissions and Credentials.
 123  * Certificate Manager
 124         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.
 125
 126 .. image:: images/SecurityArchAAF.svg
 127         :width: 30%
 128         :align: center
 129
 130 The Organization
 131 ----------------
 132
 133 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.
 134
 135  * AAF's Certman connects to the Organization's CA via SCEP protocol (Others can be created as well)
 136  * AAF ties into the Organizational hierarchy.  Currently, this is through a feed of IDs and relationships.
 137  * AAF can process some Passwords, but delegate off others based on domain.
 138
 139 .. image:: images/SecurityArchAAFOrg.svg
 140         :width: 70%
 141         :align: center
 142
 143 The Whole Picture
 144 -----------------
 145
 146 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.
 147
 148 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.
 149
 150 .. image:: images/SecurityArchFull.svg
 151         :width: 90%
 152         :align: center
 153
 154