DEV Community: GeekCoding101.com

HTTP Basic Authentication Explained (RFC 7617)

GeekCoding101.com — Sat, 17 Oct 2026 16:09:54 +0000

Originally published at GeekCoding101.

Introduction

In this blog post, we will dive into HTTP Basic Authentication, a method rooted in the principles outlined in RFC 7617.

It’s worth noting that, the RFC specification defines the use of the “Authorization” header in HTTP requests to transmit the credentials. The credentials are typically sent as a Base64-encoded string of the form username:password. It also describes how servers should respond with appropriate status codes (e.g., 401 Unauthorized) when authentication fails.

How HTTP Basic Authentication Works (RFC 7617)

Before writing any code, here is the whole exchange as RFC 7617 defines it:

The client requests a protected resource without credentials.
The server answers 401 Unauthorized with a challenge header that names the scheme and a realm (a label for the protected area):

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Basic realm="admin area", charset="UTF-8"

The client joins the user ID and password with a single colon, Base64-encodes the result, and sends it in the Authorization header. For alice and s3cret:

   GET /protected HTTP/1.1
   Host: example.com
   Authorization: Basic YWxpY2U6czNjcmV0

The server decodes the value, splits it at the first colon (so the user ID itself cannot contain a colon, but the password can), and checks the pair. A match returns 200 OK; a mismatch returns 401 again.

You can produce the same header from the command line:

echo -n 'alice:s3cret' | base64          # YWxpY2U6czNjcmV0
curl -u alice:s3cret https://example.com/protected   # curl builds the header for you

A few details from RFC 7617 that tutorials often skip:

Base64 is encoding, not encryption. Anyone who sees the header can decode it in one step, so Basic Auth is only acceptable over HTTPS.
charset="UTF-8" is the only charset the server may announce, and tells the client to encode non-ASCII user names and passwords as UTF-8.
No session, no logout. The browser caches the credentials for the realm and resends them on every request until the browser is closed; there is no standard way for the server to "log out" a user.
CSRF exposure. Because the browser attaches the credentials automatically, a forged cross-site request carries them too, so state-changing endpoints still need CSRF protection.

Step 1: Setting Up the Node.js and TypeScript Environment

Please refer to the steps explained in our previous blog post Password Authentication In Node.Js: A Step-By-Step Guide at Step 1: Setting Up the Node.js and TypeScript Environment.

Step 2: Creating the Server

usersData.ts

In this file, we define a simulated database of users with their hashed passwords using bcrypt. Each user has a username and a password field.

This file acts as our database for the sake of this example.

The usage of bcrypt also has been explained in Password Authentication In Node.Js: A Step-By-Step Guide already.

interface User {
    username: string;
    password: string;
}

const users: User[] = [];

export default users;

`basicAuthMiddleware.ts`

This file contains the basic authentication middleware. The middleware is responsible for authenticating users based on the credentials provided in the Authorization header. It uses bcrypt to compare the provided password with the hashed password stored in the usersData.ts file.

import { Request, Response, NextFunction } from 'express';
import { Buffer } from 'buffer';
import bcrypt from 'bcryptjs';

interface User {
    username: string;
    password: string;
}

const basicAuthMiddleware = (users: User[]) => async (req: Request, res: Response, next: NextFunction) => {
    try {
        const authHeader = req.headers.authorization;
        if (!authHeader) {
            // If no authorization header is provided, send a 401 response with the WWW-Authenticate header
            // so that browser will pop up username/password dialog
            res.setHeader('WWW-Authenticate', 'Basic');
            return res.status(401).json({ error: 'Authorization header missing' });
          }

        const credentials = Buffer.from(authHeader.split(' ')[1], 'base64').toString('utf-8');
        const [username, password] = credentials.split(':');

        const user = users.find((user) => user.username === username);
        if (!user) {
            return res.status(401).json({ error: 'Invalid username' });
        }

        const isPasswordValid = await bcrypt.compare(password, user.password);
        if (!isPasswordValid) {
            return res.status(401).json({ error: 'Invalid password' });
        }

        next();
    } catch (error) {
        res.status(500).json({ error: 'Internal server error' });
    }
};

export default basicAuthMiddleware;

In the interest of security, a production-ready authentication system should not provide explicit feedback on whether the username or password is invalid. However, the code examples provided in this article aim to illustrate the principles of Basic Authentication based on RFC 7617 and are intended for educational purposes. They demonstrate the basic mechanics of authentication but may not fully address all security concerns.

`app.ts`

The app.ts file will set up the Express server, handles user registration, and protects a route using the basic authentication middleware.

By implementing authentication in middleware, when the middleware detects invalid credentials, it directly sends the appropriate error response, and the route handler will not be executed.

app.ts imports the users' data from usersData.ts and creates the middleware by passing the users' data as an argument to basicAuthMiddleware.

The /register will take {"username": "your_name", "password": "your_password"} as input.

The /protected endpoint is to verify account credentials.

import express from 'express';
import bodyParser from 'body-parser';
import bcrypt from 'bcryptjs';
import basicAuthMiddleware from './basicAuthMiddleware'; // Import the basicAuthMiddleware
import users from './usersData'; // Import the users data

const app = express();
const PORT = 3001;

app.use(bodyParser.json());

// User registration route
app.post('/register', async (req, res) => {
    try {
        const { username, password } = req.body;

        // Check if the user already exists
        if (users.some((user) => user.username === username)) {
            return res.status(400).json({ error: 'Username already exists' });
        }

        // Hash the password using bcrypt
        const salt = await bcrypt.genSalt(10);
        const hashedPassword = await bcrypt.hash(password, salt);

        // Save the user in the database (in this example, we're using an in-memory array)
        const newUser = { username, password: hashedPassword };
        users.push(newUser);

        res.status(201).json({ message: 'User registered successfully!' });
    } catch (error) {
        res.status(500).json({ error: 'Internal server error' });
    }
});

// Create the basicAuthMiddleware with the users array as an argument
const authMiddleware = basicAuthMiddleware(users);

// Use the authMiddleware to protect a route
app.get('/protected', authMiddleware, (req, res) => {
    res.json({ message: 'You have successfully accessed the protected route!' });
});

app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
});

3. Testing the Server

Launch the server:

npx ts-node ./app.ts

Open another terminal and run below command:

echo '{"username": "testuser01", "password": "testpassword01"}' | http POST http://localhost:3001/register

It created a user testuser01 in the server with password testpassword01.

Let’s try to access the protected URI /protected :

Goto online Base64 encode/decode website (link here), we can see the decoding results:

If trying to access from browser, the browser will pop up the username/password verification dialog automatically as below:

Pros and Cons

Pros:

Simplicity: HTTP Basic Authentication is easy to implement and understand. It requires minimal additional overhead for client and server implementations.
Standardization: It is a standardized authentication method supported by most web browsers and server frameworks.

Cons:

Security: The credentials are Base64-encoded but not encrypted. This means they can be intercepted if transmitted over an insecure network. It’s crucial to use HTTPS to mitigate this issue.
No Built-in Password Hashing: Basic Authentication does not provide built-in mechanisms for securely storing or hashing passwords. Implementing password hashing and salting is the responsibility of the application developer. Like in our article, we have to implement password hashing.
Limited Features: It lacks advanced features like multi-factor authentication (MFA) or token-based authentication, which are often needed for more robust security.
No Session Management: Basic Authentication does not manage user sessions. If session management is required, it needs to be implemented separately.
User Experience: While browsers handle the credential prompt, the user experience can be intrusive, especially for web applications.

FAQ

Is HTTP Basic Authentication secure?

Only over HTTPS. The credentials are Base64-encoded, which anyone can reverse, and they are sent with every request. Over TLS the header is encrypted in transit, which makes Basic Auth acceptable for internal tools, staging sites and machine-to-machine calls, but it still has no MFA, no expiry and no logout.

What is the format of the Basic Authorization header?

Authorization: Basic <base64(user-id:password)>, for example Authorization: Basic YWxpY2U6czNjcmV0 for alice:s3cret.

What does the server send when credentials are missing or wrong?

401 Unauthorized with WWW-Authenticate: Basic realm="...". The browser shows its login dialog when it sees this header.

Basic Auth vs Bearer tokens?

Basic sends the user's actual password on every request. A Bearer token (for example an OAuth 2.0 access token or a JWT) is a separate, revocable, usually short-lived credential, so a leaked token does far less damage than a leaked password.

Summary

HTTP Basic Authentication is a straightforward method for securing web resources. It serves well for simple use cases but may not be suitable for applications requiring more advanced security measures.

The source code of this tutorial has been uploaded to GeekCoding101 github repo as well, feel free to take a look.

In the next blog, we will explore more advanced authentication methods, including token-based authentication using JSON Web Tokens (JWT).

OAuth 2.0 Authorization Code Flow, Step by Step

GeekCoding101.com — Fri, 16 Oct 2026 16:07:42 +0000

Originally published at GeekCoding101.

Brief Description

The OAuth 2.0 authorization code flow is a secure and widely adopted method for obtaining access tokens to access user resources on behalf of the user.

Steps

Here's a summary of the steps in the authorization code flow:

Client Initiation: The client application initiates the authorization process by redirecting the user to the authorization server's authorization endpoint.
User Authentication and Consent: The user is prompted to authenticate with the authorization server and grant permission to the client application to access their resources.
Authorization Code Generation: Upon successful authentication and consent, the authorization server generates an authorization code and redirects the user back to the client application along with the authorization code.
Access Token Exchange: The client application exchanges the authorization code for an access token by making a request to the authorization server's token endpoint.
Access Token Usage: The client application uses the access token to access the user's protected resources, such as APIs or data endpoints.

To clarify, in the authorization code flow, the authorization endpoint issues an authorization code to the client application upon user consent, not an access token directly.

The Flow with Real Requests

Here is what each step looks like on the wire (RFC 6749 section 4.1, with PKCE from RFC 7636). The client is https://app.example.com, the authorization server is https://auth.example.com.

1. Redirect the user to the authorization endpoint. The client generates a random state (CSRF protection) and a random code_verifier, then sends the browser to:

GET /authorize?response_type=code
    &client_id=my-app
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
    &scope=openid%20profile%20orders.read
    &state=af0ifjsldkj
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256 HTTP/1.1
Host: auth.example.com

code_challenge is BASE64URL(SHA256(code_verifier)); the verifier itself stays with the client.

2. The user signs in and approves the requested scopes on the authorization server's own pages. The client never sees the password.

3. The server redirects back with a one-time code:

HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

The client must check that state matches the value it generated before going further.

4. The client exchanges the code for tokens over a direct back-channel call:

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXktYXBwOm15LXNlY3JldA==

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

The Authorization: Basic header carries the client ID and secret (see HTTP Basic Authentication Explained); a public client such as a single-page or mobile app has no secret and relies on PKCE alone.

5. The server returns the tokens:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "openid profile orders.read"
}

6. The client calls the API with Authorization: Bearer <access_token>, and uses the refresh token to get a new access token when it expires.

Why PKCE Is Now Recommended for Every Client

PKCE was first designed for mobile apps, which cannot keep a client secret. If an attacker intercepts the authorization code (for example through a malicious app registered for the same redirect URI), they still cannot redeem it, because the token endpoint demands the code_verifier that only the real client knows. The OAuth 2.0 Security Best Current Practice (RFC 9700) and the OAuth 2.1 draft now recommend PKCE for confidential server-side clients as well, and OAuth 2.1 drops the implicit flow entirely. See OAuth 2.0 Grant Types Explained for how the other grant types compare.

Why Authorization Code Flow Not Issue Access Token Directly?

The OAuth 2.0 authorization code flow is designed to enhance security and minimize certain risks associated with transmitting sensitive information, such as access tokens, through the user's browser or mobile device.

Here are some reasons why the authorization endpoint issues an authorization code instead of an access token directly:

Reduced Exposure of Access Tokens: Access tokens are sensitive pieces of information that grant access to the user's protected resources. By issuing an authorization code instead of an access token directly, the authorization server reduces the exposure of access tokens to potentially compromised user agents (such as web browsers or mobile apps). Since the authorization code is short-lived and can only be exchanged for tokens by the client application with its credentials, the risk associated with the interception of the authorization code is lower than if an access token were transmitted directly.
Separation of Concerns: Separating the authorization process into two steps—obtaining the authorization code and exchanging it for an access token—helps clarify the roles and responsibilities of different components in the OAuth 2.0 flow. The authorization endpoint is responsible for handling user consent and authentication, while the token endpoint is responsible for issuing access tokens based on valid authorization codes and client credentials. This separation enhances the security and maintainability of the OAuth 2.0 protocol.
Support for Additional Security Measures: The authorization code flow allows for the implementation of additional security measures, such as client authentication at the token endpoint using client credentials (client ID and client secret), which helps verify the identity of the client application before issuing access tokens. This adds an extra layer of security to the token issuance process and helps prevent unauthorized access to user resources.

Overall, by issuing an authorization code instead of an access token directly, the OAuth 2.0 authorization code flow aims to improve security, reduce exposure to sensitive information, and provide a clear separation of concerns in the authentication and authorization process.

Benefits of Authorization Code Flow

Enhanced Security: By separating the authorization and token exchange steps, it reduces the risk of exposing sensitive information, such as access tokens, during the authorization process.
User Consent: Users have control over which resources the client application can access, ensuring privacy and security.
Scalability: The authorization code flow is well-suited for a wide range of client types, including web applications, mobile apps, and desktop applications.
Refresh Token Support: It supports the use of refresh tokens, allowing clients to obtain new access tokens without requiring user interaction.

FAQ

What is the difference between the authorization code and the access token?

The authorization code is a short-lived, single-use value that travels through the browser and is useless on its own. The access token is the credential that calls the API, and it is only ever returned over the back-channel token request.

Should a single-page app use the authorization code flow?

Yes, with PKCE. The implicit flow that SPAs used to rely on returns the token in the URL and is deprecated by the OAuth 2.0 Security Best Current Practice.

What is the `state` parameter for?

It ties the callback to the request the client started, so an attacker cannot make the client accept a code from a different authorization (a CSRF attack on the callback).

How long does an authorization code live?

RFC 6749 recommends a maximum of 10 minutes, and most providers use much less. It can be redeemed once; a second attempt should make the server revoke the tokens already issued for it.