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