Resolving JWT Refresh Token Handling in Angular with HttpInterceptor

Ensuring Seamless JWT Refresh in Angular Interceptors

In a web app with secure user sessions, managing short-lived JWT tokens effectively is crucial for uninterrupted user experience. When tokens expire, users often encounter issues such as being forced to re-login, which can be frustrating and disrupt user engagement. To tackle this, developers commonly implement automatic token refresh using an Angular interceptor to handle expired sessions. 🕰️

This approach involves intercepting HTTP requests, catching 401 errors (unauthorized requests), and then invoking a refresh process to obtain a new token. However, issues can arise in ensuring the updated token or cookie is applied to the retried requests. If the new token doesn’t propagate correctly, the retry may fail, leaving users with the same authorization error and potentially disrupting app workflows.

In this guide, we'll walk through a practical implementation of this interceptor pattern. We’ll look at how to catch errors, refresh tokens, and confirm that requests retry with valid authorization. This approach minimizes interruptions while giving you control over the session renewal process.

By the end, you’ll gain insights into how to address common pitfalls, like handling HttpOnly cookies and managing refresh sequences during high request volumes. This method ensures your application can maintain a secure, smooth user session without constant logins. 🔒

Ensuring Reliable JWT Authentication with Angular Interceptors

In the example above, the interceptor is designed to automatically refresh a short-lived JWT token whenever a 401 error is encountered. This kind of setup is essential in applications with sensitive data, where maintaining session security is critical, but the user experience shouldn’t be interrupted. The interceptor catches the 401 (Unauthorized) error and initiates a refresh token request to renew the session without requiring the user to re-authenticate. This process is triggered by the catchError function, which allows error handling within an observable pipeline. Here, any HTTP error, specifically a 401, signals that the token has likely expired and initiates the refreshing process.

The switchMap function is another core element here; it creates a new observable stream for the refreshed request, replacing the old observable without canceling the entire flow. After refreshing, it retries the original request, ensuring that the new token is applied. By switching from the old observable to a new one, the interceptor can perform the token renewal in a seamless, non-blocking manner. This technique is particularly valuable when working with real-time applications, as it reduces interruptions in user interactions while still maintaining secure authentication. For instance, a user browsing a secured financial dashboard wouldn’t be redirected or logged out unnecessarily; instead, the new token is acquired and applied in the background. 🔄

Additionally, the BehaviorSubject plays a crucial role by managing the state of the refresh process. This RxJS utility can retain the last emitted value, which is especially helpful when multiple requests encounter a 401 error at the same time. Instead of triggering multiple refreshes, the interceptor only initiates one token refresh, and all other requests are queued to wait for this single token renewal. Using BehaviorSubject with switchMap helps ensure that if one request triggers the refresh, all other requests in need of the new token will use the updated credentials without causing repeated refresh calls. This feature is extremely helpful in cases where users may have multiple open tabs, or the app is managing several simultaneous network calls, thus saving resources and avoiding excessive server load.

Testing this interceptor logic is also essential for ensuring that it works under different scenarios, which is why we include the HttpTestingController. This Angular testing tool enables us to simulate and test HTTP responses, like the 401 Unauthorized status, in a controlled environment. Using flush, a method provided by HttpTestingController, developers can simulate real-world error responses and verify that the interceptor behaves as expected. This testing approach allows us to refine how well the refresh logic handles various cases before deploying the app. With these methods, the interceptor not only preserves the session securely but also provides a more seamless, stable experience for users navigating the app. 👩‍💻

import { Injectable } from '@angular/core';
import { HttpEvent, HttpInterceptor, HttpHandler, HttpRequest, HttpErrorResponse } from '@angular/common/http';
import { catchError, switchMap } from 'rxjs/operators';
import { Observable, throwError, BehaviorSubject } from 'rxjs';
import { AuthService } from './auth.service';
import { Router } from '@angular/router';
@Injectable()
export class JwtInterceptor implements HttpInterceptor {
  private refreshTokenInProgress$ = new BehaviorSubject<boolean>(false);
  constructor(private authService: AuthService, private router: Router) {}
  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    req = req.clone({ withCredentials: true });
    return next.handle(req).pipe(
      catchError((error: HttpErrorResponse) => {
        if (error.status === 401) {
          return this.handle401Error(req, next);
        }
        return throwError(() => error);
      })
    );
  }
  private handle401Error(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    if (!this.refreshTokenInProgress$.getValue()) {
      this.refreshTokenInProgress$.next(true);
      return this.authService.refreshToken().pipe(
        switchMap(() => {
          this.refreshTokenInProgress$.next(false);
          return next.handle(req.clone({ withCredentials: true }));
        }),
        catchError((error) => {
          this.refreshTokenInProgress$.next(false);
          this.authService.logout();
          this.router.navigate(['/login'], { queryParams: { returnUrl: req.url } });
          return throwError(() => error);
        })
      );
    }
    return this.refreshTokenInProgress$.pipe(
      switchMap(() => next.handle(req.clone({ withCredentials: true })))
    );
  }
}

import { TestBed } from '@angular/core/testing';
import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing';
import { JwtInterceptor } from './jwt.interceptor';
import { HTTP_INTERCEPTORS, HttpClient } from '@angular/common/http';
import { AuthService } from './auth.service';
describe('JwtInterceptor', () => {
  let httpMock: HttpTestingController;
  let authServiceSpy: jasmine.SpyObj<AuthService>;
  let httpClient: HttpClient;
  beforeEach(() => {
    authServiceSpy = jasmine.createSpyObj('AuthService', ['refreshToken', 'logout']);
    TestBed.configureTestingModule({
      imports: [HttpClientTestingModule],
      providers: [
        JwtInterceptor,
        { provide: HTTP_INTERCEPTORS, useClass: JwtInterceptor, multi: true },
        { provide: AuthService, useValue: authServiceSpy }
      ]
    });
    httpMock = TestBed.inject(HttpTestingController);
    httpClient = TestBed.inject(HttpClient);
  });
  afterEach(() => {
    httpMock.verify();
  });
  it('should refresh token on 401 error and retry request', () => {
    authServiceSpy.refreshToken.and.returnValue(of(true));
    httpClient.get('/test').subscribe();
    const req = httpMock.expectOne('/test');
    req.flush(null, { status: 401, statusText: 'Unauthorized' });
    expect(authServiceSpy.refreshToken).toHaveBeenCalled();
  });
});

Expanding JWT Token Refresh Strategies with Angular Interceptors

A critical aspect of using an Angular JWT token interceptor for secure applications is efficiently handling the complexities of managing authentication and session expiration. Beyond merely catching 401 errors and refreshing tokens, it's essential to think about multi-request handling and how to optimize token refreshes. When multiple requests encounter a 401 error simultaneously, implementing a queue or locking mechanism can be extremely useful to ensure only one token refresh occurs at a time. This approach prevents unnecessary API calls and reduces load, especially in high-traffic applications, while allowing all queued requests to proceed after the refresh.

Angular's interceptors also allow us to streamline how we handle token storage and retrieval. Rather than hardcoding tokens in local storage, it’s best to use Angular’s HttpOnly cookies and CSRF protection to enhance security. With HttpOnly cookies, the JWT cannot be accessed or manipulated by JavaScript, greatly improving security but adding a new challenge: ensuring that requests pick up the refreshed cookie automatically. Angular’s built-in withCredentials option is a solution, instructing the browser to include these cookies on each request.

In a production environment, it’s advisable to run performance tests on how the application behaves under load with token refreshes. Testing setups can simulate high request volumes, ensuring that the interceptor’s logic scales efficiently. In practice, this setup minimizes the risk of token-related errors impacting the user experience. The interceptor strategy, when paired with proper cookie handling and testing, helps maintain a seamless, user-friendly, and secure application—whether the app manages critical financial data or a social platform’s user sessions. 🌐🔐