From 3b4359927cdcac2492cebf9287830015b78a12dc Mon Sep 17 00:00:00 2001 From: Jim Minter Date: Mon, 26 Apr 2021 16:31:19 -0500 Subject: [PATCH] docs --- docs/dbtoken-service.md | 56 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/dbtoken-service.md diff --git a/docs/dbtoken-service.md b/docs/dbtoken-service.md new file mode 100644 index 000000000..e58b89628 --- /dev/null +++ b/docs/dbtoken-service.md @@ -0,0 +1,56 @@ +# DB token service + +## Introduction + +Cosmos DB access control is described +[https://docs.microsoft.com/en-us/azure/cosmos-db/secure-access-to-data](here). +In brief, there are three options: + +1. use r/w or r/o primary keys, which grant access to the whole database account +2. implement a service which transforms (1) into scoped resource tokens +3. a third AAD RBAC-based model is in preview. + +Currently, the RP, monitoring and portal service share the same security +boundary (the RP VM) and use option 1. The dbtoken service, which also runs on +the RP VM, is our implementation of option 2. As and when option 3 goes GA, it +may be possible to retire the dbtoken service. + +The purpose of the dbtoken service at its implementation time is to enable the +gateway component (which handles end-user traffic) to access the service Cosmos +DB without recourse to using root credentials. This provides a level of defence +in depth in the face of an attack on the gateway component. + + +## Workflow + +* An AAD application is manually created at rollout, registering the + https://dbtoken.aro.azure.com resource. + +* The dbtoken service receives POST requests from any client wishing to receive + a scoped resource token at its /token?permission= endpoint. + +* The dbtoken service validates that the POST request includes a valid + AAD-signed bearer JWT for the https://dbtoken.aro.azure.com resource. The + subject UUID is retrieved from the JWT. + +* In the case of the gateway service, the JWT subject UUID is the UUID of the + service principal corresponding to the gateway VMSS MSI. + +* Using its primary key Cosmos DB credential, the dbtoken requests a scoped + resource token for the given user UUID and from Cosmos DB and + proxies it to the caller. + +* Clients may use the dbtoken.Refresher interface to handle regularly refreshing + the resource token and injecting it into the database client used by the rest + of the client codebase. + + +## Setup + +* At rollout time, create an AAD application whose *Application ID URI* + (`identifierUris` in the application manifest) is + `https://dbtoken.aro.azure.com`. It is not necessary for the application to + have any permissions, credentials, etc. + +* The dbtoken service is responsible for creating database users and permissions + - see the `ConfigurePermissions` function.