REST API Authorization

# CHAPTER 17

REST API Authorization #

1. Introduction #

2. Learning Objectives #

• Clearly distinguish between Authentication and Authorization.

• Understand the concept of Role-Based Access Control (RBAC).

• Implement endpoint-level authorization checks in PHP.

• Implement resource-level authorization checks (Ownership).

• Return the correct HTTP status codes for authorization failures.

3. Beginner-Friendly Explanation #

• When an employee swipes their badge at the front door to get in, that is Authentication. The hospital knows it is John.

• When John tries to swipe his badge to enter the surgical ward, the door denies him because he is a janitor, not a surgeon. That is Authorization.

In our API, we need to assign "roles" (like Admin, Editor, User) to our users, and check those roles before executing the requested action.

4. Real-World Examples #

• WordPress API: A "Subscriber" can use the GET /posts endpoint to read articles. But if they try to use POST /posts to write an article, the API rejects them. Only "Authors" and "Admins" can POST.

• Banking App: You are authenticated and authorized to view your own bank account (/accounts/5). But if you try to view another user's account (/accounts/6), you are rejected because you do not own it.

5. Detailed Code Examples #

<?php
// Assume the user has been authenticated and we have their data
$currentUser = [
    &#039;id' => 5,
    &#039;name' => 'Jane',
    &#039;role' => 'standard_user' // Options: admin, editor, standard_user
];

// Endpoint: DELETE /articles/99

// 1. Endpoint-Level Authorization Check (Role Based)
if ($currentUser[&#039;role'] !== 'admin' && $currentUser['role'] !== 'editor') {
    http_response_code(403); // 403 Forbidden!
    echo json_encode(["error" => "You do not have permission to delete articles."]);
    exit;
}

// 2. Resource-Level Authorization Check (Ownership Based)
// Assume we query the database to find the article
$article = [&#039;id' => 99, 'author_id' => 8];

if ($currentUser[&#039;role'] !== 'admin' && $article['author_id'] !== $currentUser['id']) {
    http_response_code(403);
    echo json_encode(["error" => "You can only delete your own articles."]);
    exit;
}

echo json_encode(["message" => "Article deleted successfully."]);
?>

6. Request/Response Examples #

Request by standard user:

DELETE /users/10 HTTP/1.1
Authorization: Bearer valid_token_for_jane

Response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "message": "Only administrators can delete user accounts."
}

7. HTTP Examples #

• 401 Unauthorized: The client didn't send a token, or the token is expired/invalid. (Identity unknown).

• 403 Forbidden: The token is perfectly valid. The server knows who the client is, but refuses to execute the action due to lack of permissions. (Identity known, action denied).

8. JSON Examples #

{
  "user_profile": {
    "id": 5,
    "name": "Jane",
    "role": "admin",
    "permissions": ["create_post", "delete_post", "manage_users"]
  }
}

9. Best Practices #

• Deny by Default: Always assume a user DOES NOT have access to an endpoint unless your code explicitly grants them access. Never default to "allow."

• Check at the Resource Level: Just because a user has the "Editor" role doesn't mean they can edit *anything*. Always check if resource.ownerid == currentuser.id when users try to modify specific data.

• Keep Roles Simple: Start with basic roles (admin, user). Only introduce complex granular permissions (like caneditposts, canviewbilling) if the application truly requires it.

10. Common Mistakes #

• Trusting the Frontend: A beginner mistake is hiding the "Admin Panel" button in the frontend React app, but forgetting to secure the actual API endpoint. Hackers don't need buttons; they will just send a DELETE request directly to the API using cURL. ALL security MUST be enforced on the backend API.

• Using 401 instead of 403: Returning 401 for an authorization failure often causes frontend apps to force the user to log out, resulting in a terrible user experience.

11. Mini Exercises #

1. 1. Scenario: User A tries to edit User B's profile. User A sends a valid JWT token. The API should block this. What HTTP status code should be returned?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Compare and contrast 401 Unauthorized and 403 Forbidden. Give an example of when to use each.

• Q: Explain the concept of "Resource-Level" ownership authorization vs "Endpoint-Level" role authorization.

• Q: Why is it dangerous to rely on frontend logic to prevent unauthorized actions?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #