docs/sections/development/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
   5
   6 Development
   7 ============
   8 .. _Example RESTful Client: https://gerrit.onap.org/r/gitweb?p=aaf/authz.git;a=blob;f=cadi/oauth-enduser/src/main/java/org/onap/aaf/cadi/enduser/SimpleRESTClient.java;h=30344de521ae628221bdb54642a71733304a5656;hb=HEAD
   9 .. _Developer Video: https://wiki.onap.org/download/attachments/38111886/ONAPClient.mp4?version=1&modificationDate=1532378616000&api=v2
  10
  11 ============
  12 Resources
  13 ============
  14   * `Example RESTful Client`_ (Java Client)
  15   * `Developer Video`_ (might be large)
  16
  17 =========================
  18 ONAP Test Env
  19 =========================
  20
  21 -------
  22 Purpose
  23 -------
  24
  25 The AAF Test Environment is a single instance VM setp so that
  26   - ONAP Developers can utilize AAF with their personal machines without having to run their own AAF.
  27   - ONAP Developers can put the Permissions and Roles required for their Apps into a common AAF Environment with others
  28   - AAF will pull (on demand) all the ONAP related Data (Perms/Roles/Identities) and put into "Bootstrap Data".
  29         - This Bootstrap data becomes available on the myriad Testing Systems so that
  30                 - They don't have to create AAF Data loading on their own.
  31                 - The data is already consistent with other ONAP entities.
  32
  33 ------
  34 Access
  35 ------
  36
  37 You must be connected to the WindRiver "pod-onap-01" VPN to gain access
  38 to AAF Beijing
  39
  40 ----------------
  41 DNS (/etc/hosts)
  42 ----------------
  43
  44 At this time, there is no known DNS available for ONAP Entities.  It is
  45 recommended that you add the following entry into your "/etc/hosts" on
  46 your accessing machine:
  47
  48     /etc/hosts:
  49
  50     10.12.6.214 aaf-onap-beijing-test aaf-onap-beijing-test.osaaf.org
  51
  52 --------------------
  53 Finding AAF Services
  54 --------------------
  55
  56 AAF can be run as standalone Java Services, Docker and Kubernetes. For Kubernetes and some Docker installs, AAF's Services  need to be able to be contacted both inside the K8S, not just one name or port.
  57
  58 AAF has a Locator Service, default port of 8095, which will give the URLs of Running Services.  The CADI Client uses this, but any Authenticated Client may make queries.
  59
  60 With El Alto, you can request Internal or External URLs.
  61
  62 Example
  63   * assumes ONAP Test Env URL, and access to ONAP Test Systems
  64   * put URL in browser
  65
  66 External URL:https://aaf-onap-test.osaaf.org:8095/locate/org.osaaf.aaf.service:2.1
  67 Internal URL:https://aaf-onap-test.osaaf.org:8095/locate/onap.org.osaaf.aaf.service:2.1
  68
  69 Where "onap" is the Container name
  70
  71 ------------------------------
  72 Environment Artifacts (AAF FS)
  73 ------------------------------
  74
  75     AAF has an HTTP Fileserver to gain access to needed public info.
  76
  77     http://aaf-onap-beijing-test.osaaf.org/-
  78
  79 -----------
  80 Credentials
  81 -----------
  82
  83     AAF does support User/Password, and allows additional plugins as it
  84     did in Amsterdam, however, User/Password credentials are inferior to
  85     PKI technology, and does not match the ONAP Design goal of TLS and
  86     PKI Identity across the board.  Therefore, while an individual
  87     organization might avail themselves of the User/Password facilities
  88     within AAF, for ONAP, we are avoiding.
  89
  90     THEREFORE: **GO WITH CERTIFICATE IDENTITY**
  91
  92
  93 Root Certificate
  94 ^^^^^^^^^^^^^^^^
  95
  96     `AAF\_RootCA.cer <http://aaf-onap-beijing-test.osaaf.org/AAF_RootCA.cer>`__
  97
  98 AAF CA
  99 ^^^^^^
 100
 101     At time of Beijing, an official Certificate Authority for ONAP was
 102     not declared, installed or operationalized.  Secure TLS requires
 103     certificates, so for the time being, the Certificate Authority is
 104     being run by AAF Team.
 105
 106 Root Certificate
 107 ''''''''''''''''
 108
 109     | The Root Certificate for ONAP Certificate Authority used by AAF
 110       is \ `AAF\_RootCA.cer <http://aaf-onap-beijing-test.osaaf.org/AAF_RootCA.cer>`__
 111     | Depending on your Browser/ Operating System, clicking on this link
 112       will allow you to install this Cert into your Browser for GUI
 113       access (see next)
 114
 115     This Root Certificate is also available in "truststore" form, ready
 116     to be used by Java or other processes:
 117
 118 -
 119
 120    -
 121
 122       -  `truststoreONAP.p12 <http://aaf-onap-beijing-test.osaaf.org/truststoreONAP.p12>`__
 123              -  This Truststore has ONLY the ONAP AAF\_RootCA in it.
 124
 125       -  `truststoreONAPall.jks <http://aaf-onap-beijing-test.osaaf.org/truststoreONAPall.jks>`__
 126              - This Truststore has the ONAP AAF\_RootCA in it PLUS all the Public CA Certs that are in Java 1.8.131 (note: this is in jks format, because the original JAVA truststore was in jks format)
 127
 128     Note: as of Java 8, pkcs12 format is recommended, rather than jks.
 129      Java's "keytool" utility provides a conversion for .jks for Java 7
 130     and previous.
 131
 132 Identity
 133 ''''''''
 134
 135     Certificates certify nothing if there is no identity or process to
 136     verify the Identity.  Typically, for a company, an HR department
 137     will establish the formal organization, specifically, who reports to
 138     whom.  For ONAP, at time of Beijing, no such formalized "Org Chart"
 139     existed, so we'll be building this up as we go along.
 140
 141     Therefore, with each Certificate Request, we'll need identity
 142     information as well, that will be entered into an ONAP Identity
 143     file.  Again, as a real company, this can be derived or accessed
 144     real-time (if available) as an "Organization Plugin".  Again, as
 145     there appears to be no such central formal system in ONAP, though,
 146     of course, Linux Foundation logins have some of this information for
 147     ALL LF projects.  Until ONAP declares such a system or decides how
 148     we might integrate with LF for Identity and we have time to create
 149     an Integration strategy, AAF will control this data.
 150
 151     For each Identity, we'll need:
 152
 153   People
 154
 155
 156     | # 0 - unique ID (for Apps, just make sure it is unique, for
 157       People, one might consider your LinuxFoundation ID)
 158     | # 1 - full name (for App, name of the APP)
 159     | # 2 - first name (for App,
 160     | # 3 - last name
 161     | # 4 - phone
 162     | # 5 - official email
 163     | # 6 - type - person
 164     | # 7 - reports to: If you are working as part of a Project, list
 165       the PTL of your Project.  If you are PTL, just declare you are the
 166       PTL
 167
 168   Applications
 169
 170
 171     | # 0 - unique ID - For ONAP Test, this will be the same a the App
 172       Acronym.
 173     | # 1 - full name of the App
 174     | # 2 - App Acronym
 175     | # 3 - App Description, or just "Application"
 176     | # 5 - official email - a Distribution list for the Application, or
 177       the Email of the Owner
 178     | # 6 - type - application
 179     | # 7 - reports to: give the Application Owner's Unique ID.  Note,
 180       this should also be the Owner in AAF Namespace
 181
 182 Obtaining a Certificate
 183 '''''''''''''''''''''''
 184
 185 Services/Clients
 186     See `Automated Configuration and Certificates`_.
 187
 188 .. _Automated Configuration and Certificates: AAF_4.1_config.html
 189
 190 People
 191
 192
 193     People Certificates can be used for browsers, curl, etc.
 194
 195     Automation and tracking of People Certificates will be proposed for
 196     Dublin.
 197
 198
 199