Configuring Keycloak Authentication

This document explains how to configure Zuul and Keycloak in order to enable authentication in Zuul with Keycloak. It’s written with Keycloak 23 in mind, but should probably work for other versions with only minor adjustments.

Prerequisites

• The Zuul instance must be able to query Keycloak over HTTPS.

• Authenticating users must be able to reach Keycloak’s web UI.

• Have a realm set up in Keycloak. Instructions on how to do so can be found here .

By convention, we will assume the Keycloak server’s FQDN is keycloak, and Zuul’s Web UI’s base URL is https://zuul/. We will use the realm my_realm.

Most operations below regarding the configuration of Keycloak can be performed through Keycloak’s admin CLI. The following steps must be performed as an admin on Keycloak’s GUI.

Setting up Keycloak

Create a client

Choose the realm my_realm, then click clients in the Configure panel. Click Create.

Give your client whatever ID you please; we will pick zuul for this example. Also this example assumes your Zuul WebUI is served from a host referred to as zuul.example.org in DNS. Make sure to fill the following fields:

• General settings (page 1):

  • Client type: OpenID Connect (default)

  • Client ID: zuul (or whatever else you want)

• Capability config (page 2):

  • Client authentication: Off (default)

  • Authentication flow:

    • Standard flow: On (default)

    • Direct access grants: On (default)

    • Implicit flow: On

• Login settings (page 3):

  • Valid redirect URIs: https://zuul.example.org/*

  • Web origins: https://zuul.example.org (no trailing / here)

Click “Save” when done.

Create a client scope

Keycloak maps the client ID to a specific claim, instead of the usual aud claim. We need to configure Keycloak to add our client ID to the aud claim by creating a custom client scope for our client.

Choose the realm my_realm, then click client scopes in the Configure panel. Click Create.

Name your scope as you please. We will name it zuul_aud for this example. Make sure you fill the following fields:

• Name: zuul_aud

• Protocol: OpenID Connect (default)

• Include in Token Scope: On (default)

Click “Save” when done.

On the Client Scopes page, click on zuul_aud to configure it; click on Mappers then Configure a new mapper and select Audience from the list it presents.

On the resulting form, name the mapper whatever you want (our example will use zuul_map), and make sure to fill the following:

• Name: zuul_map

• Included client audience: zuul

• Add to ID token: On

• Add to access token: On (default)

Then save.

Finally, go back to the clients list and pick the zuul client again. Click on Client scopes and click the Add client scope button. Pick the checkbox next to the zuul_aud scope you created and click the Add button choosing the Default option from the list that subsequently pops up.

(Optional) Set up a social identity provider

Keycloak can delegate authentication to predefined social networks. Follow these steps to find out how.

If you don’t set up authentication delegation, make sure to create at least one user in your realm, or allow self-registration. See Keycloak’s documentation section on user management for more details on how to do so.

Setting up Zuul

Edit the /etc/zuul/zuul.conf to add the keycloak authenticator:

[auth keycloak]
default=true
driver=OpenIDConnect
realm=my_realm
issuer_id=https://keycloak/auth/realms/my_realm
client_id=zuul

Restart Zuul services (scheduler, web).

Head to your tenant’s status page. If all went well, you should see a “Sign in” button in the upper right corner of the page. Congratulations!

Further Reading

This How-To is based on Keycloak’s documentation, specifically the documentation about clients.