Forem: Pratusha Raya

Overview of Web Accessibility Guidelines: Tools, Techniques & Best Practices for EAA & WCAG Compliance

Pratusha Raya — Wed, 23 Jul 2025 19:20:21 +0000

Accessibility is not just a feature - it's a fundamental human right.

With the European Accessibility Act (EAA) in force, digital accessibility is now a legal and ethical expectation. If you develop or manage websites or apps, this article will help you align with WCAG 2.1 AA standards and ensure inclusive design for users with disabilities.

This guide covers:

Key WCAG criteria every developer should know
Tools like FastPass and NVDA
A practical accessibility testing checklist
40+ actionable best practices

Let’s explore how to design and build with accessibility in mind.

What Is the European Accessibility Act?

The EAA mandates that digital products and services must be accessible across the EU, aligning with WCAG 2.1 AA guidelines. It applies to:

Websites and apps
E-commerce platforms
Banking, transport, and ticketing systems
Communication services

The goal is simple: equal access for all, including those with visual, motor, cognitive, and auditory impairments.

Accessibility Testing Tools

FastPass (Accessibility Insights for Web)

FastPass is a browser extension by Microsoft that performs automated WCAG checks.

Steps to Use:

Install Accessibility Insights for Web.
Open your app and run FastPass from the extension.
Fix reported Failures and Warnings using guidance provided.

Ideal for early-stage and pre-release accessibility scans.

NVDA (NonVisual Desktop Access)

NVDA is a free screen reader for Windows that simulates how blind users experience your app.

Try This:

Download from nvaccess.org
Launch with Ctrl + Alt + N
Navigate using:
— Tab, Shift + Tab: move between elements

— Insert + F7: view headings and landmarks

Listen for how labels, buttons, and alerts are announced

Summary: Key WCAG Guidelines to Verify

1.1.1 — Non-text Content: Provide text alternatives for images/icons.
1.3.1 — Info & Relationships: Use semantic HTML to convey structure.
1.3.3 — Sensory Characteristics: Don’t rely only on color, shape, or position.
1.4.3 — Contrast (Minimum): Ensure 4.5:1 text-to-background contrast.
1.4.10 — Reflow: No horizontal scroll at 320px screen width.
1.4.12 — Text Spacing: Page remains usable with increased line/letter spacing.
2.1.1 — Keyboard: All features must work with just a keyboard.
2.4.1 — Bypass Blocks: Add “Skip to content” or similar mechanism.
2.4.3 — Focus Order: Focus moves in logical, predictable order.
2.4.4 — Link Purpose: Link text is meaningful in context.
2.4.5 — Label in Name: Visible label must be part of the accessible name.
2.4.7 — Focus Visible: Show focus with a clear visible indicator.
3.3.1 — Error Identification: Clearly explain input errors to users.
3.3.2 — Labels or Instructions: Provide helpful labels/instructions for inputs.
4.1.1 — Parsing: Use clean, valid HTML (no duplicate IDs, unclosed tags).
4.1.2 — Name, Role, Value: Components expose accessible name/role/state.
4.1.3 — Status Messages: Notify users via ARIA live regions for updates.

40+ Best Practices to Ensure Accessibility and Points to Remember

Semantic Structure & Content

Use alt attributes for images to describe their purpose.
Avoid using div or span when semantic elements like button or nav are appropriate.
Use headings (h1 — h6) in a logical, hierarchical order.
Use meaningful link text — avoid vague phrases like “click here” or “read more”.
Include lang attributes on the element.
Avoid using tables for layout purposes.
Group related form elements using
and .

Keyboard Accessibility

Ensure all interactive elements (links, buttons, forms) can be used with a keyboard.
Use a visible focus indicator to highlight the element currently in focus.
Ensure links and buttons are clearly distinguishable and usable with keyboard navigation.
Ensure pressing the Enter key on a button triggers the expected action.
Ensure keyboard users can escape or close dialogs with the Escape key.
Use aria-disabled=“true” (not just disabled) for elements that should appear inactive but visible.

Screen Reader Support

Regularly test with screen readers (NVDA) and other tools.
Screen readers should announce actions taken by users (e.g., clicks, form submissions).
Screen readers should read out error messages and alerts.
Ensure the screen reader reads out form field requirements and validations.
Make sure all form inputs have appropriate labels for screen readers.
Ensure focus is returned to the triggering element after closing modals.
Ensure dynamic content updates do not steal focus unexpectedly.
Ensure all tooltips, popovers, and custom widgets are accessible.

Forms & Validation

Use clear and predictable labels for forms, menus, and buttons.
Make sure all form inputs have appropriate labels for screen readers.
Screen readers should read out error messages and alerts.
Ensure the screen reader reads out form field requirements and validations.
Group related form elements using
and . Provide captions and transcripts for audio and video content.

ARIA & Live Regions

Implement ARIA roles, properties, and states where required without overusing them.
Use live regions (aria-live) to announce updates dynamically for assistive technologies.
Use role=“alert” sparingly and only for critical messages.
Use aria-disabled=“true” to disable elements while keeping them in focus order.

Visual Design & Contrast

Maintain sufficient color contrast between text and background.
Avoid relying solely on color to convey meaning. Use text or icons for additional clarification.
Use accessible icons with clear alternative text for non-text content.
Add focus indicators for all interactive elements.
Ensure text spacing adheres to accessibility requirements.

Responsive Design & Zoom

Ensure the interface is usable on various screen sizes and orientations.
Do not introduce horizontal scrollbars.
Use em or rem units for scalable elements instead of fixed pixel sizes.
Make content resizable and ensure no content is lost when zoomed in on a page.

Navigation & Landmarks

Maintain a consistent structure and navigation across pages.
Provide skip links or landmark regions for quick navigation.

Media & Motion

Do not auto-play media without user interaction or a clear stop control.
Provide captions and transcripts for audio and video content.

General Accessibility Testing

Ensure compatibility with multiple browsers and devices.
Regularly test with screen readers (NVDA) and other tools.

Dev Checklist (Quick Reference)

Alt text on all images
Keyboard access to all features
Visible focus indicator
Logical tab order
Modals behave properly
Forms are labeled and errors announced
Contrast and spacing meet guidelines
App reflows at 320px width
NVDA test passes for labels, forms, dynamic content

If you found this useful:

Drop a comment
Share with your team

Thank you!

Secure Your Spring Boot API with JWT and Role-Based Authorization

Pratusha Raya — Mon, 21 Jul 2025 18:25:17 +0000

Originally published on Medium

Securing your REST API is essential for protecting sensitive data and ensuring only authorized users can access your endpoints. In this article, you'll learn how to secure a Spring Boot API using JSON Web Tokens (JWT) with role-based authorization, clear error handling, and best practices.

Project Setup

Create a Spring Boot project with the following dependencies:

Spring Web
Spring Security
jjwt (add to pom.xml):

<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt</artifactId>
  <version>0.9.1</version>
</dependency>

DTO for Login

package com.example.jwtsecuritydemo;

//DTO for login requests. Used to receive username and password as JSON.
public class LoginRequest {
    private String username;
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

JWT Utility

package com.example.jwtsecuritydemo;

import javax.crypto.spec.SecretKeySpec;
import java.security.Key;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

import java.util.Date;

//Utility class for JWT operations: generate, validate, and extract claims.
public class JwtUtil {
    private static final String SECRET_KEY = "my-super-secret-key-for-jwt";
    private static final long EXPIRATION_TIME = 3600000; // 1 hour
    private static final SignatureAlgorithm SIGNATURE_ALGORITHM = SignatureAlgorithm.HS256;
    private static final Key key = new SecretKeySpec(SECRET_KEY.getBytes(), SIGNATURE_ALGORITHM.getJcaName());

    public static String generateToken(String username, String role) {
        return Jwts.builder()
                .setSubject(username)
                .claim("role", role)
                .setIssuedAt(new Date())
                .setExpiration(new Date(System.currentTimeMillis() + EXPIRATION_TIME))
                .signWith(SIGNATURE_ALGORITHM, key)
                .compact();
    }

    public static boolean validateToken(String token) {
        try {
            Jwts.parser()
                .setSigningKey(key)
                .parseClaimsJws(token);
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    public static String getUsernameFromToken(String token) {
        return Jwts.parser()
                .setSigningKey(key)
                .parseClaimsJws(token)
                .getBody()
                .getSubject();
    }

    public static String getRoleFromToken(String token) {
        Claims claims = Jwts.parser()
                .setSigningKey(key)
                .parseClaimsJws(token)
                .getBody();
        return claims.get("role", String.class);
    }
}

Authentication Controller

package com.example.jwtsecuritydemo;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/auth")
public class AuthController {

    @PostMapping("/login")
    public ResponseEntity<?> login(@RequestBody LoginRequest loginRequest) {
        String username = loginRequest.getUsername();
        String password = loginRequest.getPassword();
        String role = "admin".equals(username) ? "ROLE_ADMIN" : "ROLE_USER";
        if (("admin".equals(username) && "password".equals(password)) ||
            ("user".equals(username) && "password".equals(password))) {
            String token = JwtUtil.generateToken(username, role);
            return ResponseEntity.ok().body(token);
        }
        return ResponseEntity.status(401).body("Invalid credentials");
    }
}

JWT Filter

package com.example.jwtsecuritydemo;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.Collections;

public class JwtFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        String token = request.getHeader("Authorization");
        if (token != null && token.startsWith("Bearer ")) {
            token = token.substring(7);
            if (JwtUtil.validateToken(token)) {
                String username = JwtUtil.getUsernameFromToken(token);
                String role = JwtUtil.getRoleFromToken(token);
                SimpleGrantedAuthority authority = new SimpleGrantedAuthority(role);
                UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(
                        username, null, Collections.singletonList(authority));
                SecurityContextHolder.getContext().setAuthentication(auth);
            }
        }
        chain.doFilter(request, response);
    }
}

Security Configuration

package com.example.jwtsecuritydemo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableMethodSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                .csrf(csrf -> csrf.disable())
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/auth/login").permitAll()
                        .anyRequest().authenticated()
                )
                .sessionManagement(sess -> sess.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .addFilterBefore(new JwtFilter(), UsernamePasswordAuthenticationFilter.class)
                .build();
    }
}

Global Exception Handler

package com.example.jwtsecuritydemo;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.ResponseStatus;

import jakarta.servlet.ServletException;
import java.io.IOException;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(AccessDeniedException.class)
    @ResponseStatus(HttpStatus.FORBIDDEN)
    @ResponseBody
    public ResponseEntity<?> handleAccessDeniedException(AccessDeniedException ex) {
        return ResponseEntity.status(HttpStatus.FORBIDDEN)
                .body("Access denied: " + ex.getMessage());
    }

    @ExceptionHandler({ServletException.class, IOException.class})
    @ResponseStatus(HttpStatus.UNAUTHORIZED)
    @ResponseBody
    public ResponseEntity<?> handleServletException(Exception ex) {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body("Unauthorized: " + ex.getMessage());
    }
}

Secured Endpoints

HelloController.java

package com.example.jwtsecuritydemo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello! You have accessed a secured endpoint.";
    }
}

SecuredController.java

package com.example.jwtsecuritydemo;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
public class SecuredController {

    @PreAuthorize("hasAuthority('ROLE_ADMIN')")
    @GetMapping("/secure-data")
    public String secureData() {
        return "Access granted to admin user!";
    }
}

Main Application

package com.example.jwtsecuritydemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class JwtsecuritydemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(JwtsecuritydemoApplication.class, args);
    }
}

Testing with curl

Login as admin:

curl -X POST http://localhost:8080/auth/login -H "Content-Type: application/json" -d "{\"username\":\"admin\",\"password\":\"password\"}"

Login as user:

curl -X POST http://localhost:8080/auth/login -H "Content-Type: application/json" -d "{\"username\":\"user\",\"password\":\"password\"}"

Access public endpoint:

curl -H "Authorization: Bearer <TOKEN>" http://localhost:8080/hello

Access admin-only endpoint (should succeed for admin, fail for user):

curl -H "Authorization: Bearer <TOKEN>" http://localhost:8080/api/secure-data

Conclusion

You now have a robust, stateless, and role-based JWT security setup for your Spring Boot API. This approach is scalable, production-ready, and easy to extend for real-world applications.

What You Gain from This Article

Practical Security: A hands-on, production-ready template for securing any Spring Boot API using JWT and role-based access control.
Scalability: Stateless JWT approach ideal for microservices, cloud deployments, and modern distributed systems.
Extensibility: Modular code that’s easy to extend — add refresh tokens, integrate databases, or connect OAuth providers.
Best Practices: Use of DTOs, global exception handling, and method-level security—all industry standards.

Who Should Use This Guide

Java/Spring Boot developers looking to secure APIs quickly and correctly.

Backend engineers building microservices or RESTful APIs.

Students and learners wanting a clear, step-by-step JWT security example.

Architects and tech leads seeking a reference implementation.

How to Get the Most Out of This Article

Try the curl commands to see the authentication flow in action.

Fork and extend the code — add user registration, connect to a real database, or implement refresh tokens.

Share your feedback or questions in the comments—let's learn together!

Bonus: What’s Next?

Interested in:

Integrating with OAuth2 or social login?

Adding refresh tokens?

Using JWT with GraphQL or WebSockets?

Deploying this setup to the cloud?