---
title: Auth server ACL plugins
sidebar_label: Auth server ACL plugins
---

System administrators can create Deephaven Authentication Server plugins that execute Java code upon certain Authentication Server actions, such as user login or token verification.

This document describes a specific use case in which an "Auth Hook" (plugin) can be created to request and parse data from an external server and then import that data into the Deephaven system. The imported data may then be utilized in the ACL Editor by a corresponding, custom filter generator.

The following graphic demonstrates the general process:

![A diagram showing how the "Auth Hook" requests, parses, and imports data from an external system into Deephaven](../../assets/sys-admin/permissions/authhook.png)

Implementing this system requires four steps:

1. Create the authentication server plugin by creating a class that implements the `AuthHookModule` interface.
2. Specify the plugin through the `authentication.server.hooks.class` property.
3. Set up a tailer to import logged data real-time.
4. Create a custom filter generator that utilizes the imported data within an ACL.

## `AuthHookModule` interface

To create your authentication hook, you must create a class that implements the `com.illumon.iris.auth.AuthHookModule` interface and overrides its methods.

The `AuthHookModule` interface follows:

```java
package com.illumon.iris.auth;

import io.deephaven.enterprise.auth.UserContext;

/**
 * This interface allows you to run actions after useful authentication server operations; for example you may use an
 * AuthHookModule to perform post-login refresh of ACL entries.
 *
 * Implementations must implement a Constructor which takes a {@link com.fishlib.io.logger.Logger}.
 */
public interface AuthHookModule {
    /**
     * Called after a client successfully logs in to the authentication server.
     *
     * @param userContext the userContext of the login
     */
    void onLogin(UserContext userContext);

    /**
     * Called after a client logs out from the authentication server (i.e. disconnects).
     *
     * @param userContext the userContext of the terminating connection
     */
    void onLogout(UserContext userContext);

    /**
     * Called after an authentication token is created.
     *
     * @param authenticatedContext the context of the user creating the token
     * @param service the service the user is creating a token for
     */
    void onTokenCreate(UserContext authenticatedContext, String service);

    /**
     * Called after an authentication token is verified
     *
     * @param authenticatedContext the context of the verified token
     * @param service the service for which the token is valid
     */
    void onTokenVerify(UserContext authenticatedContext, String service);

    /**
     * Called after an authentication token fails verification
     *
     * @param authenticatedContext the context of the verified token
     * @param service the service for which the token is valid
     */
    void onTokenVerifyFailure(UserContext authenticatedContext, String service);

    /**
     * Called after the authentication server configuration is reloaded.
     */
    void onReload();

    class Null implements AuthHookModule {

        @Override
        public void onLogin(UserContext userContext) {

        }

        @Override
        public void onLogout(UserContext userContext) {

        }

        @Override
        public void onTokenCreate(UserContext authenticatedContext, String service) {

        }

        @Override
        public void onTokenVerify(UserContext authenticatedContext, String service) {

        }

        @Override
        public void onTokenVerifyFailure(UserContext authenticatedContext, String service) {

        }

        @Override
        public void onReload() {

        }
    }
}
```

The nested `com.illumon.iris.auth.AuthHookModule.Null` class provides an implementation with empty methods, which you may use as your base class. By using the Null implementation as your base, you only need to implement methods required for your use case, and your extension will continue to compile if additional methods are added to the `AuthHookModule` interface.

## Authentication server hooks property

To utilize the `AuthHookModule` implementation, you must specify the fully qualified class name of the hook in the `authentication.server.hooks.class` property:

```
authentication.server.hooks.class=<fully qualified class name>
```

## Data import

Authentication hooks may utilize a logger like a client logger application would. If this is the case, you will need to set up a tailer to import the logged data real-time. Please refer to [Importing Data > Deephaven Data Tailer](../configuration/data-tailer.md) for an example of tailer installation and configuration.

## Custom filter generator

If you'd like to utilize the imported data in the ACL Editor, you must create a class that implements the FilterGenerator interface, and then apply it as an ACL. Refer to the [Deephaven Javadoc](https://docs.deephaven.io/javadoc/20240517/com/illumon/iris/db/v2/permissions/FilterGenerator.html) and the [Table ACLs](./table-acls.md#custom-filter-generators) documentation to learn more.

## Related documentation

- [Table ACLs](./table-acls.md)
- [DACS integration](./dacs-integration.md)
- [Importing Data > Deephaven Data Tailer](../configuration/data-tailer.md)
- [Permissions overview](./permissions-overview.md)