webapp-backend/README.md

   1 # RIC Dashboard Web Application Backend
   2
   3 The RIC Dashboard back-end provides REST services to the Dashboard
   4 front-end Typescript features running in the user's browser.  For
   5 production use, this server also offers the Angular application files.
   6
   7 The server uses the ONAP Portal's "EPSDK-FW" library to support
   8 single-sign-on (SSO) feature, which requires users to authenticate
   9 at the ONAP Portal UI.  Authentication features including SSO are
  10 excluded by Spring profiles when running the back-end as a development
  11 server, see below.
  12
  13 ## Launch production server
  14
  15 This server requires several configuration files:
  16
  17     application.properties (in launch directory)
  18     key.properties (on Java classpath)
  19     portal.properties (on Java classpath)
  20
  21 These steps are required:
  22
  23 1. Check the set of properties files in the config folder, and create
  24    files from templates as needed.  E.g., copy
  25    "key.properties.template" to "key.properties".
  26 2. Add the config folder to the Java classpath
  27 3a. Launch the server with this command-line invocation:
  28
  29     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
  30         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
  31         org.springframework.boot.loader.PropertiesLauncher
  32
  33 3b. To use the configuration in the "application-abc.properties" file, addd a
  34 key-value pair for "spring.config.name" and launch with an invocation like this:
  35
  36     java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
  37         -Dspring.config.name=application-abc \
  38         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
  39         org.springframework.boot.loader.PropertiesLauncher
  40
  41 ### Production user authentication
  42
  43 The regular server authenticates requests using cookies that are set
  44 by the ONAP Portal:
  45
  46      EPService
  47      UserId
  48
  49 The EPService value is not checked.  The UserId value is decrypted
  50 using a secret key shared with the ONAP Portal to yield a user ID.
  51 That ID must match a user's loginId defined in the user manager.
  52
  53 The regular server checks requests for the following granted
  54 authorities (role names), as defined in the DashboardConstants class.
  55 A standard user can read (GET) all methods but not make changes.
  56 An administrator can read (GET) and write (POST PUT DELETE) all data.
  57
  58     Standard_User
  59         System_Administrator
  60
  61 Use the following structure in a JSON file to publish a user for the
  62 user manager:
  63
  64     [
  65      {
  66       "orgId":null,
  67       "managerId":null,
  68       "firstName":"Demo",
  69       "middleInitial":null,
  70       "lastName":"User",
  71       "phone":null,
  72       "email":null,
  73       "hrid":null,
  74       "orgUserId":null,
  75       "orgCode":null,
  76       "orgManagerUserId":null,
  77       "jobTitle":null,
  78       "loginId":"demo",
  79       "active":true,
  80       "roles":[
  81          {
  82             "id":null,
  83             "name":"Standard_User",
  84             "roleFunctions":null
  85          }
  86       ]
  87      }
  88     ]
  89
  90
  91 ## Launch development server
  92
  93 The development server uses local configuration and serves mock data
  94 that simulates the behavior of remote endpoints.  The directory
  95 src/main/resources contains usable versions of the required property
  96 files.  These steps are required to launch:
  97
  98 1. Set an environment variable via JVM argument: "-Dorg.oransc.ric.portal.dashboard=mock"
  99 2. Run the JUnit test case DashboardServerTest -- not exactly a "test" because it never finishes.
 100
 101 Both steps can be done with this command-line invocation:
 102
 103      mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer test
 104
 105 ### Development user authentication
 106
 107 The development server requires basic HTTP user authentication for all requests. Like
 108 the production server, it requires HTTP headers with authentication for Portal API
 109 requests.  The credentials are in constants in this Java class in the src/test/java
 110 folder:
 111
 112     org.oransc.ric.portal.dashboard.config.WebSecurityMockConfiguration
 113
 114 Like the production server, the development server also performs role-based
 115 authentication on requests. The user name-role  name associations are defined
 116 in the class shown above.
 117
 118 ## Swagger API documentation
 119
 120 Both a regular and a development server publish API documentation at URL `http://localhost:8080/swagger-ui.html`.
 121
 122 ## License
 123
 124 Copyright (C) 2019 AT&T Intellectual Property & Nokia. All rights reserved.
 125 Licensed under the Apache License, Version 2.0 (the "License");
 126 you may not use this file except in compliance with the License.
 127 You may obtain a copy of the License at
 128
 129      http://www.apache.org/licenses/LICENSE-2.0
 130
 131 Unless required by applicable law or agreed to in writing, software
 132 distributed under the License is distributed on an "AS IS" BASIS,
 133 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 134 See the License for the specific language governing permissions and
 135 limitations under the License.