sidecar/rproxy/README.md

   1 # Reverse Proxy Introduction
   2
   3 The **AAF Reverse Proxy** (or **rProxy**) is a proxy microservice which intercepts incoming REST requests by, extracting the credentials from the request and authenticates/authorises
   4 with a configured security provider. It is one of two components (along with the [Forward proxy][1]) deployed as a Kubernetes sidecar to
   5 separate the responsibility of authentication and authorization away from the primary microservice, this service is responsible for
   6 controlling access to the REST URL endpoints exposed by the primary microservice, and propagating security credentials to downstream microservices.
   7
   8 ## Features
   9
  10 **Reverse Proxy**:
  11
  12 * The service will intercept all incoming REST requests to the primary service, extract and cache the token credentials in the [Forward proxy][1].
  13 * Invokes the authentication and authorisation providers to validate the extracted tokens, and retrieves its list of authorisations.
  14 * Invokes the enforcement point filter to determine whether the incoming request URI and retrieved permissions match the list of granted URIs and permissions
  15   configured in the URI authorisation file. If authorisation is successful, forward the request to the primary service.
  16
  17 ## Configuring the rProxy service
  18 The **rProxy service** is configured through properties and JSON files that reside under the `${CONFIG_HOME}` environment variable.
  19
  20 The files have the following configurable properties:
  21
  22 ### cadi.properties
  23
  24 - `cadi_loglevel` log level of the cadi filter, e.g. DEBUG, INFO
  25 - `cadi_keyfile`  location to the cadi key file
  26 - `cadi_truststore`
  27 - `cadi_truststore_password`
  28 - `aaf_url` hostname and port of the server hosting the AAF service, e.g. https://aaf.osaaf.org:30247
  29 - `aaf_env` AAF environment type, e.g. DEV, PROD
  30 - `aaf_id` aafadmin user, e.g. demo@people.osaaf.org
  31 - `aaf_password` aafadmin user password encrypted with the cadi_keyfile, e.g. enc:92w4px0y_rrm265LXLpw58QnNPgDXykyA1YTrflbAKz
  32 - `cadi_x509_issuers` colon separated list of client cert issuers
  33
  34 ### reverse-proxy.properties
  35
  36 - `transactionid.header.name`   This is the name of the header in incoming requests that will contain the transaction ID e.g. `X-TransactionId`
  37
  38 ### primary-service.properties
  39
  40 - `primary-service.protocol` HTTP protocol of the primary service e.g. https
  41 - `primary-service.host` location of the primary service, since this sidecar resides in the same pod of the primary service. e.g. localhost
  42 - `primary-service.port` port of the primary service
  43
  44 ### forward-proxy.properties
  45
  46 - `forward-proxy.protocol` HTTP protocol of the [fproxy service][1] e.g. https
  47 - `forward-proxy.host` location of the [fproxy service][1], since this sidecar resides in the same pod of the primary service. e.g. localhost
  48 - `forward-proxy.port` port of the [fproxy service][1]
  49 - `forward-proxy.cacheurl` URI to the store credential cache. e.g. /credential-cache
  50
  51 ### auth/uri-authorization.json
  52 This file is used by the **ReverseProxyAuthorization filter**, the configurable authorization enforcement point, and contains the list
  53 of required AAF permissions needed for the request URI. The content of the file is in JSON format. Permissions will be tested against
  54 the first matching URI. If the user does not have those permissions then the next matching URI will be tested until the list of URIs
  55 is exhausted. URIs will be matched in order as positioned in the configuration file. All permissions listed in the configuration file
  56 for a request URI must have been granted to the user.
  57
  58 The current implementation of sidecar security retrieves user permissions from AAF. AAF permissions are composed of a type, instance and
  59 action and are returned from AAF as those values separated by the pipe (|) character e.g. org.onap.osaaf.resources.access|rest|read.
  60 Both instance and/or action can be wildcarded with an asterisk (\*) e.g. org.onap.osaaf.resources.access|\*|read,
  61 org.onap.osaaf.resources.access|rest|\* or org.onap.osaaf.resources.access|\*|\*.  If action or instance is wildcarded then a match
  62 between granted and needed permissions is found as long as the non wildcarded parts of the permission is also matched.
  63
  64 Both URIs and permissions are matched using regular expressions which are defined in the `uri-authorization.json` file. Regular
  65 expression tests are applied to the whole permission unless AAF wildcarding has been used in which case the permissions are split
  66 into type, instance and action and the non wildcarded parts are tested individually. Note that owing to regular expression and JSON
  67 format that backslashes need to be escaped twice.
  68 ```
  69 [
  70     {
  71       "uri": "URI 1",
  72       "permissions": [
  73         "permission 1",
  74         "permission 2",
  75         "..."]
  76     },
  77     {
  78       "uri": "URI 2",
  79       "permissions": [
  80         "permission 3",
  81         "permission 4",
  82         "..."]
  83     }
  84 ]
  85 ```
  86 e.g.
  87 ```
  88 [
  89     {
  90       "uri": "\\/aai\\/v13\\/cloud-infrastructure\\/cloud-regions$",
  91       "permissions": [
  92         "org\\.onap\\.osaaf\\.resources\\.access\\|rest\\|read"
  93        ]
  94     },
  95     {
  96       "uri": "\\/aai\\/v13\\/cloud-infrastructure\\/cloud-regions\\/cloud-region\\/[^\\/]+[\\/][^\\/]+$*",
  97       "permissions": [
  98         "org\\.onap\\.osaaf\\.resources\\.access|clouds|read",
  99         "org\\.onap\\.osaaf\\.auth\\.resources\\.access|tenants|read"
 100       ]
 101     },
 102     {
 103       "uri": "\\/aai\\/v13\\/cloud-infrastructure\\/cloud-regions\\/cloud-region\\/[^\\/]+[\\/][^\\/]+\\/tenants\\/tenant/[^\\/]+\\/vservers\\/vserver\\/[^\\/]+$",
 104       "permissions": [
 105         "org\\.onap\\.osaaf\\.auth\\.resources\\.access\\|clouds\\|read",
 106         "org\\.onap\\.osaaf\\.auth\\.resources\\.access\\|tenants\\|read",
 107         "org\\.onap\\.osaaf\\.auth\\.resources\\.access\\|vservers\\|read"
 108       ]
 109     }
 110 ]
 111 ```
 112
 113 ## Using an Alternative Authorization Service Provider
 114 The current implementation of sidecar security relies on AAF & use of the CADI filter. In order to use an alternative authorization
 115 service provider it will be necessary to modify the Reverse Proxy sidecar filter chain. The first change necessary is replacement of
 116 the CADI filter. The replacing filter will be responsible for extracting the credentials from the incoming request, contacting the
 117 alternative authorization service to return the authorizations/permissions and passing the authorizations through to the
 118 **ReverseProxyAuthorization filter**. The **ReverseProxyAuthorization filter** is next in the filter chain.  Currently authorizations are passed
 119 with the `HttpServletRequestWrapper` derived CADIWrap object. If it is desirable to not have a dependency on the CADI libraries then a
 120 new object derived from `HTTPServletRequestWrapper` can be used or alternatively authorizations could be passed as an attribute set on
 121 the `HTTPServletRequest`. If either of these two options is chosen then the **ReverseProxyAuthorization filter** have to be altered to use
 122 the new object or to retrieve authorizations from the request attribute. Finally the `auth/uri-authorization.json` file will need revision to
 123 match the new format and list of permissions for the URI requests.
 124
 125 [1]: ../fproxy/README.md