API Security: Authentication Basics

1. A Quick Refresher: Authentication vs. Permissions

Before we dive into the code, it's crucial to be crystal clear on the distinction between authentication and permissions. They work together, but they are not the same thing.

To summarize the key idea:

• Authentication is about identity. It answers the question, "Who are you?". The system checks your credentials (like a username/password or a token) and attaches a user object (request.user) to the incoming request. It doesn't, by itself, grant or deny access.
• Permissions (or Authorization) is about access rights. It answers the question, "What are you allowed to do?". It uses the identity provided by the authentication step to decide if the requested action is permitted.

Today, we are focusing on the simplest and most common permission check: is the user identified as an authenticated user, or are they anonymous?

2. DRF's Built-in Permissions for Authentication Status

Django REST Framework (DRF) provides a set of pre-built permission classes for the most common use cases, so you don't have to write them from scratch every time.

Here’s a quick breakdown:

• permissions.IsAuthenticated: This class is very straightforward. It will deny access to any unauthenticated (anonymous) user and allow access otherwise. This is your go-to choice for endpoints that should be completely private and accessible only to registered users of your application (e.g., a user's profile page, a list of their private orders).

• permissions.IsAuthenticatedOrReadOnly: This class is slightly more nuanced. It will allow any user (authenticated or not) to perform read-only requests (GET, HEAD, OPTIONS). However, for any action that modifies data (POST, PUT, PATCH, DELETE), the user must be authenticated. This is perfect for public APIs where you want everyone to be able to see the data, but only registered users can contribute or make changes (e.g., a blog, a public forum).

3. Implementing IsAuthenticated

Let's see how easy it is to protect an endpoint. Imagine you have a view that shows a user their order history. This is sensitive data that should absolutely not be public.

The following video demonstrates how to apply the IsAuthenticated permission to a view and what happens when an unauthenticated user tries to access it.

As you saw in the video, applying the permission is as simple as adding a permission_classes attribute to your view:

# In your views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated

class UserOrdersView(APIView):
    # This line is the key. DRF will run this permission check for every request to this view.
    permission_classes = [IsAuthenticated]

    def get(self, request, format=None):
        # Because of the permission class, we can now be certain that
        # `request.user` is an authenticated user instance.
        user = request.user
        orders = get_orders_for_user(user) # Your business logic here
        serializer = OrderSerializer(orders, many=True)
        return Response(serializer.data)

When an unauthenticated user tries to GET /api/user-orders/, they will be denied. The browsable API shows a clear message: "Authentication credentials were not provided."

4. Under the Hood: 401 Unauthorized vs. 403 Forbidden

When a permission check fails, DRF returns an error response. You'll typically see one of two HTTP status codes: 401 Unauthorized or 403 Forbidden. While they seem similar, they have distinct meanings, and understanding them is key for building robust APIs.

In essence:

• 401 Unauthorized: This response means "You need to authenticate to access this." The request has failed because it lacks valid authentication credentials. This is often sent when no credentials were provided at all. It usually includes a WWW-Authenticate header telling the client how to authenticate (e.g., "Use a Bearer token").
• 403 Forbidden: This response means "I know who you are, but you are not allowed to perform this action." The system successfully authenticated you, but you simply don't have the necessary permissions for this specific resource.

DRF's default behavior, as seen in the video, is often to return a 403 response even if the user is not authenticated. The exact code depends on the configured authentication schemes, but the key takeaway is that the client is being told they cannot access the resource.

5. Testing Your Permissions (The Right Way)

You should never assume your security works. You must prove it with tests. Writing automated tests for permissions is a critical skill for any backend developer.

A good test suite for a protected endpoint should verify two scenarios:

1. An unauthenticated user is blocked (receives a 403 or 401).
2. An authenticated user is allowed access (receives a 200).

Here's an example of what those tests would look like in your tests.py file, based on the video:

# In your tests.py
from rest_framework.test import APITestCase
from rest_framework import status
from django.urls import reverse

class UserOrdersViewTests(APITestCase):

    def test_unauthenticated_user_cannot_access_orders(self):
        """
        Verify that an unauthenticated request to the user-orders endpoint is denied.
        """
        url = reverse('user-orders') # Assuming you named your URL 'user-orders'
        response = self.client.get(url)
        
        # We expect to be forbidden from accessing this endpoint
        self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)

    def test_authenticated_user_can_access_orders(self):
        """
        Verify that an authenticated user can successfully access the endpoint.
        """
        # Create a user and authenticate the client
        user = User.objects.create_user(username='testuser', password='password123')
        self.client.force_login(user)
        
        url = reverse('user-orders')
        response = self.client.get(url)

        # We expect a successful response
        self.assertEqual(response.status_code, status.HTTP_200_OK)

By writing these two simple tests, you create a safety net that guarantees your endpoint is, and remains, secure against unauthenticated access.

Conclusion

In this lesson, you've mastered the most fundamental aspect of API authorization: securing endpoints based on a user's authentication status. This is a non-negotiable skill for building any real-world backend system.

Key Takeaways:

• Authentication identifies, Permissions authorize. They are separate but related concepts.
• DRF provides powerful, reusable, built-in permission classes like IsAuthenticated and IsAuthenticatedOrReadOnly.
• You can secure an entire view simply by adding the permission_classes attribute.
• Understanding the difference between 401 Unauthorized and 403 Forbidden helps you debug and build better APIs.
• Always write automated tests to verify that your security rules are correctly enforced for both unauthenticated and authenticated users.

Preview of the Next Lesson:
We've now covered how to check if a user is logged in. But what if you need to be more specific? In our next lesson, we will build on this foundation to secure endpoints based on a user's role or specific permissions, using tools like IsAdminUser and Django's group system.