API Gateway APISIX Integrates Keycloak for Authentication

This article shows you how to use OpenID-Connect protocol and Keycloak for identity authentication in Apache APISIX through detailed steps.

Click to Preview

Keycloak is an open source identity and access management solution for modern applications and services. Keycloak supports Single-Sign On, which enables services to interface with Keycloak through protocols such as OpenID Connect, OAuth 2.0, etc. Keycloak also supports integrations with different authentication services, such as Github, Google and Facebook.

In addition, Keycloak also supports user federation, and can import users through LDAP and Kerberos. For more information about Keycloak, please refer to the official documentation.

How to Use​

Environment Preparation​

Make sure that Apache APISIX is started in your environment before proceeding with the following steps.

Start Keycloak​

Here we use docker-compose to start Keycloak with PostgreSQL.

version: '3.7'

services:
  postgres:
      image: postgres:12.2
      container_name: postgres
      environment:
        POSTGRES_DB: keycloak
        POSTGRES_USER: keycloak
        POSTGRES_PASSWORD: password

  keycloak:
      image: jboss/keycloak:9.0.2
      container_name: keycloak
      environment:
        DB_VENDOR: POSTGRES
        DB_ADDR: postgres
        DB_DATABASE: keycloak
        DB_USER: keycloak
        DB_PASSWORD: password
        KEYCLOAK_USER: admin
        KEYCLOAK_PASSWORD: password
        PROXY_ADDRESS_FORWARDING: "true"
      ports:
        - 8080:8080
      depends_on:
        - postgres

docker-compose up

After execution, you need to verify that Keycloak and postgres have started successfully.

docker-compose ps

Configure Keycloak​

After Keycloak is started, use your browser to access "http://127.0.0.1:8080/auth/admin/" and type the admin/password account password to log in to the administrator console.

Create a realm​

First, you need to create a realm named apisix_test_realm. In Keycloak, a realm is a workspace dedicated to managing projects, and the resources of different realms are isolated from each other.

The realm in Keycloak is divided into two categories: one is the master realm, which is created when Keycloak is first started and used to manage the admin account and create other realm. the second is the other realm, which is created by the admin in the master realm and can be used to create, manage and use users and applications in this realm. The second category is the other realm, created by admin in the master realm, where users and applications can be created, managed and used. For more details, please refer to the realm and users section in Keycloak.

Click to Preview

Click to Preview

Create a Client​

The next step is to create the OpenID Connect Client. In Keycloak, Client means a client that is allowed to initiate authentication to Keycloak.

In this example scenario, Apache APISIX is equivalent to a client that is responsible for initiating authentication requests to Keycloak, so we create a Client with the name apisix. More details about the Client can be found in Keycloak OIDC Clients.

Click to Preview

Click to Preview

Configure the Client​

After the Client is created, you need to configure the Apache APISIX access type for the Client.

In Keycloak, there are three types of Access Type:

1. Confidential: which is used for applications that need to perform browser login, and the client will get the access token through client secret, mostly used in web systems rendered by the server.
2. Public: for applications that need to perform browser login, mostly used in front-end projects implemented using vue and react.
3. Bearer-only: for applications that don't need to perform browser login, only allow access with bearer token, mostly used in RESTful API scenarios.

For more details about Client settings, please refer to Keycloak OIDC Clients Advanced Settings.

Since we are using Apache APISIX as the Client on the server side, we can choose either "confidential" Access Type or "Bearer-only" Access Type. For the demonstration below, we are using "confidential" Access Type as an example.

Click to Preview

Create Users​

Keycloak supports interfacing with other third-party user systems, such as Google and Facebook, or importing or manually creating users using LDAP . Here we will use "manually creating users" to demonstrate.

Click to Preview

Click to Preview

Then set the user's password in the Credentials page.

Click to Preview

Create Routes​

After Keycloak is configured, you need to create a route and open the Openid-Connect plugin . For details on the configuration of this plugin, please refer to the Apache APISIX OpenID-Connect plugin.

Get client_id and client_secret​

Click to Preview

In the above configuration.

• client_id is the name used when creating the Client before, i.e. apisix
• client_secret should be obtained from Clients-apisix-Credentials, for example: d5c42c50-3e71-4bbbe-aa9e-31083ab29da4.

Get the discovery configuration​

Click to Preview

Go to Realm Settings-General-Endpoints, select the OpenID Endpoint Configuration link and copy the address that the link points to, for example:http://127.0.0.1:8080/auth/realms/apisix_test_realm/.well-known/openid-configuration.

Create a route and enable the plug-in​

Use the following command to access the Apache APISIX Admin interface to create a route, set the upstream to httpbin.org, and enable the plug-in OpenID Connect for authentication.

Note: If you select bearer-only as the Access Type when creating a Client, you need to set bearer_only to true when configuring the route, so that access to Apache APISIX will not jump to the Keycloak login screen.

curl  -XPOST 127.0.0.1:9080/apisix/admin/routes -H "X-Api-Key: edd1c9f034335f136f87ad84b625c8f1" -d '{
    "uri":"/*",
    "plugins":{
        "openid-connect":{
            "client_id":"apisix",
            "client_secret":"d5c42c50-3e71-4bbe-aa9e-31083ab29da4",
            "discovery":"http://127.0.0.1:8080/auth/realms/apisix_test_realm/.well-known/openid-configuration",
            "scope":"openid profile",
            "bearer_only":false,
            "realm":"apisix_test_realm",
            "introspection_endpoint_auth_method":"client_secret_post",
            "redirect_uri":"http://127.0.0.1:9080/"
        }
    },
    "upstream":{
        "type":"roundrobin",
        "nodes":{
            "httpbin.org:80":1
        }
    }
}'

Access Testing​

Once the above configuration is complete, we are ready to perform the relevant access tests in Apache APISIX.

Access Apache APISIX​

Use your browser to access http://127.0.0.1:9080/image/png.

Since the OpenID-Connect plugin is enabled and bearer-only is set to false, when you access this path for the first time, Apache APISIX will redirect to the login screen configured in apisix_test_realm in Keycloak and make a user login request.

Click to Preview

Enter the User peter created during the Keycloak configuration to complete user login.

Successful access​

After a successful login, the browser will again redirect the link to http://127.0.0.1:9080/image/png and will successfully access the image content. The content is identical to that of the upstream http://httpbin.org/image/png.

Click to Preview

Logout​

After the test, use your browser to access "http:/127.0.0.1:9080/logout" to logout your account.

Note: The logout path can be specified by logout_path in the OpenID-Connect plug-in configuration, the default is logout.

Summary​

This article shows the procedure of using OpenID-Connect protocol and Keycloak for authentication in Apache APISIX. By integrating with Keycloak, Apache APISIX can be configured to authenticate and authenticate users and application services, which greatly reduces the development work involved.

For more information about the implementation of authentication in Apache APISIX with Okta, see this article.