Skip to content

Use Case & User Stories: Unauthorized Access Handling
Use Case ID: UC-09
Use Case Name: Respond to a Failed Permission Check
Feature: Unauthorized Access Handling
Actors: System (Primary), All Authenticated Users (Secondary)

1. Use Case Description

This use case describes the standardized, system-wide procedure that is automatically triggered whenever a user's action fails a permission check. It is a non-functional, security-critical process that ensures the system responds in a consistent, predictable, and safe manner when a user attempts to access a resource or perform an action for which they are not authorized. The system's response is context-aware, handling page-level and API-level access denials differently to maintain both security and a good user experience.

2. User Stories

  • US-35: Consistent and Clear Access Denial Feedback > As a user, > I want to see a clear and consistent "Access Denied" message whenever I try to access something I'm not supposed to, > so that I understand why I cannot proceed and am not left confused by a broken page or a technical error.

  • US-36: Prevent Information Leakage in Error Messages > As an IT Security Officer, > I want the "Access Denied" page to be generic and to explicitly not reveal the specific permission the user was missing, > so that we do not leak potentially sensitive information about the system's security structure to unauthorized users.

  • US-37: Proactive UI Security (Graceful Degradation) > As a user, > I want the user interface to proactively hide or disable buttons and links for actions I'm not allowed to perform, > so that I am not even given the opportunity to click on something that will result in an error, leading to a smoother experience.

  • US-38: Secure Backend Enforcement > As a System Architect, > I want the backend API to authoritatively reject any unauthorized request with a standard HTTP 403 Forbidden status code, > so that our security does not rely on the client-side UI alone and cannot be bypassed by a malicious user.

3. Preconditions

  • A user is authenticated and has an active session (UC-01).
  • The user initiates an action that requires a specific permission.
  • The system performs a permission check as defined in UC-04, and the check fails (the required permission is absent from the user's effective permissions).

4. Postconditions

  • The user's attempted action is immediately and completely halted.
  • The user is presented with a clear, safe, and context-appropriate notification of the access denial.

5. Scenarios and System Responses

This use case is best described through its scenarios, as the system's response is entirely dependent on the context of the failed permission check.

  • Scenario A: User Attempts to Access a Restricted Page via URL

    • Trigger: A user, Bob, who lacks the user:create permission, is sent a direct link to the "/users/create" page and clicks it.
    • System Response:
      1. The system receives the navigation request.
      2. The permission check for user:create fails.
      3. The system immediately halts the navigation to the creation page.
      4. The system redirects the user's browser to the standard "Access Denied" page.
      5. This page displays a generic message like "Sorry, you do not have the necessary permissions to view this page" and provides a link to return to the dashboard. It does not say "you are missing user:create".

  • Scenario B: User Attempts an Unauthorized API Action (Backend Enforcement)

    • Trigger: A user, Carol, who can view the user list but cannot create users, sees the "Create New User" button is disabled. She uses browser developer tools to manually enable the button and clicks it.
    • System Response:
      1. The user's browser sends an API request (e.g., POST to /api/users) to the server.
      2. The backend server receives the request and performs its own authoritative permission check for user:create on Carol's session. The check fails.
      3. The server immediately halts the action. No new user record is created.
      4. The server rejects the request and returns an HTTP 403 Forbidden status code to the browser.
      5. The UI, upon receiving the 403 error, displays a non-disruptive "toast" notification with a message like "Action failed: Insufficient permissions." The user remains on the User Listing page.

  • Scenario C: Graceful Degradation (Preventative Measure)

    • Trigger: A user, Carol, who has user:view:list but not user:create or user:edit, navigates to the User Listing page.
    • System Response:
      1. The system renders the page and checks Carol's permissions for the actions available on that page.
      2. The system finds she is missing user:create, so the "Create New User" button is rendered as disabled (greyed out) or is not rendered at all.
      3. The system finds she is missing user:edit, so the "Edit" button does not appear on any user row.
    • Outcome: The UI proactively prevents Carol from attempting actions she is not permitted to perform, creating a cleaner user experience.