Update /auth/mapping endpoints docs (#162)

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "go.sum|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2023-01-31T20:54:41Z",
+  "generated_at": "2024-03-01T20:51:33Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -70,7 +70,7 @@
       {
         "hashed_secret": "f9fdc64928c96c7ad56bf7da557f70345d83a6ed",
         "is_verified": false,
-        "line_number": 1665,
+        "line_number": 1684,
         "type": "Base64 High Entropy String"
       }
     ],

README.md

@@ -23,6 +23,8 @@ microservices needing to check user authorization to operate on a resource can
 statelessly verify the user's authorization, making a request to arborist with
 the user's JWT and receiving a response for the authorization decision.
 
+The key documentation is below. Additional documentation can be found in the [/docs](/docs) directory.
+
 ## API documentation
 
 [OpenAPI documentation available here.](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/uc-cdis/arborist/master/docs/openapi.yaml)

arborist/auth.go

@@ -664,13 +664,13 @@ type AuthMappingQuery struct {
 
 type AuthMapping map[string][]Action
 
-// authMapping gets the auth mapping for the user with this username.
+// authMappingForUser gets the auth mapping for the user with this username.
 // The user's auth mapping includes the permissions of the `anonymous` and
 // `logged-in` groups.
 // If there is no user with this username in the db, this function will NOT
 // throw an error, but will return only the auth mapping of the `anonymous`
 // and `logged-in` groups.
-func authMapping(db *sqlx.DB, username string) (AuthMapping, *ErrorResponse) {
+func authMappingForUser(db *sqlx.DB, username string) (AuthMapping, *ErrorResponse) {
 	mappingQuery := []AuthMappingQuery{}
 	stmt := `
 		SELECT DISTINCT resource.path, permission.service, permission.method

arborist/server.go

@@ -257,7 +257,7 @@ func (server *Server) handleAuthMappingGET(w http.ResponseWriter, r *http.Reques
 
 	usernameProvided := username != ""
 	if usernameProvided {
-		mappings, errResponse := authMapping(server.db, username)
+		mappings, errResponse := authMappingForUser(server.db, username)
 		if errResponse != nil {
 			errResponse.log.write(server.logger)
 			_ = errResponse.write(w, r)
@@ -348,7 +348,7 @@ func (server *Server) handleAuthMappingPOST(w http.ResponseWriter, r *http.Reque
 	if clientID != "" {
 		mappings, errResponse = authMappingForClient(server.db, clientID)
 	} else {
-		mappings, errResponse = authMapping(server.db, username)
+		mappings, errResponse = authMappingForUser(server.db, username)
 	}
 	if errResponse != nil {
 		errResponse.log.write(server.logger)

docs/openapi.yaml

@@ -24,10 +24,13 @@ paths:
         Return a mapping from the resources the specified user can access, to
         the actions which they are authorized for on those resources. This includes
         the mappings available to members of the `anonymous` and `logged-in` groups, 
-        which apply to all users (anonymous) and to all logged-in users (logged-in). 
+        which apply to all users (anonymous) and to all logged-in users (logged-in). This endpoint accepts a username in a token in the Authorization header.
 
 
-        This endpoint accepts a username in a token in the Authorization header.
+        Note: Tokens which are linked to both a user and a client (token belonging to a client acting on behalf of a user) are supported, but the client's access is NOT taken into account. Only the user's access is returned.
+
+
+        Note that this endpoint does NOT support tokens generated through the OIDC "client_credentials" grant, which are linked to a client but not to a user. Calling this endpoint with such a token will not return the client's access.
 
 
         If the specified user is not recognized by arborist, this endpoint returns
@@ -64,8 +67,22 @@ paths:
         - auth
       description: >-
         Return a mapping from the resources the specified user or client can access, to
-        the actions which they are authorized for on those resources. This endpoint accepts
-        a username OR a client ID in the body, but not both.
+        the actions which they are authorized for on those resources. This endpoint accepts a token in the Authorization header or information in the request body.
+
+
+        Note: Tokens which are linked to both a user and a client (token belonging to a client acting on behalf of a user) are supported, but the client's access is NOT taken into account. Only the user's access is returned.
+
+
+        Note: This endpoint supports tokens generated through the OIDC "client_credentials" grant, which are linked to a client but not to a user. The client's access is returned.
+
+
+        If a token is provided and is linked to a user (regardless of whether it is also linked to a client), the user's mapping is returned.
+
+
+        If a token is provided and is linked to a client but is NOT linked to a user, the client's mapping is returned.
+
+
+        If no token is provided, this endpoint accepts a username OR a client ID in the body, but not both.
 
 
         For users (not for clients), this includes
@@ -80,6 +97,8 @@ paths:
         If the specified client is not recognized by arborist, this endpoint returns
         an empty response.
 
+
+        Note: accepting a username or client ID in the body means that anyone can check anyone's authorization if they have their username. For this reason, this API is not meant to be exposed publicly.
       requestBody:
 
         content:
@@ -133,13 +152,13 @@ paths:
         and the client have permission can the response be positive. 
 
 
-        IMPORTANT NOTE: Under `body` you can now also check authorization of 
-        a user given just the username using the field `user_id` instead of 
+        Note: Under `body` we can also check authorization of
+        a user given their username, using the field `user_id` instead of
         using `token`. This means that anyone can check anyone's authorization
-        if they have their username. For this reason, this API is not meant to 
-        be fully exposed publically. Arborist does not currently have 
+        if they have their username. For this reason, this API is not meant to
+        be exposed publicly. Arborist does not currently have
         authorization for the management of the authorization in the system.
-        The service itself does not provide a way to expose only certain parts 
+        The service itself does not provide a way to expose only certain parts
         of the API to super admins vs admins.
       requestBody:
         content:

docs/username.md

@@ -22,6 +22,8 @@ If we need the list of anonymous or logged-in policies, we can hit the `group/{g
 
 ## GET, POST auth/mapping and GET, POST auth/resources endpoints
 
+> Note: The rationale described in this document is still accurate, but some of the statements below may be outdated. Check the [API documentation](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/uc-cdis/arborist/master/docs/openapi.yaml#/) for the latest behavior of each endpoint.
+
 The GET `auth/mapping` endpoint accepts a username as an optional query parameter. If the username is not specified, we try to get it from the JWT in the 'Authorization' header.
 The GET `auth/resources` endpoint only passes the username in a JWT in the 'Authorization' header. 
 The POST `auth/mapping` and POST `auth/resources` endpoints pass the username in the request body.