Authentication with Keycloak

This tutorial introduces GeoServer Keycloak support and walks through the process of setting up authentication against an Keycloak provider. It is recommended that the Authentication chain section be read before proceeding.

The GeoServer Keycloak-authn/authz plugin will allow you to use an instance of Keycloak to control access to resources within GeoServer.

Installation Instructions

As the Keycloak Admin:

Note

In this example the Keycloak service runs on port 8080 while GeoServer runs on port 8181

  1. Create a new client for GeoServer named geoserver-client.

    ../../_images/keycloak_client001.png
  2. Make sure to add the base URL of GeoServer to the list of acceptable redirect paths, and add also the Keycloak OIDC endpoint base URI.

    eg:
    ../../_images/keycloak_client002.png
  3. Set the access-type of client as appropriate. If your GeoServer instance is depending on another service for authentication (eg: NGINX auth plugin) then you should probably select bearer-only. Otherwise, you should probably select confidential.

    ../../_images/keycloak_client003.png
  4. Add the the ADMINISTRATOR and AUTHENTICATED client-role to the geoserver-client in Keycloak.

    ../../_images/keycloak_client004.png

    In this phase you will need to map GeoServer Roles to the geoserver-client ones in Keycloak.

    ../../_images/keycloak_client005.png

    Use the AUTHENTICATED one for generic users. Assign this role ADMINISTRATOR to the users/groups who should have administrative access to GeoServer.

    ../../_images/keycloak_client006.png
  5. Obtain the installation-configuration for the geoserver-client in JSON, and provide this to the GeoServer Admin for the next steps.

    ../../_images/keycloak_client007.png

As the GeoServer Admin:

Note

In this example the Keycloak service runs on port 8080 while GeoServer runs on port 8181

  1. Under the Authentication UI, add a new authentication-filter. Select Keycloak from the list of provided options, and name your new filter keycloak_adapter. Paste the installation-configuration from the Keycloak-server in the text area provided.

    If not present, be sure to add the following options before clicking Save:

    "use-resource-role-mappings": true
    
    ../../_images/keycloak_adapter001.png

    The Enable redirect to Keycloak Login page checkbox should be checked if the desired behaviour is to authenticate on the web ui only through keycloak. Otherwise if the keycloak filter needs to coexists with other filter on the /web filter chain it must be unchecked. In this case we will keep it checked.

    The Role Source drop down enable the selection of the desired role source for the user being authenticated through keycloak. If none is selected by default the Active Role Service will be used.

  2. Add the keycloak_adapter to the web filter-chain if you want to protect the Admin GUI, as an instance. If you want to be redirected everytime to Keycloak, then remove all of the others chain filters (basic, form, rememberme, anonymous), otherwise you will need to access directly the login url on Keycloak.

    ../../_images/keycloak_adapter002.png
  3. Check your work so far by navigating to the GeoServer UI. You should see a Keycloak icon in the top right corner next to the Login button.

    ../../_images/keycloak_client010.png
  4. On clicking the Keycloak button you should be redirected to the Keycloak login-page, and after logging-in you should be redirected back to the actual GUI page.

    ../../_images/keycloak_adapter003.png

    You should verify that the message logged in as <USERNAME> is posted in the top right corner before continuing.

    ../../_images/keycloak_adapter004.png

Warning

Workaround in the event of a 403 unauthorized response after logging-in.

Enforce the algorithm RS256 in the keycloak client.

../../_images/keycloak_client008.png

Copy the public key for the RS256 algorithm from the Realm Settings into the adapter config as:

"realm-public-key": XXXXXXX
../../_images/keycloak_client009.png
../../_images/keycloak_adapter005.png