Synchronizing Tokens

When a user has authenticated successfully with a server, a token is issued that is passed back and forth in a cookie. These tokens may be long-lived with a default expiration time of seven days and normally automatically reissued. So when the server is regularly used, the user will rarely need to log in again. Similarly, API tokens never expire.

Normally, a token issued by one server is only valid on that server. The server keeps track of issued tokens and validates each incoming token against its stored tokens. Furthermore, tokens are revoked when an administrator logs out a user, and the token is removed from the server’s list.

If there are multiple servers that is being used as a cluster with a load balancer in front, they should be configured to have synchronized tokens. Even if the load balancer uses sticky sessions as it should, a token is typically valid for a longer time than a sessions lasts, and the user should not have to log in again just because a new session is directed to a different server than last time.

Token synchronization uses a different mechanism from repository synchronization. The repository stores content with its change history, and there are scenarios where the user may want to synchronize one and not the other. For example, there may be one QA server and one production server then use a common login.

Tokens are synchronized through the cluster shared store. By default, this is just a subdirectory <appdata>/shared/ which is not synchronized. The store also keeps other types of non-content data that the user may want to synchronize between servers.

To enable token synchronization:

q  Change the property cluster.shared.store.type from its default PRIVATE_DIRECTORY to SHARED_DIRECTORY.

q  Set cluster.shared.store.shared_directory.path to a location that is accessible from all servers. On Kubernetes, this would typically be a volume that you mount on a path in the container.

q  Ensure all servers use the same cookie name in authentication.token.cookie, or a cookie issued by one server would not be visible to another.