TLDR; If you end up on this page, you probably realize that configuring domain-level Forward Auth from Traefik in K3S with Authentik 2024.2.2 is not easy. I show here how to do it.

Authentik is a popular identity provider which can be used in various authentication and authorisation flows. You can get more information about it on https://goauthentik.io/. There is a big list of possible integrations with known services, such as Portainer and Jenkins.

The other feature of Authentik is more interesting. It provides a capability to protect web-services from unauthorized access, even if these services do not support it originally. This is achieved by intercepting incoming requests and testing if they contain a proper http-header. In case no such header is found, the request is redirected to a login page of Authentik.

It sounds great and doable. There are plenty of resources describing the configuration process. Unfortunately, I did not find a solution for K3S with Traefik. Getting it work cost me a lot of time and patience. The official documentation does not describe this case. So I would like to share this knowledge.

To be on the same page, here are the prerequisites:
1. Your instance of Authentik is deployed at https://authentik.domain1
2. The service you would like to protect is deployed in a K3S and available at https://service.domain2
3. A future Authentik Outpost will be accessible at https://outpost.domain3.
Please note, that domain1, domain2 and domain3 do not need to be different. They all can use 1 domain and be deployed in the same K3S cluster.

First of all, we install an Authentik Outpost using a helm chart from https://artifacthub.io/packages/helm/goauthentik/authentik-remote-cluster. The installation process ends with a kube-config. This config is reqiured to create an outpost integration in Authentik.

Later, you can use the integration to create an outpost for an app of your choice. The created outpost will automatically trigger a new ghcr.io/goauthentik/proxy deployment in the cluster which will connect to Authentik.

Here is a catch! The outpost needs to be exposed at https://outpost.domain3. There is a ping endpoint which must be testable via:
curl -i https://outpost.domain3/outpost.goauthentik.io/ping. A correct response contains HTTP/2 204. One way to expose the outpost is using Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: outpost-ingress
spec:
  ingressClassName: traefik
  rules:
  - host: outpost.domain3
    http:
      paths:
      - backend:
          service:
            name: ak-outpost
            port:
              number: 9000
        path: /
        pathType: Prefix

Finally, the target web-service needs to be re-configured to use the following Traefik Middleware with the exposed outpost:

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: authentik
spec:
  forwardAuth:
    address: https://outpost.domain3/outpost.goauthentik.io/auth/traefik
    trustForwardHeader: true
    authResponseHeaders:
      - X-authentik-username
      - X-authentik-groups
      - X-authentik-email
      - X-authentik-name
      - X-authentik-uid
      - X-authentik-jwt
      - X-authentik-meta-jwks
      - X-authentik-meta-outpost
      - X-authentik-meta-provider
      - X-authentik-meta-app
      - X-authentik-meta-version

The target web-service can be exposed via:

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: whoami-ingress
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: default-authentik@kubernetescrd
spec:
  ingressClassName: traefik
  rules:
    - host: https://service.domain2
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: whoami
                port:
                  number: 80

This configuration works for domain-level forward auth, where an auth cookie is set for the whole domain2 and all services within the domain, e.g. service2.domain2.

Single app forward auth is also possible, but needs changes to Ingress. Let me know if you are interested.

In this article I demonstrate how to enable JPA to produce SQL queries dynamically and execute them, for example:

select book_type, count(book.id) 
from book
where book.publish_date<=PARSEDATETIME('01-01-1900','dd-MM-yyy')
group by book.book_type

It is easy to use named queries and predefined method from JPA to query a database. However, this may not be enough. Some situations require generation of SQL queries during runtime, e.g. filtering or aggregation based on user-specified fields.

We start with a basic entity:

@Entity
@Table(name = "Book")
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column
    private String author;

    @Column
    private String title;

    @Column
    private Date publishDate;
    
    @Enumerated(EnumType.STRING)
    private BookType bookType;
}

The following repository definition allows us to access and to query the db:

@Repository
public interface BookRepo extends JpaRepository<Book, Long>, JpaSpecificationExecutor<Book>, GroupByRepository{
}

Extension of JpaSpecificationExecutor interface adds a support of JPA Specifications. This allows us to dynamically generate where-statements in the SQL query.

The interface GroupByRepository adds the aggregation functionality. Here is the definition:

public interface GroupByRepository {
    Map<Object, Long> whereGroupBy(SingularAttribute singularAttribute, Specification where);
}

The only method of the interface takes an attribute of the entity as a group-by argument, and the mentioned JPA specification. Here is an implementation of the interface, inspired by a post from stackoverflow:

public class GroupByRepositoryImpl implements GroupByRepository {
    @Autowired
    private EntityManager entityManager;
    @Override
    public Map<Object, Long> whereGroupBy(SingularAttribute singularAttribute, Specification where) {
        final CriteriaBuilder criteriaBuilder = entityManager.getCriteriaBuilder();
        final CriteriaQuery<Tuple> query = criteriaBuilder.createQuery(Tuple.class);
        final Root<Book> root = query.from(Book.class);
        final Path<String> expression = root.get(singularAttribute);
        query.multiselect(expression, criteriaBuilder.count(root));
        query.select(criteriaBuilder.tuple(expression, criteriaBuilder.count(root)));
        query.where(where.toPredicate(root, query, criteriaBuilder));
        query.groupBy(expression);
        final List<Tuple> resultList = entityManager.createQuery(query).getResultList();
        return resultList.stream()
                .collect(toMap(
                        t -> t.get(0, singularAttribute.getJavaType()),
                        t -> t.get(1, Long.class))
                );
    }
}

The following JUnit test contains an example of how to use the method:

@RunWith(SpringRunner.class)
@SpringBootTest
public class GroupByRepositoryTest {
    @Autowired
    BookRepo bookRepo;

    @Test
    public void groupByTest() {
        final Date Century20th = new Date(-2199999999999l);
        System.out.println(Century20th.toString());
        Specification<Object> where = Specification.where(
                (root, query, cb) -> cb.lessThanOrEqualTo(root.<Date>get("publishDate"), Century20th)
        );
        Map<Object, Long> result = bookRepo.whereGroupBy(Book_.bookType, where);
        System.out.println(result);
        Assert.assertEquals(2, result.entrySet().size());
    }
}

I showed you how you can use JPA Specification API to generate type-safe SQL queries dynamically instead of using query strings.

The sources are available here. Hopefully, you find this post useful.

Here is a pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.4</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <groupId>org.example</groupId>
    <artifactId>spring-boot</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
    </properties>

    <dependencies>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-batch</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.batch</groupId>
            <artifactId>spring-batch-test</artifactId>
            <scope>test</scope>
        </dependency>


        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-batch</artifactId>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>**/*IT.java</exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <id>integration-test</id>
                        <goals>
                            <goal>test</goal>
                        </goals>
                        <phase>integration-test</phase>
                        <configuration>
                            <excludes>
                                <exclude>**/*Test.java</exclude>
                            </excludes>
                            <includes>
                                <include>**/*IT.java</include>
                            </includes>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

As you can see maven-surefire-plugin allows us to execute integration tests separately from Unit tests. This enables faster development cycles without a need to wait until integration tests are finished.

Here is an example of a unit test:

@SpringBootTest
@AutoConfigureMockMvc
public class HelloControllerTest {

    @Autowired
    private MockMvc mvc;

    @Test
    public void index() throws Exception {
        mvc.perform(MockMvcRequestBuilders.get("/")
                .contentType(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andExpect(content().string(equalTo("greetings")));



    }
}

An example of an integration test follows:

package com.example.springboot;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.boot.web.server.LocalServerPort;
import org.springframework.http.ResponseEntity;
import org.springframework.test.context.ActiveProfiles;

import java.net.URL;
import java.util.Collection;

import static org.assertj.core.api.AssertionsForClassTypes.assertThat;

@ActiveProfiles("it")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class HelloControllerIT {
    @LocalServerPort
    private int port;

    private URL base;

    @Autowired
    private TestRestTemplate template;

    @BeforeEach
    public void setUp() throws Exception {
        this.base = new URL("http://localhost:" + port + "/");

    }

    @Test
    public void getHello() throws Exception {
        ResponseEntity<String> response =
            template.getForEntity(base.toString(), String.class);
        assertThat(response.getBody()).isEqualTo("greetings");
    }

    @Test
    public void getStudents() throws Exception {
        ResponseEntity<Collection> response = 
            template.getForEntity(base.toString() + "students", 
                                  Collection.class);
        assertThat(response.getBody().size()).isEqualTo(3);
    }
}

Finally here is an integration test of a Spring Batch pipeline:

package com.example.springboot;

import com.example.springboot.persistence.StudentRepository;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import org.springframework.batch.core.ExitStatus;
import org.springframework.batch.core.JobExecution;
import org.springframework.batch.core.JobInstance;
import org.springframework.batch.test.JobLauncherTestUtils;
import org.springframework.batch.test.JobRepositoryTestUtils;
import org.springframework.batch.test.context.SpringBatchTest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.annotation.DirtiesContext;
import org.springframework.test.context.ActiveProfiles;

import javax.sql.DataSource;

import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.is;


@SpringBatchTest
@SpringBootTest
@DirtiesContext
@ActiveProfiles("it")
public class SpringBatchIT {

    @Autowired
    DataSource dataSource;

    @Autowired
    private JobLauncherTestUtils jobLauncherTestUtils;

    @Autowired
    private JobRepositoryTestUtils jobRepositoryTestUtils;

    @Autowired
    private StudentRepository studentRepository;

    @AfterEach
    public void cleanUp() {
        jobRepositoryTestUtils.removeJobExecutions();
    }

    @Test
    public void batchTest() throws Exception {

        long countBefore = studentRepository.count();
        System.out.println(String.format("There are %d objects in DB 
                                  before running the test", countBefore));
        assertThat(countBefore, is(3L));


        JobExecution jobExecution = jobLauncherTestUtils.launchJob();
        
        
        JobInstance jobInstance = jobExecution.getJobInstance();
        ExitStatus jobExitStatus = jobExecution.getExitStatus();
        assertThat(jobInstance.getJobName(), is("firstJob"));
        assertThat(jobExitStatus.getExitCode(), is("COMPLETED"));


        long countAfter = studentRepository.count();
        System.out.println(String.format("There are %d objects in DB after
                                          running the test", countAfter));
        assertThat(countAfter, is(2L));

    }
}

You can also notice that the integration test classes are annotated using @ActiveProfiles. This helps to differentiate between unit and integration tests. To make use of them (and save time on package phase of maven build) I introduced a config file:

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName= org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect

spring.batch.job.enabled=false

The last parameter in the config file disables autostart of the Spring Batch pipeline.

Hi folks. This post is dedicated to the owners of NAS.

NAS are not particular safe, as they become targets to hacker attacks due to vulnerabilities due to "vendors don't give a sh*t". A common practice here is to block any access to NAS from the internet, which reduces their usefulness.

Here I show you one way to keep NAS secure while allowing access to it from the internet. I use a NAS from QNAP, but the approach is valid for other brands as well. Disclaimer: I am not responsible for your actions/losses and make sure you understand what you do.

The main ingredient of my solution is SSH. It allows remote connections to a server and offers configurations to minimize risks of unauthorized access. One such configuration is adding a 2-step authentication, which requires a temporal verification code.

Here are the steps:

1. Enable SSH in NAS.

This is the easiest step, can be done mostly from the web-ui of the NAS.

2. Install Entware.

Commonly, NAS run on a linux-based OS. These OSs are very limited in terms of available software. Entware solves this problem by allowing to install a great deal of linux-packages; yes, it is a package manager. The official website is https://entware.net/.

Before installing Entware on QNAP NAS, you have to add a 3-rd party repo https://www.qnapclub.eu/en/howto/1.  

Afterwards, Entware can be found using the search box.

3. Enable 2-step authentication.

Usually, this is achieved by adding google-authenticator-libpam and tuning the SSH configuration. Here is a helpful tutorial.

Some NAS vendors, e.g. Asustor, already pre-install all required packages. The only task is to enable the method by setting "UsePAM yes" in sshd_config.

Other vendors, such as QNAP, make our lives extremely difficult and such easy modifications are not feasible. However, here I show the way to achieve our goal and enable the 2-step authentication on QNAP NAS TS-253D with firmware v. 5.0.0. The following subsections are about it.

3.1 Installing a separate SSH on QNAP NAS.

The big problem of QNAP NAS firmware is the tools and their configs are hard-wired in the firmware. Modifications of any parameters will not survive a system restart, as the defaults are overwritten. A solution here is to store all necessary packages away from firmware-important locations and wire the SSH user to use those packages only.

This means, that we have install a separate SSH-server, which will create a new SSH session for the user. This new SSH-server can and must be configured to enable the 2-step authentication. Here is an outdated guide for the firmware v. 4.2.0.

Let's start. Connect to the NAS using the default SSH and install the packages:

opkg install openssh-server-pam google-authenticator-libpam

After a successful execution of the command, the new binaries will be placed in /opt/bin and /opt/sbin. The contents of /opt survive during NAS restarts.

Add the bin folders to $PATH:

export PATH=/opt/bin:/opt/sbin:$PATH

This tutorial shows how to add commands to autorun.sh, which will be automatically started on NAS restarts.

3.2 Configuring the SSH server.

Execute the commands:

ssh-keygen -f /opt/etc/ssh/ssh_host_rsa_key -t rsa
ssh-keygen -f /opt/etc/ssh/ssh_host_dsa_key -t dsa
ssh-keygen -f /opt/etc/ssh/ssh_host_ecdsa_key -t ecdsa
ssh-keygen -f /opt/etc/ssh/ssh_host_ed25519_key -t ed25519
useradd --system --no-create-home sshd
google-authenticator

The last command will start a wizard to generate required tokens with QR-code needed for your OTP-app.

Add the following lines to /opt/etc/pam.d/sshd:

#Google Authenticator 2-step auth.
auth required pam_google_authenticator.so nullok

Update /opt/etc/ssh/sshd_config with:

Port 322
UsePAM yes
ChallengeResponseAuthentication yes

Lastly, update the autorun.sh with (this enables autostart of the new SSH server):

/opt/etc/init.d/S40sshd start

In case the server is not started yet, you can manually execute the command.

4. Expose the endpoint.

Once the SSH-server is started, you can try to connect to it using the internal IP of the NAS, e.g.:

ssh -p 322 {user}@{NAS_IP}

If you want to access the NAS using SSH from the internet, you need to set up port-forwarding on your router (and, likely, to talk to you provider to turn on the feature). Make sure that you port-forward the new SSH server with port 322 (with enabled 2-step auth). Otherwise, with the default SSH server exposed to the internet, you put your NAS and local network in a great danger!

Final thoughts

I showed you here how you can make your NAS more useful by enabling a secure access to it over the internet. SSH is the most important service and the key to further possibilities, such as:

• A remote network folder (over SFTP) to store and access your files.
• a remote desktop environment (over ssh -X).
• a private streaming service, where your own music/movies/shows can be accessed via Kodi/Jellyfin.

Please let me know in the comments, what you want to learn next.

Here I show you the easiest way to start your own blog. Make sure you have a domain and a virtual server with docker behind.

We will deploy all needed software as Docker containers. Here is a code snippet that contains a specification for docker-compose:

version: '3'

services:

  traefik:
    image: traefik:v2.2
    container_name: traefik
    networks:
      - web
    command:
      
      - --log.level=DEBUG
      - --global.sendanonymoususage=false
      - --api.insecure=true
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443

      #Enable https
      - --certificatesresolvers.mychallenge.acme.httpchallenge=true
      - --certificatesresolvers.mychallenge.acme.httpchallenge.entrypoint=web
      - --certificatesresolvers.mychallenge.acme.email=your@email
      - --certificatesresolvers.mychallenge.acme.storage=/letsencrypt/acme.json
      - --certificatesresolvers.mychallenge.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory

    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./shared/letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:

      # middleware redirect
      - traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)
      - traefik.http.routers.http-catchall.entrypoints=web
      - traefik.http.routers.http-catchall.middlewares=redirect-to-https

      - traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https
      
      - traefik.enable=true
      - traefik.http.routers.traefik.rule=Host(`traefik.localhost`)
      - traefik.http.routers.traefik.entrypoints=websecure
      - traefik.http.services.traefik.loadbalancer.server.port=8080
      - traefik.http.routers.traefik.tls.certresolver=mychallenge
    restart: unless-stopped


  ghost:
    image: ghost:3.11
    container_name: ghost
    networks:
      - web
    environment:
      - url=https://localhost
    labels:
      - traefik.enable=true
      - traefik.http.routers.ghost.rule=Host(`localhost`)
      - traefik.http.routers.ghost.entrypoints=websecure
      - traefik.http.services.ghost.loadbalancer.server.port=2368
      - traefik.http.routers.ghost.tls.certresolver=mychallenge
    volumes:
      - ./shared/ghost:/var/lib/ghost/content


networks:
  web:

This specification is ready to run on a local Docker instance. Just paste it in a docker-compose.yaml and execute docker compose up.

This specification deploys 2 containers. The first container runs Traefik, a powerful reverse proxy, which routes traffic to a target service. You can access the Traefik dashboard at https://traefik.localhost. Ghost, a blog platform, is served by the second container. It is accessible at https://localhost.

As you might notice, the URLs contain https. When you follow the links, you browser should complain about invalid certificates and will recommend not to proceed to the websites. (Although it is completely safe to proceed in this example). Later we will learn how to generate valid certificates for your domain.

Traefik helps us to redirect our requests to the blog. You might type http://localhost as well and you would end-up at https. Besides redirection, Traefik takes care of certificate generation. Additional information on enabling HTTPS can be found here: https://docs.traefik.io/https/overview/.

The next item on the agenda is to schedule back-ups. The idea is to be able to archive the content of the blog and take the archive out of the system. The easiest way is to use existing popular version control systems such as Gitlab and Github.

An example that depicts all the discussed concepts are packed in a template, that you can download here (2 KB). The template has to be adapted to your infrastructure before use.

In this post, I showed you how to set up your own blog using available open-source tools. The setup requires a domain, a host and a git server for backups. The blog is one use-case of the Docker containerisation technology. In the upcoming posts, I will show how else you can use Docker to address some common needs.

This is my very first post on this beautiful platform.

I hope this blog will bring a lot of joy by expressing myself to me and useful thoughts, ideas and inspiration to my fellow readers.

I would like to keep the blog as open as possible, thus I will keep the comments section open for the public.