Forem: Michael M.

Access Control and Zero-Knowledge

Michael M. — Sun, 02 Mar 2025 08:00:25 +0000

Recap

In the previous parts of the series, we implemented a backend capable of securely authenticating users and a functional frontend application.

In this part, we will protect our app's (and users') data by introducing an access control mechanism and further securing users' authentication.

Role-Based Access Control

If you remember, previously, we intentionally skipped any route validations within the frontend application, so if you open the "/account" page without signing in, two endpoints will be queried:

The /api/account/check/public will return a successful response
The /api/account will return an error caused by the "user_not_found" exception

While this seems correct at first, the issue here is the exception's origin – that service shouldn't have been invoked in the first place. What if the data queried by that endpoint didn't require the user's ID? This could expose unnecessary information or services.

Let's protect that endpoint so that an unauthorized request never reaches it. Remember how we added the user's role to the token withClaim(claimUserType, userType) and then, in the JwtFilter, put it into the Security Context new SimpleGrantedAuthority(tokenData.getUserType())? This would help us filter requests using Spring's annotation:

@PreAuthorize("hasAnyAuthority('admin', 'user')")
public ResponseEntity<UserInfo> getUser() { ... }

...

[AccountController.java]

Here, we marked this endpoint with the @PreAuthorize annotation, asking Spring to check if the user making the request has any of the listed roles. If the criteria don't match, Spring will entirely prevent the request from reaching this endpoint.

Since we don't display any greeting on the account page if the request fails, let's add one more endpoint for the demonstration:

...

@GetMapping(value = "/check/protected", produces = MediaType.TEXT_PLAIN_VALUE)
@PreAuthorize("hasAnyAuthority('admin', 'user')")
public ResponseEntity<String> getProtected() {
    return ResponseEntity.status(HttpStatus.OK)
            .body("This data is available only when signed in.");
}

[AccountController.java]

Once again, launch the backend and execute npm run api-gen to update our frontend services. As a final touch, query this endpoint along with the public one:

public ngOnInit(): void {
    this.loadData(this.accountService.getPublic(), this.responsePublic$);
    this.loadData(this.accountService.getProtected(), this.responseProtected$);
    ...
}

[account.component.ts]

And display the result:

<div class="c-split">
    <span class="text-split">Protected endpoint:</span>
    @if (responseProtected$ | async; as response) {
    <span class="text-split">{{ response }}</span>
    }
</div>

[account.component.ts]

Now, launch the frontend as well and navigate to the account page manually without signing in. All three endpoints would be queried simultaneously, but only one would return with a successful response (you will see the HTTP status of the protected endpoint, though). But after you sign in, all of them will return something useful.

In a SaaS platform, for example, protecting sensitive endpoints with access control is essential to ensuring users only access what they're authorized for, preventing data leaks or misconfiguration vulnerabilities.

Practice: Now that you've set up access control, try experimenting with additional roles or creating different endpoint restrictions. How would you allow specific users to access something, and what are the potential pitfalls?

Zero-Knowledge

With all the basics set up, I may now introduce you to the zero-knowledge password storage. The idea behind this is very simple: I, as the owner of the web service, take full responsibility for the user's personal information, if applicable, but I don't want to have even the slightest chance to know their passwords and be responsible for credentials in case of a leakage.

Okay, but how do we achieve this? We need to store some kind of credentials anyway to let users in, and the answer would be double hashing.

Hashing passwords with modern algorithms already prevents storing raw passwords in the database. Even if attackers gain access to the hashes, reversing them would be computationally, and financially, expensive. Double hashing adds an extra layer by ensuring that even if someone knows the hashed format, they still won't have access to the raw data unless they're willing to spend even more resources on brute-forcing. Let's see the implementation.

First, we will add a dependency to the frontend app npm i hash.js, and since this package is a CommonJS one, we let Angular know that we're OK with that:

...
"options": {
    ...
    "allowedCommonJsDependencies": ["hash.js"]
}

[project.json]

Now, all we have to do is slightly change the login (and signup) form submission logic:

const formValue = this.form.getRawValue();
const hashedValue = sha256()
    .update(formValue.password || '')
    .digest('hex');

this.authService
    .login({ body: { username: formValue.username, password: hashedValue } })

[login.component.ts]

This will invalidate all existing password hashes stored in the database, so if you would like to introduce this to an existing production application, you would need to implement a smooth migration strategy.

Finally, let's make sure that network errors or brute-force attacks won't mess with our database performance by adding an extra validation to the "password" field:

...

@Size(min = 64, max = 64, message = "Incorrect password format")
@Pattern(regexp = "^[\\da-f]+$", message = "Incorrect password format")
private String password;

[LoginRequest.java]

Now, the only time our application knows the real user's password is the moment between the form input and page navigation. The backend does not know the original value at any point, and you may see it for yourself using the Network tab of Dev Tools.

Conclusion

In this part, we've added more security measures to the application, namely access control and zero-knowledge password storage.

As usual, all the code fragments in this article are in the companion repository, which you can clone or browse online. If you feel any area needs further clarification in the article itself, feel free to point in the comments, and I'll do my best.

Up next is the multi-factor authentication and the seemingly complex (not really) WebAuthn.

Cover image by Joshua Sortino on Unsplash

OpenAPI and Frontend

Michael M. — Sun, 10 Nov 2024 12:29:01 +0000

Recap

In the previous part of the series, we configured the PostgreSQL database, created the User entity, implemented JSON Web Tokens, and secured our API.

In this part, we will add two more methods in the backend for convenience and demonstration and then build the frontend application.

Logout & User Information

Before jumping to the frontend part, we should take one step ahead and think about how we will test everything without using the browser's Dev Tools. We authenticate users with cookies, and of course, we have to be able to remove them when they sign out, so we introduce the "logout" endpoint:

...

@PostMapping(value = "/logout")
public ResponseEntity<String> logout(
        HttpServletResponse res
) {
    CookiesResult result = this.authService.logout();

    res.addCookie(result.getResult()[0]);
    res.addCookie(result.getResult()[1]);
    return ResponseEntity.status(HttpStatus.OK).build();
}

[AuthController.java]

The AuthService's method just passes the request down to the JwtService, where the logic, yet again, is quite simple. By returning cookies with the same parameters, i.e., name and path, but zeroed expiration time, we're essentially revoking them in the browser the moment it processes the response.

...

public @NonNull Cookie[] revokeCookies() {
    return new Cookie[]{
            this.createAuth("", 0),
            this.createMarker("", 0)
    };
}

[JwtServiceImpl.java]

As I said in the previous article, you should implement a revocation mechanism that blacklists tokens until they expire. But, since this is a demo application, we will only revoke cookies for anyone, even if they're not yet authenticated.

Next, to test that we have signed in successfully and everything is good and well, let's create an endpoint that returns the current user's information.

...

@GetMapping(value = "/", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<UserInfo> getUser() {
    UserInfo user = this.accountService.getUser();
    return ResponseEntity.status(HttpStatus.OK)
            .body(user);
}

[AccountController.java]

And the corresponding service:

@Service
@RequiredArgsConstructor
public class AccountServiceImpl implements AccountService {

    private final UserRepo userRepo;

    public UserInfo getUser() {
        String principal = (String) SecurityContextHolder.getContext().getAuthentication().getPrincipal();
        Optional<User> userOptional = this.userRepo.findFirstById(UUID.fromString(principal));
        if (userOptional.isEmpty()) {
            throw new RuntimeException("user_not_found");
        }

        User user = userOptional.get();
        return new UserInfo(user.getUsername());
    }
}

[AccountServiceImpl.java]

Note how we retrieve the principal (or, in JWT terms, the subject). When the HTTP request hits the application, it's passed through several mechanisms within Spring, as well as our JwtFilter we implemented earlier. It populates the context so we can retrieve this information across the app.

OpenAPI

Since we're done creating endpoints for all operations we need right now, let's add OpenAPI to our application. Doing so allows our clients or other teams to discover the endpoints quickly and potentially generate their code, just like we would do in a moment. In larger projects, this drastically reduces errors and time spent debugging integrations.

We will start by adding a dependency that does pretty much everything for us:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
</dependency>

[pom.xml]

And set it up with just a few lines of configuration properties. We will enable the generation and make it human-readable by enabling "pretty print," but since we won't need the Swagger UI, let's turn it off.

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: false
  writer-with-default-pretty-printer: true

[application.yaml]

One last thing would be adding tags to our controllers:

@Tag(name = "auth")
public class AuthController {
    ...
}

[AuthController.java]

We're all set, you may now start the app and open http://localhost:25100/api/v3/api-docs in the browser.

Frontend Models

Creating services and models manually sounds easy enough, but not when you have a huge application with over a hundred endpoints and their contracts change from time to time. Of course, there are tools to automate the models' generation, and for Angular, we will even create services in just a few lines of code.

First, we'll need a dependency npm i -D @public-js/ng-openapi-gen with a few lines of configuration:

{
  ...
  "input": "http://localhost:25100/api/v3/api-docs",
  "output": "src/api/generated"
}

[openapi.json]

And a handy npm script to run it:

...
"scripts": {
  ...
  "api-gen": "ng-openapi-gen --config ./openapi.json"
}

[package.json]

Now, all we need to do is successfully start the backend and, while it's running, execute npm run api-gen to get ourselves all models and services in TypeScript that are ready to use.

With the services in place, we need to plug them into the application. Let's start by creating a proxy configuration to trick the browser into thinking that our backend is served at the exact same domain and port and avoid CORS issues:

{
  "/api/**": {
    "target": "http://127.0.0.1:25100/api",
    "secure": false,
    "changeOrigin": true,
    "pathRewrite": {
      "^/api": ""
    }
  }
}

[proxy-local.json]

We should also make sure that running the npm run start command uses this file every time:

...

"configurations": {
  ...
  "development": {
    ...
    "proxyConfig": "./proxy-local.json"
  }
}

[project.json]

Now that we're able to communicate with the backend during development, we will set up the actual application to work with the generated code. You may either hard-code this path or leverage the power of Angular's file replacement technique, which I highly recommend using.

export const environment = { apiRootUrl: '/api' };

[environment.ts]

Finally, provide the app with the generated API module. To do so, we need to start utilizing Angular's HttpClient, pass our root URL to the Dependency Injection Token, and provide our app with the generated services coupled by a module.

providers: [
    ...
    provideHttpClient(),
    { provide: API_ROOT_URL_TOKEN, useValue: environment.apiRootUrl },
    importProvidersFrom(ApiModule),
]

[app.config.ts]

User Interface

Let's get to the most creative part of this series – the user interface, aka frontend.

We will start by outlining our navigation routes. Note that we don't add any router filters, so we can easily navigate between these pages during development.

export const appRoutes: Route[] = [
    { path: 'account', component: AccountComponent },
    { path: 'login', component: LoginComponent },
    { path: 'signup', component: SignupComponent },
    { path: '', pathMatch: 'full', redirectTo: 'login' },
];

[app.routes.ts]

Moving on to the signup page, start by creating an Angular reactive form. It has the same validation rules for the username field as the backend, so we can catch errors faster. Also, we won't even bother validating the "repeat_password" control, because we will check if it matches the password anyway.

public readonly form = this.fb.nonNullable.group({
    username: this.fb.nonNullable.control<string>('', [Validators.required, Validators.pattern('[\\da-zA-Z_-]+')]),
    password: this.fb.nonNullable.control<string>('', [Validators.required, Validators.minLength(6)]),
    repeat_password: this.fb.nonNullable.control<string>('', [Validators.required]),
});

[signup.component.ts]

Next, we add some HTML to render this form. Not only will our forms be visually pleasing, but they will also be accessible. For the user's convenience, we will explicitly disable the spellcheck and automatic capitalization, even though we look users up in a case-insensitive manner.

Also, since the CSS code is provided in the repo, I will not mention it here at all. You're welcome to either re-use it or write your own from scratch.

<form [formGroup]="form" (ngSubmit)="submit()" class="c-form">
    <div class="w-input">
        <label for="username" class="f-label">Username</label>
        <input
            formControlName="username"
            id="username"
            type="text"
            autocomplete="username"
            autocapitalize="off"
            autocorrect="off"
            spellcheck="false"
            class="f-input"
        />
    </div>

    ...
</form>

[signup.component.ts]

Then, because we need some logic to be done before the data is sent, we will add a method to mark the form "dirty" if the validation fails and add an error message. It will then send the request and handle its response.

...

public submit(): void {
    if (!this.form.valid) {
        this.form.markAsDirty();
        this.errors$.next('The form is invalid');
        this.form.valueChanges.pipe(first()).subscribe(() => this.errors$.next(''));
        return;
    }

    if (this.form.value.password !== this.form.value.repeat_password) {
        this.errors$.next("Passwords don't match");
        this.form.valueChanges.pipe(first()).subscribe(() => this.errors$.next(''));
        return;
    }

    const formValue = this.form.getRawValue();

    this.authService
        .signup({ body: { username: formValue.username, password: formValue.password } })
        .pipe(catchError(this.handleHttpError))
        .subscribe({
            next: () => this.router.navigate(['account']),
            error: (code: string) => this.errors$.next(signupErrors[code] ?? signupErrors['_']),
        });
}

[signup.component.ts]

For a seamless experience, let's add the navigation link that adds the username to the router state.

<div class="c-split">
    <span class="text-split">Already have an account?</span>
    <a routerLink="/login" [state]="{ username: form.value.username }" class="link-split">Sign in</a>
</div>

[signup.component.ts]

The login page looks very alike, so I'll skip ahead and add a method that pulls the username from the router state and applies it to the form:

...

public ngOnInit(): void {
    const navUsername = this.router.lastSuccessfulNavigation?.extras?.state?.['username'];
    if (navUsername) {
        this.form.patchValue({ username: navUsername });
    }
}

[login.component.ts]

How is it convenient? Easy: imagine yourself as a user who tried to sign up on a website and got a message that this user already exists. You will likely remember that some time ago you already signed up here, and when you click the "sign in" link, the login form will greet you with that username already in place. Same applies in the other direction.

So, what about those two endpoind we added at the beginning of this part? We will use them for the account page. Let's (try to) load some data when this page is opened:

...

public ngOnInit(): void {
    this.loadData(this.accountService.getPublic(), this.responsePublic$);

    this.accountService.getUser().subscribe({
        next: (user) => this.userInfo$.next(user),
    });
}

[account.component.ts]

And greet the user by their username, if they're signed in (remember, we don't have router filters):

@if (userInfo$ | async; as userInfo) {
<div class="c-title">
    <h2 class="text-title">Hello, {{ userInfo.username }}</h2>
</div>
}

[account.component.ts]

That's it, you may now spin up everything and see how it works for yourself!

TODO: Add the drumroll sound.

Conclusion

In this part we've implemented a fully-functional accessible frontend based on auto-generated API models from the OpenAPI document.

As a reminder, all the code fragments in this article are in the companion repository, which you can clone or browse online. If you feel any area needs further clarification in the article itself, feel free to point in the comments, and I'll do my best.

We can now proceed to more complex and even more exciting functionality like access control, multi-factor authentication, and WebAuthn.

Cover image by Karen Grigorean on Unsplash

Database Setup, JWT Implementation & API

Michael M. — Sat, 26 Oct 2024 05:36:23 +0000

Foundation

For this series, our launchpad will be two separate applications: the Spring Boot-based backend and the Angular-based frontend. I am deliberately omitting their initialization because this code is just boilerplate, already in the companion repository, and you will likely find a better guide covering all the basics.

I am also deliberately omitting a lot of code here to focus on explaining key concepts, leaving repetitive or obvious parts outside of the article. You will find a complete working implementation in the repo, where everything is broken down into separate commits.

Database Setup

Before we create any application logic, we'll need a database to store user information. While Spring provides out-of-the-box support for an H2 in-memory database, which self-destructs when the application is shut down, for this project, let's focus on a more real-world implementation using PostgreSQL. The setup is as simple as possible:

image: postgres:16-alpine
environment:
  POSTGRES_DB: knox_dev_db
  POSTGRES_USER: knox_dev_user
  POSTGRES_PASSWORD: knox_dev_pass
  ...
volumes:
  - ./dbdev:/var/lib/postgresql/data
ports:
  - '25101:5432'

[docker-compose.dev.yml]

This configuration pulls the lightweight Alpine-based image of PostgreSQL and sets up essential environment variables like the database name, username, and password. We also specify a custom port and tell Docker to persist container data right beside the file.

Don't forget to add the "volume" directory to the "gitignore" file because PostgreSQL spawns a lot of files that we don't want to be committed to the repository:

dbdev/*

[.gitignore]

Yes, committing credentials to shared storage and even storing them in plaintext is risky, but since this file is used solely to spin up a local database, it's acceptable as long as you never use these credentials in production.

Now, let's tell our backend how to connect to the database:

datasource:
  driver-class-name: org.postgresql.Driver
  url: jdbc:postgresql://localhost:25101/knox_dev_db
  username: knox_dev_user
  password: knox_dev_pass
jpa:
  generate-ddl: true
  hibernate:
    ddl-auto: update
  ...

[application.yml]

This configuration uses a JDBC connection string to connect to the database, which is pretty standard and allows us to pass only one variable during deployment instead of three. We also enable DDL generation to let Spring automatically update the database schema as we go.

At this point, you may already start the application with the database connected to it, but nothing much will happen yet. Let's now create an entity that will represent users in our app; it will serve as the foundation for managing users, their credentials, and other relevant information.

@Entity
@Table(name = "users")
public class User {

    @NonNull
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    @Column(name = "id", nullable = false, updatable = false)
    private UUID id;

    @Setter
    @NonNull
    @Column(name = "username", nullable = false, unique = true, length = 64)
    @JdbcTypeCode(SqlTypes.VARCHAR)
    private String username;

    ...
}

[User.java]

Here, we use UUIDs for the user ID to prevent guessing and to allow potential future scaling of the application into a large distributed system without major refactoring. The username field is unique and capped at 64 characters to balance out flexibility and performance; the password field is capped at the same length because of bcrypt limitations.

Pro Tip: Always use UUIDs for primary keys in distributed systems to avoid ID collisions and enhance security by preventing sequential patterns.

Now, let's create a repository for this entity, which, thanks to Spring Data's Derived Query Methods, we can declare as an interface without writing custom implementations:

public interface UserRepo extends JpaRepository<User, UUID> {

    Optional<User> findFirstById(@NonNull UUID id);

    Optional<User> findFirstByUsernameLikeIgnoreCase(@NonNull String username);
}

[UserRepo.java]

Finally, leverage the power of Spring Data so it will wire this entity and repository automatically:

@EntityScan({"gin.knox.jpa"})
@EnableJpaRepositories({"gin.knox.jpa"})
public class KnoxApplication {
    ...
}

[KnoxApplication.java]

JWT Implementation

Now, let's move on to implementing JSON Web Tokens.

First, we need to add a few dependencies that handle many things behind the scenes:

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-core</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-config</artifactId>
</dependency>
<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
</dependency>

[pom.xml]

Next, create a class to interchange the token information within our app. As a reminder, these tokens have only a few mandatory claims and are very extensible, but in our case, we'll focus on the subject, which is the user's ID, and the role:

public class TokenData implements Serializable {

    @NonNull
    private String userId;

    @Nullable
    private String userType;
}

[TokenData.java]

The core of the JWT implementation is the private key used for signing the token. If you've worked with production environments before, you probably know that providing secure non-text data to the application is painful. Tools like HashiCorp Vault are used in big tech to securely store various credentials, so we'll generate our keys as single-line text strings.

openssl genrsa -out ${pathPem} 2048;
keyPkcs8=$(openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in ${pathPem} | tr -d '\n');
...
keyX509=$(openssl rsa -pubout -in ${pathPem} | tr -d '\n');
...

[jwk-gen.sh]

Add the resulting keys to application.yaml (again, that's okay if these keys are used solely in your local environment). Technically, you may set your key ID to be anything you like; this random value would be useful when you need to rotate your keys, but that's a topic for a different article.

jwt:
  issuer: knoxdev
  key:
    id: ...
    pkcs8: ...
    x509: ...

[application.yml]

Next, we'll create an interface for the JwtDataProvider based on the RSAKeyProvider and provide methods to retrieve the issuer and keys for JWT handling:

public interface JwtDataProvider extends RSAKeyProvider {

    @NonNull
    String getIssuer();
}

[JwtDataProvider.java]

And then implement it using the @Value annotation to inject variables from the configuration and the postConstruct method, where our base64-encoded keys are decoded into the respective formats:

@Service
public class JwtDataProviderImpl implements JwtDataProvider {
    ...

    @Value("${jwt.key.x509}")
    private String keyX509;

    @PostConstruct
    private void postConstruct() throws Exception {
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");

        this.publicKey =
                (RSAPublicKey)
                        keyFactory.generatePublic(new X509EncodedKeySpec(Base64.decodeBase64(this.keyX509)));
        ...
    }
}

[JwtDataProviderImpl.java]

Now that we have our key set up, let's implement the JwtService itself:

@RequiredArgsConstructor
public class JwtServiceImpl implements JwtService {
    ...
}

[JwtServiceImpl.java]

At the core of this service will be an issuing method that sets the token's validity time, and consequentially the session length, the user ID and their role, our key ID, and the issuer name.

...

private @Nullable String issueToken(@NonNull String userId, @NonNull String userType) {
    try {
        return JWT.create()
                .withKeyId(this.dataProvider.getPrivateKeyId())
                .withIssuer(this.dataProvider.getIssuer())
                .withExpiresAt(Instant.now().plusSeconds(sessionTtl))
                .withSubject(userId)
                .withClaim(claimUserType, userType)
                .sign(this.algorithm);
    } catch (Exception ex) {
        return null;
    }
}

[JwtServiceImpl.java]

Best Practice: Set reasonable expiration times for JWTs; in production, consider implementing a token blacklist or revocation mechanism to prevent compromised tokens from being reused.

This method would be called by another one that places the resulting token in a cookie. In fact, we will create two cookies – one with the token itself, which would be inaccessible for JavaScript, and one allowing the frontend to know whether the user is signed in or not.

public @Nullable Cookie[] issueCookies(@NonNull String userId, @NonNull String userType) {
    String token = issueToken(userId, userType);
    return token == null ? null : new Cookie[]{
            this.createAuth(token, sessionTtl),
            this.createMarker("1", sessionTtl - 10)
    };
}

private @NonNull Cookie createAuth(@Nullable String value, int maxAge) {
    Cookie cookie = new Cookie(authCookieName, value);
    cookie.setPath("/");
    cookie.setHttpOnly(true); // "false" for the marker
    cookie.setMaxAge(maxAge);
    return cookie;
}

...

[JwtServiceImpl.java]

Parsing the token is a multi-step process as well: we extract the cookie, verify the token's signature, and only then retrieve its claims. We will check that the token contains the user type as well.

...

public @Nullable TokenData parseCookies(Cookie[] cookies) {
    Optional<Cookie> cookieMaybe =
            cookies == null
                    ? Optional.empty()
                    : Arrays.stream(cookies)
                    .filter(cookie -> cookie.getName().equals(authCookieName))
                    .findFirst();

    TokenData tokenData = cookieMaybe.isEmpty() || cookieMaybe.get().getValue().isBlank()
            ? null
            : this.parseToken(cookieMaybe.get().getValue());

    return tokenData == null || tokenData.getUserType() == null ? null : tokenData;
}

private @Nullable TokenData parseToken(@NonNull String token) {
    try {
        DecodedJWT jwt = this.verifier.verify(token);
        return new TokenData(jwt.getSubject(), jwt.getClaim(claimUserType).asString());
    } catch (Exception ex) {
        return null;
    }
}

[JwtServiceImpl.java]

Create a RequestFilter that will authenticate our users upon each request:

@Component
@RequiredArgsConstructor
public class JwtFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(...) {
        TokenData tokenData = this.jwtService.parseCookies(request.getCookies());

        SecurityContextHolder.getContext()
                .setAuthentication(
                        tokenData == null
                                ? new UsernamePasswordAuthenticationToken("", null, null)
                                : new UsernamePasswordAuthenticationToken(
                                tokenData.getUserId(),
                                null,
                                Collections.singleton(new SimpleGrantedAuthority(tokenData.getUserType()))));

        filterChain.doFilter(request, response);
        SecurityContextHolder.getContext().setAuthentication(null);
    }
}

[JwtFilter.java]

Note that in this implementation, every request is considered authenticated, you may tailor this filter to your own specifics.

Finally, let's enable WebSecurity and set up the SecurityFilterChain:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(@NonNull HttpSecurity http) throws Exception {
        http.addFilterBefore(this.jwtFilter, UsernamePasswordAuthenticationFilter.class);

        http.authorizeHttpRequests(customizer -> customizer.anyRequest().authenticated());

        http.sessionManagement(customizer -> customizer.sessionCreationPolicy(SessionCreationPolicy.STATELESS));

        http.csrf(AbstractHttpConfigurer::disable);
        http.cors(Customizer.withDefaults());

        return http.build();
    }

    ...
}

[SecurityConfig.java]

While we've disabled CSRF for simplicity, keep in mind that this is an important security measure to protect against certain types of attacks.

API

Now that we have implemented JWTs for issuing and validating tokens, the next logical step is to expose this functionality through a REST API so we can at least try the code above using Postman.

First off, let's circle back to the security configuration and set up the password encoder that we will use later in the process. We don't want to store passwords in plain text.

...

@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder(BCryptPasswordEncoder.BCryptVersion.$2B, 10);
}

[SecurityConfig.java]

I like using simple yet handy generic classes like this one for internal stuff:

@Getter
@AllArgsConstructor
public abstract class AnyResult<T> {

    private String error;

    private T result;
}

[AnyResult.java]

It allows us to create classes like this, for example:

public class CookiesResult extends AnyResult<Cookie[]> {

    public CookiesResult(String error, Cookie[] result) {
        super(error, result);
    }

    public static CookiesResult error(String error) {
        return new CookiesResult(error, null);
    }

    public static CookiesResult success(Cookie[] result) {
        return new CookiesResult(null, result);
    }
}

[CookiesResult.java]

We will also need some public-facing data transfer objects (aka DTOs):

public class SignupRequest {

    @NotEmpty
    @Size(min = 6, max = 64, message = "Incorrect username format")
    @Pattern(regexp = "^[\\da-zA-Z_-]+$", message = "Incorrect username format")
    private String username;

    @ToString.Exclude
    @NotEmpty
    @Size(min = 6, max = 64, message = "Incorrect password format")
    private String password;

    private boolean admin;
}

[SignupRequest.java]

Here, we provide the same length limits for the username and password, add minimal requirements and some validation for usernames.

TODO: Should I mention that adding the "admin" flag for something other than a demonstration is a bad idea?

Let's tie everything together with a service to process login and signup. The "login" method is quite simple: it checks the user's credentials and issues JWT cookies if the credentials are valid.

@Service
@RequiredArgsConstructor
public class AuthServiceImpl implements AuthService {

    ...

    public CookiesResult login(@NonNull LoginRequest request) {
        Optional<User> userOptional = this.userRepo.findFirstByUsernameLikeIgnoreCase(request.getUsername());
        if (userOptional.isEmpty()) {
            return CookiesResult.error("user_not_found");
        }

        User user = userOptional.get();
        if (!this.passwordEncoder.matches(request.getPassword(), user.getPassword())) {
            return CookiesResult.error("password_mismatch");
        }

        return CookiesResult.success(
                this.jwtService.issueCookies(
                        user.getId().toString(),
                        user.getType().toString()
                ));
    }

    ...
}

[AuthServiceImpl.java]

And finally, a REST controller. You may implement the service logic right in the controller, but I prefer to keep them as simple as possible, so we'll pass the request to the service and handle the output.

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

    @PostMapping(value = "/login", consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<String> login(
            @RequestBody @Valid @NotNull LoginRequest request,
            HttpServletResponse res
    ) {
        CookiesResult result = this.authService.login(request);
        if (result.getError() != null) {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(result.getError());
        }

        res.addCookie(result.getResult()[0]);
        res.addCookie(result.getResult()[1]);
        return ResponseEntity.status(HttpStatus.OK).build();
    }

    ...
}

[AuthController.java]

Conclusion

We've taken a hands-on approach to building a robust authentication system. From configuring PostgreSQL, to creating the User entity, to implementing JWTs and securing REST API, each component plays its role.

At this point, our application can:

Store users in the database with the hashed passwords
Handle their signup and login
Validate usernames and passwords
Issue JWTs and authenticate requests

Again, all the code fragments in this article are in the companion repository, which you can clone or browse online. If you feel any area needs further clarification in the article itself, feel free to point in the comments, and I'll do my best.

In the next articles, we will move on to the frontend part and then dive into more complex stuff to secure our users' data as much as possible.

Cover image by Kaleidico on Unsplash

Building Secure Systems for Modern Applications

Michael M. — Tue, 22 Oct 2024 04:02:57 +0000

The importance of secure authentication in modern applications has grown exponentially in the last decade and continues to rise. The security of your personal information, private messages, photos, contacts, bank transactions, and much more is at stake whenever you use any online service. While some corporations build their income on top of security, the vast majority of companies, regardless of size, are susceptible to cyber threats, as demonstrated by the recent increase in data breaches.

In this series of articles, I will cover various approaches to storing users' credentials and create a small, yet secure, application to demonstrate them. Rather than targeting a general audience, these articles are aimed at architects and developers, for whom they will be exceptionally useful.

The technology stack I've chosen is fairly standard – PostgreSQL, Java with Spring, and Angular. While these technologies are popular, the concepts and approaches discussed in the series can apply to any modern stack.

Key Concepts

Before we move on, let's refresh some key knowledge:

Authentication is the process of verifying the identity of a user or system. For example, when a user signs in, the system checks if the credentials are correct.

Authorization, on the other hand, is the process of determining the user's or system's permissions. For example, a signed-in user might be able to view and edit their own data if they're a "regular" user, or edit anyone's data if they have "elevated" permissions.

While these processes are often discussed together, they're distinct and entirely different, although interconnected. To use an analogy, if this were a concert, authentication would be the validation of your ticket, and authorization would be moving to your assigned seating zone.

The Role of Authentication & Authorization

Setting aside intentional data leaks, where someone with access to user data "dumps" or exports it, the majority of breaches occur due to poor authentication or authorization practices, whether it's weak password policies, outdated cryptographic algorithms, or what's commonly called "Broken Access Control".

To mitigate some of these vulnerabilities, weak passwords can be addressed by implementing Multi-Factor Authentication (MFA), also known as the "six-digit code from an email or app," which can be easily integrated into systems of any size.

Commonly used authorization models include:

Role-Based Access Control (RBAC): Pre-defined user roles and their access scope.
Attribute-Based Access Control (ABAC): Access is granted based on various attributes such as device type, user group, or file type.
Discretionary Access Control (DAC): Provides granular permissions with flexibility in exchange for increased complexity.

Modern Approaches

One of today's techniques to secure authentication and minimize data leakages is using advanced hashing algorithms like bcrypt and Argon2 for secure password storage and to prevent brute force attacks. These algorithms are computationally intensive, requiring a substantial amount of power to encrypt passwords, but also making brute force attacks against the resulting hashes extremely difficult – potentially taking days or even years to decrypt a single password with cutting-edge technologies.

As mentioned earlier, MFA mitigates the risks of weak cryptography by requiring users to provide a "second factor" for signing in. The first factor is something the user knows – their password. The second factor is something they possess, such as a trusted device, a smartphone with an app, or a secure token. But we'll get to that later in the series.

Improved Approach

Server-side password hashing is good enough to protect user accounts in case the database gets leaked, but we can enhance security tenfold by implementing the zero-knowledge approach. This improvement is why our app will be called "Knox."

Series Roadmap

In the following articles, I will describe in detail and implement:

Database design to store and manage user accounts
Classic approach to password storage
Frontend application (because an API alone won't cut it)
RBAC with Spring
Improved approach to password storage

After we've laid the groundwork, we'll dive into more advanced topics like:

MFA, with proper time-based implementation
WebAuthn, for a cutting-edge authentication flow
OAuth2, to implicitly sign users up

By following the series, you'll not only gain a fully functional backend with a GitHub repository included but also priceless knowledge. As a bonus, you'll have a neatly designed frontend with a wonderful user experience, crafted especially for this series by a friend of mine Andrii.

Cover image by Kai Pilger on Unsplash

Exploring Alternatives: Are There Better Options Than JSON?

Michael M. — Fri, 16 Feb 2024 16:43:13 +0000

A while back, I stumbled upon a captivating article titled “JSON is incredibly slow: Here’s What’s Faster!” It almost immediately caught my attention because, let’s face it, who doesn’t like shiny trinkets that make their apps run faster? But as I dug deeper, something felt off. So, I decided to not only take another look at these alternatives but also put them to the test.

Here are the key points I’d like to focus on and discuss: JSON has serialization overhead, offers a limited set of data types, and is bloated and too verbose, so there are at least four supposedly faster alternative exchange formats to use.

Let’s kick things off with the basics. No format can eliminate serialization overhead, given the internet’s reliance on various transfer protocols for serialized data. We can try to optimize whatever we want, but unless there’s an alternative to HTTP itself, we’ll be serializing data back and forth.

Now, onto the alternatives mentioned in the article: Protocol Buffers (protobuf), MessagePack (msgpack), BSON, and Apache Avro. I would exclude BSON and Avro from this experiment as they cater to more niche use cases, so applying them to a typical client-server exchange might prove challenging even for a simple playground app.

One thing mentioned is JSON’s lack of binary data and functions support. Here’s where all the alternatives shine, as they are binary. However, none of the suggested formats still offer functions. Don’t get me wrong, but why overcomplicate things and pass functions? Doing so will not only disperse the business logic of an application but also introduce unnecessary complexity because the receiving end, whether it’s a client-side part running on JavaScript or another service created in a different language, might be unable to execute such functions either way, the sender will be responsible for creating a function in a language foreign to itself.

Next up is verbosity. With most applications split into backend and frontend components, each can and has its own bugs. Consider what an experienced QA engineer familiar with the project enough and aware of some technical details does when they find a problem and need to file a Jira issue: they open DevTools, look through the data received from the backend, and assign the corresponding label. Swapping out JSON, or XML for that matter, for a binary format will make it harder for both QA engineers and developers to trace issues. So developers will have to use breakpoints to investigate even the tiniest issue, which wouldn’t take much time, but you know how problems sometimes pile up.

A side-by-side comparison of JSON, msgpack, and protobuf responses

Let’s imagine that we weighed all the risks and prepared automated tests of all sorts, but the question remains: do we truly need an alternative to JSON, or is it doing just fine? I take software benchmarks with a grain of salt, often seeing them as a part of marketing, just like the battery life in fancy smartphone presentations. That’s why if I can’t get some good reviews, I roll up my sleeves, set up playgrounds, and try to replicate real-life conditions. Who cares how fast a protocol can serialize data if the roundtrip time is still the same?

Here are the results:

(lower numbers are better)

Evidently, protobuf is a winner regarding medium-sized requests, at least in transfer size, which is crucial for clients with poor internet connection. But if you’ve noticed the gaps in the table, you got to the juiciest part – missing measurements. But why so?

Countless times, I’ve encountered a nice piece of software that either had no examples whatsoever or the ones provided were so unhelpful that I spent hours trying to make things work. The same goes for protobuf and msgpack – both lack solid working examples. Sure, Spring supports protobuf out of the box, and there are indeed good examples and even guides on how to start using either of them, but a closer look at the table reveals a significant issue – the absence of POST requests. It’s not that Spring can’t handle them; it’s just incredibly tedious to implement. Even though Java is not my primary skill, I’ve spent about 20 hours trying to crack that nut.

Yet I’m grateful for the open-source software we already have and that there are potential alternatives to JSON, but if you’re putting something out there and expecting others to use it, please at least provide some basic and, most importantly, working examples.

How do companies like Okta and LinkedIn make it all tick? One might assume they’ve got deep pockets to throw at such challenges, but unfortunately, not all of us can afford that luxury. That’s why I invite you to take part in building a one-stop collection of working examples, making these technologies more accessible to those with fewer resources. If you can contribute, you’re more than welcome to the repo: https://github.com/GinMitch/better-than-json.

Dynamic translations in Angular made possible

Michael M. — Fri, 12 Aug 2022 17:57:00 +0000

A practical guide to implement lazy-loaded translations

If you have ever dealt with internationalization (or “i18n” for short) in Angular or is about to implement it, you may stick with the official guide which is awesome, use third-party packages that might be hard to debug or choose an alternative path which I will describe below.

One of the common pitfalls when using i18n are large translation files size and inability to split them in order to hide parts of your application from prying eyes. Some solutions like Angular built-in implementation are really powerful and SEO compatible but require a lot of preparation and do not support switching languages on the fly in development mode (which was causing troubles at least in version 9); other solutions like ngx-translate require you to install several packages and still don’t support splitting up a single language (update: in fact, ngx-translate supports this).

While there is no “magic wand” out there for this complex feature that supports everything and fits everyone, here is another way of implementing translations that might fit your needs.
Enough with the introduction, I promised this would be a practical guide, so let’s jump straight into it.

Preparing the basics

The first step is to create a type for languages that will be used across the app:

export type LanguageCode = 'en' | 'de';

One of the loved Angular features is Dependency Injection that does a lot for us — let’s utilize it for our needs. I would also like to spice things up a little by using NgRx for this guide but if you don’t use it in your project, feel free to replace it with a simple BehaviorSubject.

As an optional step that will make further development with NgRx easier, create a type for DI factories:

export type Ti18nFactory<Part> = (store: Store) => Observable<Part>;

Creating translation files

General strings

Suppose we have some basic strings that we’d like to use across the app. Some simple yet common things that are never related to a specific module, feature or library, like “OK” or “Back” buttons.
We will place these strings in “core” module and start doing so with a simple interface that will help us not to forget any single string in out translations:

export interface I18nCore {
  errorDefault: string;
  language: string;
}

Just to be clear, this interface does not guarantee that all the strings will be actually translated but the TypeScript compiler (and your IDE) will raise an error “TS2741” if you forget to include any string in your “lang” files.

Moving on to the implementation for the interface and for this snippet it’s vitally important that I provide an example file path which in this case would be libs/core/src/lib/i18n/lang-en.lang.ts:

export const lang: I18nCore = {
  errorDefault: 'An error has occurred',
  language: 'Language',
};

To reduce code duplication and get the most out of the development process, we’ll also create a DI factory. Here’s a working example utilizing NgRx (again, this is completely optional, you may use BehaviorSubject for this):

export const I18N_CORE =
  new InjectionToken<Observable<I18nCore>>('I18N_CORE');

export const i18nCoreFactory: Ti18nFactory<I18nCore> =
  (store: Store): Observable<I18nCore> => 
    (store as Store<LocalePartialState>).pipe(
      select(getLocaleLanguageCode),
      distinctUntilChanged(),
      switchMap((code: LanguageCode) =>
        import(`./lang-${code}.lang`)
          .then((l: { lang: I18nCore }) => l.lang)
      ),
    );

export const i18nCoreProvider: FactoryProvider = {
  provide: I18N_CORE,
  useFactory: i18nCoreFactory,
  deps: [Store],
};

Obviously, the getLocaleLanguageCode selector will pick the language code from Store.

Don’t forget to include translation files into your compilation as they are not being referenced directly thus will not be automatically included. For that, locate the relevant “tsconfig” (the one that lists “main.ts”) and add the following to the “include” array:

"../../libs/core/src/lib/i18n/*.lang.ts"

Note that the file path here includes a wildcard so that all your translations will be included at once. Also, as a matter of taste, I like to prefix similar files which pretty much explains why the example name ([prefix]-[langCode].lang.ts) looks so weird.

Module-specific strings

Let’s do the same for any module, so we can see how translations will be loaded separately in the browser. To keep it simple, this module would be named “tab1”.

Again, start with the interface:

export interface I18nTab1 {
  country: string;
}

Implement this interface:

export const lang: I18nTab1 = {
  country: 'Country',
};

Include your translations into compilation:

"../../libs/tab1/src/lib/i18n/*.lang.ts"

And optionally create a DI factory which would look literally the same as previous but with another interface.

Providing translations

I prefer to reduce the amount of providers so “core” translations will be listed in AppModule only:

providers: [i18nCoreProvider],

Any other translation should be provided in the relevant modules only — either in lazy-loaded feature modules or, if you follow the SCAM pattern, in component modules:

@NgModule({
  declarations: [TabComponent],
  imports: [CommonModule, ReactiveFormsModule],
  providers: [i18nTab1Provider],
})
export class TabModule {}

Also note the elegance of utilizing pre-made FactoryProviders instead of adding objects here.

Inject the tokens in a component.ts:

constructor(
  @Inject(I18N_CORE)
  public readonly i18nCore$: Observable<I18nCore>,
  @Inject(I18N_TAB1)
  public readonly i18nTab1$: Observable<I18nTab1>,
) {}

And finally, wrap component.html with ng-container and a simple ngIf statement:

<ng-container *ngIf="{
    core: i18nCore$ | async,
    tab1: i18nTab1$ | async
  } as i18n">
    <p>{{ i18n.core?.language }}</p>
    <p>{{ i18n.tab1?.country }}: n/a</p>
</ng-container>

Checking out the result

Let’s run this and see if this actually works and more importantly how exactly would these translations be loaded. I created a simple demo app consisting of two lazy-loaded Angular modules, so you may clone and experiment with it. But for now, here are the actual screenshots of DevTools:

This is the initial page load in development mode; note the two .js files at the very end — we created these in a previous section.

This is what it looks like when language is being switched. The Network tab has been reset for demonstration purposes.

And this is the result of switching to the second lazy tab.

Benefits

With this solution you would be able but not obliged to split your translations into several files in any way that you need;
It’s reactive, which means that being implemented correctly it provides your users with a seamless experience;
It does not require you to install anything that doesn’t ship with Angular out of the box;
It’s easily debuggable and fully customizable as it would be implemented directly in your project;
It supports complex locale resolutions like relating on browser language, picking up regional settings from user account upon authorization and overriding with a user-defined language — and all this without a single page reload;
It also supports code completion in modern IDEs.

Drawbacks

As these translation files will not be included in assets, they should actually be transpiled which will slightly increase the build time;
It requires you to create a custom utility or use a third-party solution to exchange your translations with a localization platform;
It might not work really well with search engines without proper server-side rendering.

GitHub

Feel free to experiment with the fully working example that is available in this repository.
Stay positive and create great apps!

Cover photo by Nareeta Martin on Unsplash

Farewell, Moment.js!

Michael M. — Thu, 17 Sep 2020 15:02:51 +0000

On September 15, 2020 Moment.js maintainers’ team stated that one of the world’s most popular JavaScript date library has come to an end.

It doesn’t need any introduction: according to NPM, as of September 2020, it has over 14 million downloads weekly and more than 46000 dependent open source packages. Moment.js has been around since 2011, but its developers have their own reasons to shut down its active support, which also includes immutability and support for “tree shaking”.

There’s no need to whine about it but a good reason to take a look at its successors. Obviously, I must tell you that you don’t have to immediately scoop through all of your projects and replace Moment.js; if there are not many places where you use it, go ahead and upgrade but since now anything you start working on should probably not use it anymore.

Here is an overview comparison of several date libraries which are recommended as a feasible replacement. We’ll stick to TypeScript as an increasingly popular language used by a lot of projects (I mean, there are really a lot).

To begin with, let’s create a pretty basic React app, so we can jump start this journey and see the results immediately:
yarn create react-app play-date --template typescript

Moment.js

Let’s take a look at Moment.js and see how simple it is to start using it (or should I now say “was”?).

First thing we need before using Moment.js in any project is to install it:
npm i moment or yarn add moment

Then import it in a component and you're good to go:
import moment from 'moment';

Date as object
const test1 = new Date('2018-01-16'); // Date

First, we need to convert it:
const obj1 = moment(test1); // Moment
That's it — nice and simple! Moment.js takes a Date object “as is” and turns it into its own object, so we could operate on it.

And if we need to know what year is inside, then we could easily get it:
obj1.year(); // number

Or count how many days have passed since then:
moment().diff(obj1, 'days'); // number

Date as string
const test2 = '2016-07-20'; // string

Convert it:
moment(test2); // Moment
Moment.js also takes a string “as is” so you should only care about its format.
Though Moment doesn't restrict you with some special format, it may not recognize some real junk.

Day.js

Then we move on to the Moment’s nearest successor — Day.js. If you ever used Moment.js, it should be really easy to replace it with Day.js, it’s not exactly the same but still worth a try.

Start using Day.js by adding it to your project:
npm i dayjs or yarn add dayjs

Then import it:
import dayjs from 'dayjs';

Even to those of you who have never heard of Moment before the two previous lines should ring a bell as if you’ve seen this before. And you’d be right to say that it looks exactly like Moment’s installation and import.

Date as object
const test1 = new Date('2018-01-16'); // Date

Day.js might not be a drop-in replacement for Moment.js but it gives you pretty similar API and uses the same concept of turning everything into its own object.

Convert it:
const obj1 = dayjs(test1); // Dayjs

And if we need to know what year is inside, then we just get it:
obj1.year(); // number

Or simply count how many days have passed since then:
dayjs().diff(obj1, 'day'); // number

The thing about using Moment.js is that you could count days or years as well as day or year — that doesn’t matter at all. We couldn’t say the same about Day.js, but on the other hand that's the price you pay for having a really lightweight library.

Date as string
const test2 = '2016-07-20'; // string

And again we need to convert it. Day.js as well as Moment.js will parse any string given its ISO 8601. But if you want to parse anything different from that, you must provide it with the desired format:
dayjs(test2, 'YYYY-MM-DD'); // Dayjs

Luxon

Our next contestant gives us a subtle hint that its core maintainers is nearly the same as Moment’s.

Take the usual step and add Luxon to your project:
npm i luxon or yarn add luxon

Back off a little bit. Remember we decided to go on with TypeScript? Well, Luxon in contrast to the other libraries doesn’t ship with its own type definitions, so your modern IDE should scream about when you try to import it. Here’s the way to add TypeScript support:
npm i @types/luxon or yarn add @types/luxon

Then you may proceed to another usual step:
import { DateTime } from 'luxon';

Date as object
const test1 = new Date('2018-01-16'); // Date

If you think we should wrap (or convert) the date to use it then you’re right:
const obj1 = DateTime.fromJSDate(test1); // DateTime
Rather than Moment.js, Luxon will not provide you with a single “entry point” to do it. Refer to its guide or use code completion to parse your date.

Get the year value back:
obj1.toFormat('yyyy'); // string

Here we get result as string because toFormat() could give us nearly anything with the token parameter.

Count how many days have passed since then:
DateTime.fromJSDate(new Date()).diff(obj1, 'days').as('days'); // number
The syntax is trying really hard to look similar to Moment.js, but it's a way longer than I personally like and it gives you an awfully precise result.

Date as string
const test2 = '2016-07-20'; // string

And again we need to convert it using the corresponding method. Though, we could've used fromFormat() if this string was not ISO 8601 but let's stick with fromISO() for now:
DateTime.fromISO(test2); // DateTime

date-fns

To move on to the next library, we need to add date-fns just as usual:
npm i date-fns or yarn add date-fns

And here comes its first pitfall — you could not import it like Moment.js or Luxon, each of date-fns’ functions should be added to the import statement separately thus you can not use the benefits of code completion.
It requires you to know which function you need or refer to its guide to find the right one:
import { differenceInDays, getYear } from 'date-fns';

Date as object
const test1 = new Date('2018-01-16'); // Date

This library is based on so-called “helper functions” which rely on native Date object manipulations, which is really great. Therefore, we need no conversion to use it right away!

Let's get a year from it again:
getYear(test1); // number

And count how many days have passed since then:
differenceInDays(new Date(), test1); // number

Date as string
const test2 = '2016-07-20'; // string

Unfortunately, date-fns could not recognize the string format for us so to parse it we must explicitly provide the string format which is not the point if your project is well-documented and consistent:
parse(test2, 'yyyy-MM-dd', new Date()); // Date

All code samples here available on GitHub within the React app.

I must say that this quick overview of Moment’s possible replacements doesn’t make a claim to be a full guide to these libraries or a full list of “What should I use instead of Moment.js?”.
If you know better tools — please let everyone know by mentioning them in the comments.