Key authentication module¶

Limitations¶

The authkey module is meant to be used with OGC services. It won’t work properly against the administration GUI, nor RESTConfig.

The authkey module replaces the default basic authentication provider, therefore when editing a user the Enabled checkbox does not affect the authkey provider and you cannot disable users this way.

Key providers¶

Key providers are responsible for mapping the authentication keys to a user. The authentication key itself is a UUID (Universally Unique IDentifier (UUID)). A key provider needs a user/group service and it is responsible for synchronizing the authentication keys with the users contained in this service.

# Format is authkey=username
b52d2068-0a9b-45d7-aacc-144d16322018=admin
1825efd3-20e1-4c18-9648-62c97d3ee5cb=sf
ef18d7e7-963b-470f-9230-c7f9de166888=topp

Configuration¶

Configuration can be done using the administrator GUI. There is a new type of authentication filter named authkey offering the following options.

1. URL parameter name. This the name of URL parameter used in client HTTP requests. Default is authkey.

2. Key Provider. GeoServer offers the providers described above.

3. User/group service to be used.

Some of the key providers can require additional configuration parameter. These will appear under the Key Provider combo-box when one of those is selected.

After configuring the filter it is necessary to put this filter on the authentication filter chain(s).

Challenge Anonymous Session¶

“Challenge Anonymous Sessions” is designed to enforce stricter authorization and stateless behavior.

When enabled, the filter ignores any existing session or SecurityContext principal (e.g., anonymous or previously authenticated sessions created by other filters) and always authenticates the user linked to the provided authkey. This ensures that the authkey is validated independently for every request, regardless of the current session state.

This feature is particularly useful for deployments that require stateless authentication or need to ensure that requests are processed strictly based on the authkey query parameter. By default, this option is disabled.

Internal User Cache

To enhance performance in stateless mode, the AuthKey filter can use an internal user cache. The cache prevents unnecessary backend authentication requests for the same authkey by storing the user information locally for a configurable period.

The cache offers the following benefits:

1. Reduces backend service load for frequently used authkeys.

2. Allows administrators to configure the cache’s expiration policy to balance performance and data freshness.

Both the “Challenge Anonymous Sessions” option and the internal user cache settings can be configured through the filter’s settings panel in GeoServer. For step-by-step instructions and examples, refer to the screenshots below.

Enabling Mappers’ Auto-Synchronization¶

The following check is available for all provides.

If enabled, the service will automatically invoke the corresponding mapper synchronize method; the one associated to the current AuthKey provider.

By default the synchronization happens every 60 seconds. In the case an administrator needs to change the auto-sync frequency, he will need to:

1. Edit the file applicationContext.xml within the gs-authkey jar file

2. Edit the property autoSyncDelaySeconds of the authenticationKeyProvider bean

3. Restart GeoServer

Provider pluggability¶

With some Java programming it is possible to programmatically create and register a new key to user name mapper that works under a different logic. For example, you could have daily tokens, token generators and the like.

In order to provide your custom mapper you have to implement the org.geoserver.security.AuthenticationKeyMapper interface and then register said bean in the Spring application context. Alternatively it is possible to subclass from org.geoserver.security.AbstractAuthenticationKeyMapper. A mapper (key provider) has to implement

/**
 *
 * Maps a unique authentication key to a username. Since usernames are
 * unique within a {@link GeoServerUserGroupService} an individual mapper
 * is needed for each service offering this feature.
 *
 * @author Andrea Aime - GeoSolution
 */
public interface AuthenticationKeyMapper extends BeanNameAware {

    /**
     * Maps the key provided in the request to the {@link GeoServerUser} object
     * of the corresponding user, or returns null
     * if no corresponding user is found
     *
     * Returns <code>null</code> if the user is disabled
     *
     * @param key
     * @return
     */
    GeoServerUser getUser(String key) throws IOException;

    /**
     * Assures that each user in the corresponding {@link GeoServerUserGroupService} has
     * an authentication key.
     *
     * returns the number of added authentication keys
     *
     * @throws IOException
     */
    int synchronize() throws IOException;

    /**
     * Returns <code>true</code> it the mapper can deal with read only u
     * user/group services
     *
     * @return
     */
    boolean supportsReadOnlyUserGroupService();

    String getBeanName();

    void setUserGroupServiceName(String serviceName);
    String getUserGroupServiceName();

    public GeoServerSecurityManager getSecurityManager();
    public void setSecurityManager(GeoServerSecurityManager securityManager);

 }

The mapper would have to be registered in the Spring application context in a applicationContext.xml file in the root of your jar. Example for an implementation named com.mycompany.security.SuperpowersMapper:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
<beans>
  <bean id="superpowersMapper" class="com.mycompany.security.SuperpowersMapper"/>
</beans>

At this point you can drop the authkey jar along with your custom mapper jar and use it in the administrator GUI of the authentication key filter.