1# Emergency Access Authorization Service
2
3This is a binary to start a server used in the Emergency Access system to authorize Remote CLI users. The service communicates with `ea-ws`, `ea-rulesengine` and `ea-userservice`, and is expected to run in a kube cluster. The libraries used to build up the source code can be found under `pkg/sds/emergencyaccess/authservice`.
4
5
6- [Emergency Access Authorization Service](#emergency-access-authorization-service)
7 - [Database](#database)
8 - [Authorization](#authorization)
9- [Endpoints](#endpoints)
10 - [Authorize Command](#authorize-command)
11 - [Authorize Request](#authorize-request)
12 - [Authorize Target](#authorize-target)
13 - [Resolve Target](#resolve-target)
14 - [Authorize User](#authorize-user)
15
16
17## Database
18
19Authservice requires a connection to the postgres database to authorize session details. It is possible to connect to a local DB instance or a GCP Cloud SQL instance. Connection details are set via environment variables or command line flags.
20
21To connect to the GCP Cloud SQL instance the instance connection name `DATABASE_CONNECTION_NAME`, the username of the GCP service account or user `DATABASE_USERNAME`, and database name `DATABASE_NAME` is required.
22
23To connect to a local instance the database hostname and port `DATABASE_HOST` and `DATABASE_PORT`, the user to connect with `DATABASE_USERNAME` and `DATABASE_PASSWORD`, as well as the `DATABASE_NAME` is required.
24
25## Authorization
26
27Authservice is expected to be deployed behind the [auth-proxy](../../../edge/auth-proxy/server.go)
28which will do all user authentication for emergencyaccess. Only user authorization is done within the emergencyaccess services
29
30Authservice requires a set of authentication headers on all incoming http requests to identify the pre-authenticated user.
31
32The following table documents the required headers:
33
34| Header | Type | Multi-Valued | Details |
35| ----------------- | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36| `X-Auth-Username` | string | false | The value of this header indicates the unique username of the user attempting to connect. This value must not be empty. |
37| `X-Auth-Email` | string | false | The email address of the user attempting to connect. This value must not be empty. |
38| `X-Auth-Roles` | string | true | This header contains the Edge Roles that have been assigned to the user. |
39| `X-Auth-Banners` | string | true | This header contains all of the banners that the user is allowed to access. If a user is an Org Viewer or Admin, this header must include all banners within the org, not only those the user has been assigned. |
40
41Multi-Valued indicates the header allows setting multiple values.
42This can be done by specifying the header multiple times, with one value per header, e.g.
43
44```
45X-Auth-Roles: role1
46X-Auth-Roles: role2
47```
48
49# Endpoints
50
51## Authorize Command
52
53Returns a valid response with status 200 if the command is permitted according to the rules engine.
54
55__URI__: `/authorizeCommand`
56
57__Method__ : `POST`
58
59__Request__:
60
61```json
62{
63 "command":"somecommand",
64 "target":
65 {
66 "bannerID":"a-banner-id"
67 }
68 "authDetails":{
69 "darkmode":true/false
70 }
71}
72```
73__Response__:
74
75```json
76{
77 "valid":true
78}
79```
80__Error codes__:
81code | error
82-|-
83200 | ok
84400 | bad request (60201,60202)
85403 | forbidden (60003)
86500 | internal server error
87
88## Authorize Request
89
90Returns a valid structured request response with status 200 if the request is valid and permitted according to the rules engine.
91
92__URI__: `/authorizeRequest`
93
94__Method__ : `POST`
95
96__Request__:
97
98```json
99{
100 "request": {
101 "data": {
102 /* request message data - structured differently depending on message version */
103 },
104 "attributes": {
105 "version": "1.0",
106 "type": "<command, executable, job, etc>"
107 }
108 },
109 "target": {
110 "projectID": "projectID",
111 "bannerID": "bannerID",
112 "storeID": "storeID",
113 "terminalID": "terminalID"
114 }
115}
116```
117
118__Response__:
119
120```json
121{
122 "request": {
123 "data": {
124 /* request message data - structured differently depending on message version */
125 },
126 "attributes": {
127 "version": "1.0",
128 "type": "<command, executable, job, etc>",
129 "bannerId": "bannerID",
130 "storeId": "storeID",
131 "terminalId": "terminalID",
132 "identity": "username
133 }
134 }
135}
136```
137
138__Error codes__:
139
140| code | error |
141| - | - |
142| 200 | ok |
143| 400 | bad request (60201,60202) |
144| 403 | forbidden (60003, 62001) |
145| 500 | internal server error |
146
147## Authorize Target
148
149Returns a 200 OK with no response if permitted. 403 if unauthorized.
150
151__URI__: `/authorizeTarget`
152
153__Header__: see Authentication header in eagateway README.
154
155__Method__ : `POST`
156
157__Request__:
158
159```json
160{
161 "target": {
162 "projectid": "a-project-id",
163 "bannerid": "a-banner-id",
164 "storeid": "a-store-id",
165 "terminalid": "a-terminal-id"
166 }
167}
168```
169__Error codes__:
170code | error
171-|-
172200 | ok
173400 | bad request (60201)
174403 | forbidden (60003)
175500 | internal server error
176
177## Resolve Target
178
179Verifies the existence of a given target (without a project ID) and returns a 200 code and the resolved target ID details if successful.
180
181__URI__: `/resolveTarget`
182
183__Method__ : `POST`
184
185__Request__:
186
187```json
188{
189 "target": {
190 "bannerid": "a-banner-id-or-name",
191 "storeid": "a-store-id-or-name",
192 "terminalid": "a-terminal-id-or-name"
193 }
194}
195```
196
197__RESPONSE__:
198```json
199{
200 "target": {
201 "projectid": "a-project-id",
202 "bannerid": "a-banner-id",
203 "storeid": "a-store-id",
204 "terminalid": "a-terminal-id"
205 }
206}
207```
208
209__Error codes__:
210code | error | cause
211-|-|-
212200 | ok | Target resolved
213400 | bad request | Target not resolved: Invalid payload structure (60201), invalid payload properties (60202), target details not found (61202)
214500 | internal server error | Server Error (60101)
215
216
217## Authorize User
218
219Verifies the User is authorized by confirming the user is assigned at least 1 emergency access privilege.
220
221__URI__: `/authorizeUser`
222
223__Method__ : `POST`
224
225__Request__:
226
227Empty Request
228
229__RESPONSE__:
230
231Empty Response
232
233__Error codes__:
234
235| code | error | cause |
236| ---- | --------------------- | -------------------- |
237| 200 | ok | User authorized |
238| 403 | forbidden | User not authorized |
239| 500 | internal server error | Server Error (60101) |
View as plain text