System architecture: move authentication to the API Gateway

When exposing an application to the outside world, consider a Reverse-Proxy or an API Gateway to protect it from attacks. Rate Limiting comes to mind first, but it shouldn’t stop there. We can factor many features in the API Gateway and should be bold in moving them from our apps. In this post, I’ll show how to implement authentication at the Gateway API stage.

Overall authentication flow

The API Gateway doesn’t authenticate but delegates authentication to an authentication provider. After authentication, the Gateway forwards the request to the app. The app checks authentication and gets the associated identity and permissions.

Overall Authentication Flow

Now, onto the implementation. We will implement the above flow with the following components:

  • Keycloak for the Identity Provider
  • Apache APISIX for the API Gateway
  • The Spring ecosystem for developing the app


Keycloak is a feature-rich Open Source identity provider:

Add authentication to applications and secure services with minimum effort. No need to deal with storing users or authenticating users.

Keycloak provides user federation, strong authentication, user management, fine-grained authorization, and more


Keycloak offers the realm abstraction, a namespace to group logically-related objects. We will first create an apisix Realm to our configuration from other configurations. The official documentation explains how to do it in great detail. We can proceed further with creating objects under the apisix realm.

The next step is to create an OpenID client for Apache APISIX to call Keycloak in the apisix realm. Here are the data:

  • General settings:
    • Client type: OpenID Connect
    • Client ID: apisix
  • Capability config:
    • Client authentication: ON

Go to the Credential tab and note the client’s secret value.

The final step is to create users. A user is a person who can log in to the system to access the app. Let’s create two users, john and jane, and set their passwords. The demo repository already has Keycloak pre-configured - both users' password is doe.

Spring Security

We secure our application via Spring Security.

Here are the required dependencies:

    <artifactId>spring-boot-starter-security</artifactId>        (1)
    <artifactId>spring-boot-starter-oauth2-client</artifactId>   (2)
1 Protect the application
2 Call the Keycloak server

The protecting code uses Spring Security:

bean {
    ref<HttpSecurity>().authorizeHttpRequests {
        it.requestMatchers("/*")                    (1)
            .hasAuthority("OIDC_USER")              (1)
    }.oauth2Login {}                                (2)
1 Any request requires to have the OIDC_USER authority
2 "Log in" via OAuth2

The next step is configuring the framework:

        client-id: apisix                                 (1)
        authorization-grant-type: authorization_code
        scope: openid
        issuer-uri: http://localhost:9009/realms/apisix   (2)
        user-name-attribute: preferred_username           (3)
1 Use the client created in Keycloak. We pass the secret at runtime via an environment variable
2 Keycloak realm to use. We override the domain in the Docker compose file via an environment variable
3 Use the user name instead of the token for display purposes

I’ll use a dummy Thymeleaf page to display the logged-in user. We need additional dependencies:

    <artifactId>thymeleaf</artifactId>                        (1)
    <artifactId>thymeleaf-spring6</artifactId>                (2)
    <artifactId>thymeleaf-extras-springsecurity6</artifactId> (3)
1 Thymeleaf proper
2 Thymeleaf and Spring integration
3 Offers dedicated Spring Security tags

The view is the following:

<!doctype html>
<html lang="en" xmlns:sec="http://www.thymeleaf.org/extras/spring-security">
    <h1>Welcome to My App</h1>
        <span sec:authentication="name">Bob</span>  (1)
1 Display the "name" of the logged-in user


Lastly, let’s configure the entry point into our system. I assume you’re familiar with this blog and don’t need an introduction to Apache APISIX. If you do, feel free to look at the APISIX, an API Gateway the Apache way.

In standalone mode, the configuration file is the following:

  - uri: /*
        "myapp:8080": 1
        discovery: http://keycloak:9009/realms/apisix/.well-known/openid-configuration  (1)
        client_id: apisix                                                              (2)
        client_secret: rjoVkMUDpUH4TE7IXhhJuof4O7OFrbph
        bearer_only: false
        scope: openid
        realm: apisix                                                                  (3)
        redirect_uri: http://localhost:9080/callback                                   (4)
1 Keycloak offers an endpoint that details every necessary endpoint for an OpenID integration
2 Use the same client as the app. In real-world scenarios, we should use one client per component, but it’s a demo
3 Use the realm created in the Keycloak section
4 Any URL that’s a subpath of the protected URL will do

Putting it all together

We put everything together via Docker Compose:

    image: apache/apisix:3.4.0-debian
      - ./config/apisix/config.yml:/usr/local/apisix/conf/config.yaml:ro               (1)
      - ./config/apisix/apisix.yml:/usr/local/apisix/conf/apisix.yaml:ro             (2)
      - "9080:9080"
    image: quay.io/keycloak/keycloak:22.0
      - /bin/bash
      - -c
      - |
        /opt/keycloak/bin/kc.sh import --file /opt/keycloak/data/import/keycloak.json --override true (3)
        /opt/keycloak/bin/kc.sh start-dev --http-port 9009                           (4)
      KEYCLOAK_ADMIN: admin
      - ./config/keycloak:/opt/keycloak/data/import:ro
      - "9009:9009"
    build: ./myapp
      SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_KEYCLOAK_ISSUER-URI: http://keycloak:9009/realms/apisix      (5) (6)
      LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY: DEBUG                              (7)
      - keycloak
    restart: on-failure                                                              (8)
1 Configure standalone mode
2 Routes and plugins configuration as seen in the previous section
3 Initialize Keycloak with the existing saved realm
4 Start Keycloak
5 Configure the OAuth client
6 Because the flow is browser-based, we will be redirected to a keycloak domain for authentication. Hence, we have to update our /etc/hosts with a new keycloak entry
7 Set Spring Security log level to debug helps understand issues
8 Spring Security eagerly tries to contact Keycloak. Keycloak takes a while to initialize itself; we need to let the app crash and start again until Keycloak is ready

Let’s try to access the application via Apache APISIX. When we browse to http://localhost:9080, Apache APISIX redirects us to the Keycloak login page:

Keycloak default authentication page

If we log in successfully, we are allowed to access the app. Notice that we display the username of the person who logged in:

App welcome page, showing successful authentication


In this post, we described how to move the authentication step to the API Gateway stage, delegate authentication to an identity provider, and let the app verify the authentication status. We implemented it with Apache APISIX, Keycloak, and Spring Security. Many other options are available, depending on your environment.

The complete source code for this post can be found on Github.
Nicolas Fränkel

Nicolas Fränkel

Developer Advocate with 15+ years experience consulting for many different customers, in a wide range of contexts (such as telecoms, banking, insurances, large retail and public sector). Usually working on Java/Java EE and Spring technologies, but with focused interests like Rich Internet Applications, Testing, CI/CD and DevOps. Also double as a trainer and triples as a book author.

Read More
System architecture: move authentication to the API Gateway
Share this