In this project, you will add authentication and authorization to the persistent marketplace. You will explore how a separate login service issues JSON Web Tokens (JWTs), how the marketplace verifies them, and how one shared wrapper can protect several REST routes.

Clone the repository https://github.com/wngjia/ece573-prj03.git that holds scripts and source code for Project 3. Similar to Project 1 and 2, please create a new VM by importing our VM Appliance, make a clone of the repository (or fork it first), and provision the instance with the script setup_vm.sh.

It is optional to incorporate your completed Project 2 into Project 3 in order to support all functionalities. If you have completed Project 2, you may copy your completed versions into Project 3, assuming you have cloned your Project 2 into your home directory like the Project 3:

ubuntu@ubuntu24:~/ece573-prj03$ cp ../ece573-prj02/marketplace-service/marketplace/accounts.go marketplace-service/marketplace/accounts.go
ubuntu@ubuntu24:~/ece573-prj03$ cp ../ece573-prj02/marketplace-service/marketplace/orders.go marketplace-service/marketplace/orders.go

Briefly review our README.md, either in its textual form, or directly on GitHub as a web page. Execute the script run_baseline.sh from the project directory to run the starter baseline:

ubuntu@ubuntu24:~/ece573-prj03$ ./run_baseline.sh
...
Starter baseline completed.
Responses are saved in out/.
The Project 2 account assembly and credit check remain TODOs.
The services are stopped; the Postgres volume and signing keys are preserved.

Open 'docker-compose.yml' to understand the architecture of our marketplace with added support of authentication and authorization. It defines three services: postgres and marketplace-service similar to that of Project 2, and a login service to authenticate users. The two Go services are built from separate targets in the root Dockerfile so that both can use the shared 'auth' package, which takes care of handling JWTs.

Read the source files for the login service. The login service owns registration, password verification, and JWT issuance. Registration creates an account with zero credits and a regular-user role. The supplied helpers hash passwords with Argon2id and sign JWTs using an Ed25519 private key. It creates 'course-admin' on startup if the account doesn't exist and updates the password based on 'secrets/admin-password', which may be regenerated randomly by the reset script. Then, the login service will serve two RESTful endpoints, POST /accounts for registration and POST /login that issues a JWT Bearer token upon successful login. Follow-up RESTful requests should include the JWT to identify the user.

Since we haven't implemented authorizations in the marketplace service yet, run_baseline.sh sets the environment variable AUTH_ENABLED=false so that the first run could proceed without triggering the unfinished authorizations. Later on, to experiment with authorizations, set AUTH_ENABLED=true when starting the services:

ubuntu@ubuntu24:~/ece573-prj03$ ./scripts/reset.sh
...
Signing keys and admin password rotated.
Services are stopped. Run ./scripts/start.sh to use the new secrets.
Database reset. Admin password is in secrets/admin-password.
ubuntu@ubuntu24:~/ece573-prj03$ AUTH_ENABLED=true ./scripts/start.sh
...
Marketplace service is ready at http://127.0.0.1:8080.
Login service is ready at http://127.0.0.1:8081.
ubuntu@ubuntu24:~/ece573-prj03$ ./scripts/create-account.sh Alice
Password: 
{"account_id":"Alice","balance":0,"role":"user"}
ubuntu@ubuntu24:~/ece573-prj03$ ./scripts/login.sh Alice
Password: 
{"access_token":"*hidden*","expires_in":1800,"token_type":"Bearer"}

The marketplace service retains four RESTful endpoints from Project 2, including GET /listings, POST /listings, POST /orders, and GET /accounts/{account_id}, and also adds POST /accounts/{account_id}/credits. While anyone can use GET /listings, only specific users can access the other four when AUTH_ENABLED=true. In short, only regular users may list or buy, users may only view their own accounts, and only the admin may grant positive credits to regular users.

Read 'marketplace-service/main.go' first to see the route table. It includes all routes when AUTH_ENABLED=false, and one route for AUTH_ENABLED=true as the example. A 'TODO Project 3' comment indicates that you will need to complete the other three routes requiring authorizations based on the example. Without knowing the detail of the authorization wrapper 'requireAuthorization', please make reasonable guess on its parameters and then complete this TODO item.

Now we are ready to review 'marketplace-service/authorization.go' to understand and implement the authorization wrapper 'requireAuthorization'. This function uses the decorator pattern as we have introduced in the lectures to add authorization to any RESTful handler function ('http.HandlerFunc'). The supplied code extracts the JWT token from request header and verifies it. The 'TODO Project 3' requires you to write a few lines of code to check whether the token's subject and role are permitted using the filters 'matchesID' and 'allowsRole', before proceeding to the requested marketplace operation 'next'. Make sure to generate specific error response for failures: return HTTP 400 ('http.StatusBadRequest') if the filter reports an invalid identity field, and return HTTP 403 ('http.StatusForbidden') if the operation is not permitted.

After you have completed both Project 3 TODOs, run acceptance.sh and attack.sh to verify the correctness.

ubuntu@ubuntu24:~/ece573-prj03$ ./acceptance.sh
Project 3 acceptance test passed.
Responses are saved in out/.
Services are stopped; the Postgres volume and signing keys are preserved.
ubuntu@ubuntu24:~/ece573-prj03$ ./attack.sh
Project 3 attack test passed.
Responses are saved in out/attack/.
Services are stopped; the Postgres volume and signing keys are preserved.

1. Wrong-password login (401).
2. A regular user cannot grant credits (403).
3. Admin cannot grant credits to an admin account (400).
4. A missing token cannot create a listing (401).
5. An invalid token cannot create a listing (401).
6. Bob cannot create a listing for Alice (403).
7. Admin cannot create a listing (403).
8. Alice cannot place an order for Bob (403).
9. Admin cannot place an order (403).
10. Alice cannot read Bob's account (403).

Prepare a project report in .doc/.docx or .pdf format and submit it to Canvas before the deadline. Your project report should include the following for a total of 15 points:

• Section II
  • (1 point) Explain the purpose of the package argon2 used in the login service. Why don't the login service store the password directly into the database?
  • (1 point) Explain why login holds the private signing key while marketplace has only the public verification key.
  • (1 point) Among stopping and restarting services, rotating secrets while retaining the database, and resetting everything, which operations invalidate existing JWTs? Which delete account data?
  • (1 point) How to update password for course-admin? How to update password for other users?
• Section III
  • (1 point) Explain why we use the authorization wrapper instead of modify each RESTful handler.
  • (1 point) Referring to 'marketplace-service/main.go' and 'marketplace-service/authorization.go', explain how 'allowRole', 'allowAny', 'matchBody', 'matchPath', 'matchAny' work. In particular, why 'POST /orders' should use 'matchBody' and 'GET /accounts/{account_id}' should use 'matchPath'?
  • (2 point) Show the lines of code you have added for the authorization wrapper and the three protected routes. Explain each route's identity and role rules and how it is checked in the wrapper.
  • (2 points) Provide evidences of successful acceptance.sh and attack.sh runs. Show representative responses while redact passwords and JWTs from screenshots.
  • (5 points total; 0.5 point per test) For each of attack tests 1 to 10, identify the file and line(s) containing the decision that rejects the request. Explain the condition, the resulting HTTP status, and whether the marketplace business handler runs, when applicable.