Microservices: Documentation improvedHEADmaster

1 files changed, 16 insertions, 0 deletions

diff --git a/microservices/02-api-gateway/README b/microservices/02-api-gateway/README
new file mode 100644
index 0000000..310aeb0
--- /dev/null
+++ b/microservices/02-api-gateway/README
@@ -0,0 +1,16 @@
+This directory contains an API gateway implemented using Spring Cloud API Gateway.
+
+Look at the application.yaml as to how the API gateway forwards requests to backend services.
+
+Additional notes:
+  After a user successfully authenticates to the external OAuth2 authorization server and is redirected back to this API Gatway, the authorization server may not always return user role details. Some authorization servers may return such details but some others may not based on their configurations. Assuming the roles are defined within the specific application (specific backend services used and the React frontend) instead by the authorization server, the API gateway tries to find the user roles by accessing an internal REST service. This is coded in the SecurityConfig.java and uses the property app.userRolesUrl defined in application.yaml file.
+
+  The JavaScript frontend application can call the /api/security/me endpoint of this API Gateway for it to find the roles of authenticated users (so that the link display visibility and route availability can be controlled within the JavaScript frontend application based on user roles.) Exposing this endpoint has been coded in the UserRestController.java file.
+
+  During user authention this API gateway loads the role data (from the earlier said backend endpoint). After that, this API gateway adds the user roles to HTTP requests that are forworded to the backend services. This is coded in the RoleHeaderRelayFilter.java file.
+  
+  If a backend service needs to determine the roles of a user on behalf of whome a request is being served for, the backend service may use the HTTP headers sent by this API gateway. Keep in mind that this header information may not be trused by a backend service if the backend service is not deployed in an access restricted network. Otherwise, an attacker may send requests to the backend service with forged HTTP headers to force the backend service to assume different user roles.
+
+  This API gateway has been configured to forward the OAuth2 access token of a user to the backend service. This is accomplished by the TokenRelay filter added to the routes defined in application.yaml. A backend service configured as an OAuth2 resource server will use this token to detect the user on behalf of whome the API gatway forwarded a request. The backend service can trust the username determined from the access token even if the backend service is not deployed in an access restricted network (as opposed to trusting the details in HTTP headers).
+
+  Look at the README file of the sample resource server for further details about how the backend service determins the user and user roles.
\ No newline at end of file