Auth API V2 Design

[kzalys]

For the Auth System V2 project.

We need to design a new version of the auth API that would meet our requirements for implementing resource-oriented authorization on the Hacker Suite.

We also need to identify what operations on the version 1 of the API can be deprecated and what operations need to be removed or disabled.

Definition of done:

• Designed a new version of the API which would allow us to implement resource-oriented authorization (no implementation required).
• Identified what operations on v1 of the API need to be removed and what operations can be deprecated.
• Discussed the changes with the team and received approval.

[kzalys]

I've created a design for V2 of the hs_auth API: https://documenter.getpostman.com/view/2489646/T1DjjKP6?version=latest (each V2 operation has multiple usage examples, so check them out to fully understand what the operation does). @seanjparker @amishshah let me know what you think.

There are a couple of things to note here:

• I've expanded the use of the me keyword. Previously we were using it for GetMe and PutMe methods to perform operations on the user in the auth token. It caused a few conflicts in the router's paths in API v1. In API v2 we could use me as a special kind of id rather than creating special me operations: http://localhost:8000/api/v2/users/me would be handled by the same controller as http://localhost:8000/api/v2/users/5f1193728d049b852bc1fe5d. This means that both requests would look the same at the router level and we would not have any conflicts being caused by me operations. On the controller level, when handling requests with me instead of an id, the id would be derived from the auth token. We could reuse the me keyword for multiple types of ids (e.g.: user id would be taken from the auth token, team id could be derived by fetching the user the auth token belongs to from the database). What's more, resource-oriented authorization would allow us to very elegantly control how the me keyword is being used. The URI hs:hs_auth:api:v2:getUsers?team=me would allow a user to fetch information about all users belonging to their team but it would not allow the user to fetch information about users from other teams. Meaning that we would not need to create separate operations for fetching all users (to be used by organisers) and for fetching a user's teammates (to be used by normal users), this logic would be handled by the authorization system without any additional implementation.
• I've removed the GetTeamMember operation, as this functionality is covered by the GetUsers operations since it would support filtering the users by their team.
• Auth checks would be performed by the GetAuthorizedURIs operation. The basic idea behind is: you provide it a list of URIs and it returns a list of URIs from the initial list the user has access to. The fact that the operation expects a list of URIs means that we can use the operation for both single URI auth checks and bulk URI auth checks.
• I did not add an operation dedicated to providing user's access to specific resources. As far as I can tell, such functionality is not currently required by the Hacker Suite and the functionality provided by the SetRole operation should be enough. However, if we ever feel the need to add an operation that provides access to URIs, that can be done (though the implementation would not be the easiest thing in the world as we would need to worry about merging URIs).
• I have identified another potentially worth-while use case for metadata in the URIs. We could use metadata to determine what fields are included in the response from an operation. For example: we could use hs:hs_auth:api:v2:getUsers#forbiddenFields=email to make sure that the email addresses of the users is not included in the response. This could come in useful for managing volunteer permissions as we might want them to be able to fetch all users but we might not want them to be able to see the email addresses of all attendees.

[amishshah]

This all looks great to me! 🚀