docs/developer-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2019 AT&T Intellectual Property
   4
   5 RIC Dashboard Developer Guide
   6 =============================
   7
   8 This document provides a quickstart for developers of the O-RAN SC RIC
   9 Dashboard web application.
  10
  11 Prerequisites
  12 -------------
  13
  14 1. Java development kit (JDK), version 11 or later
  15 2. Maven dependency-management tool, version 3.4 or later
  16
  17 Other required tools including the Node Package Manager (npm) are
  18 fetched dynamically.
  19
  20 Clone and Update Submodules
  21 ---------------------------
  22
  23 After cloning the repository, initialize and update all git submodules
  24 like this::
  25
  26     git submodule init
  27     git submodule update
  28
  29 Check the submodule status at any time like this::
  30
  31     git submodule status
  32
  33
  34 Angular Front-End Application
  35 -----------------------------
  36
  37 The Angular 8 application files are in subdirectory
  38 ``webapp-frontend``.  Build the front-end application via ``mvn
  39 package``.  For development and debugging, build the application, then
  40 launch an ng development server using this command::
  41
  42     ./ng serve --proxy-config proxy.conf.json
  43
  44 The app will automatically reload in the browser if you change any of
  45 the source files.  The ng server listens for requests at this URL:
  46
  47     http://localhost:4200
  48
  49
  50 Spring-Boot Back-End Application
  51 --------------------------------
  52
  53 A development (not production) server uses local configuration and
  54 serves mock data that simulates the behavior of remote endpoints.  The
  55 back-end server listens for requests at this URL:
  56
  57     http://localhost:8080
  58
  59 The directory ``src/test/resources`` contains usable versions of the
  60 required property files.  These steps are required to launch:
  61
  62 1. Install all project jar files locally
  63 2. Set an environment variable via JVM argument: ``-Dorg.oransc.ric.portal.dashboard=mock``
  64 3. Run the JUnit test case ``DashboardTestServer`` which is not exactly a "test" because it never finishes.
  65
  66 These steps can be done with these commands::
  67
  68      mvn -Ddocker.skip=true -DskipTests=true install
  69      mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer test
  70
  71 Development user authentication
  72 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  73
  74 The development server requires basic HTTP user authentication for all
  75 requests. Like the production server, it requires HTTP headers with
  76 authentication for Portal API requests.  The username and password are
  77 stored in constants in this Java class in the ``src/test/java``
  78 folder::
  79
  80     org.oransc.ric.portal.dashboard.config.WebSecurityMockConfiguration
  81
  82 Like the production server, the development server also performs
  83 role-based authentication on requests. The user name-role name
  84 associations are also defined in the class shown above.
  85
  86 Production user authentication
  87 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  88
  89 The server uses the ONAP Portal's "EPSDK-FW" library to support a
  90 single-sign-on (SSO) feature, which requires users to authenticate at
  91 the ONAP Portal UI. The RIC Dashboard can be on-boarded as an
  92 application on the ONAP Portal using its application on-boarding UI.
  93
  94 The server authenticates requests using cookies that are set
  95 by the ONAP Portal::
  96
  97      EPService
  98      UserId
  99
 100 The EPService value is not checked.  The UserId value is decrypted
 101 using a secret key shared with the ONAP Portal to yield a user ID.
 102 That ID must match a user's loginId defined in the user manager.
 103
 104 The regular server checks requests for the following granted
 105 authorities (role names), as defined in the java class
 106 ``DashboardConstants``.  A standard user can invoke all "GET" methods
 107 but not make changes.  A system administrator can invoke all methods
 108 ("GET", "POST", "PUT", "DELETE") to make arbitrary changes::
 109
 110     Standard_User
 111     System_Administrator
 112
 113 Use the following structure in a JSON file to publish a user for the
 114 user manager::
 115
 116     [
 117      {
 118       "orgId":null,
 119       "managerId":null,
 120       "firstName":"Demo",
 121       "middleInitial":null,
 122       "lastName":"User",
 123       "phone":null,
 124       "email":null,
 125       "hrid":null,
 126       "orgUserId":null,
 127       "orgCode":null,
 128       "orgManagerUserId":null,
 129       "jobTitle":null,
 130       "loginId":"demo",
 131       "active":true,
 132       "roles":[
 133          {
 134             "id":null,
 135             "name":"Standard_User",
 136             "roleFunctions":null
 137          }
 138       ]
 139      }
 140     ]