Using the Support Login Feature

Documentation Technical Docs
1

:book: This guide explains how to use the support_login management command, a secure feature intended for system administrators to gain temporary, one-time access to a user’s account for troubleshooting purposes.

Enabling the Feature

[!warning] This feature is disabled by default.

For security, you must explicitly enable this feature by setting the ALLOW_SUPPORT_LOGIN environment variable to True.

You can set this in your docker-compose.yml file for the specify7 service. You can also configure the token’s lifespan using SUPPORT_LOGIN_TTL (default is 180 seconds).

# Example snippet for docker-compose.yml

services:
  specify7:
    image: specify/specify7:latest
    environment:
      - ALLOW_SUPPORT_LOGIN=True
      - SUPPORT_LOGIN_TTL=180 # Optional: Time in seconds token is valid (default: 180)
    # ... other settings

How to Generate a Login Token

Follow these steps from a terminal on the host machine running your Docker instance.

  1. Enter the Specify 7 container:

    docker exec -it specify7 /bin/bash

  2. Run the management command:
    Inside the container’s shell, run the support_login command, replacing target_username with the username of the account you need to access.

    ve/bin/python manage.py support_login --username target_username

  3. Copy the token URL:
    The command will output a one-time-use URL. The token is only valid for the duration specified by SUPPORT_LOGIN_TTL.

    Example Output:

    specify@2384d44b795e:/opt/specify7$ ve/bin/python manage.py support_login --username sp7demofish
The following token is valid for 180 seconds:
/accounts/support_login/?token=1-1757106120-7394fa7d5ffc6f87fe8306d25c5b2c71b3f98942d9f9c46aea97f3eda725434b

  4. Use the login link:
    Append the generated path (e.g., /accounts/support_login/?token=...) to your instance’s base URL and paste the complete URL into your browser to log in as that user.

    Example: https://my-specify-instance.org/accounts/support_login/?token=...

Administrator Best Practices

[!danger] Important Security Recommendations

This feature is powerful. To maintain a secure instance, you must follow these security practices.

  1. Change the SECRET_KEY: Never use the default SECRET_KEY. Change it to a randomly generated, cryptographically secure value upon installation and rotate it periodically.
  2. Secure the Docker Network: Ensure no unnecessary ports are exposed from your Docker containers to the host machine or the wider internet. Specifically, the Redis container should only be accessible to other containers within the Docker network (like specify7), not to the outside world.
  3. Keep SUPPORT_LOGIN_TTL Small: The default of 180 seconds (3 minutes) is recommended. A shorter time reduces the window for an attacker to intercept and use a generated token.
  4. Monitor Logs: Regularly review your instance, database, and Redis logs for unauthorized access attempts or suspicious activity.

Security & Technical Details

[!info] How it Works (Technical Deep Dive)

This feature uses Redis and JWT (JSON Web Tokens) with AES-GCM encryption to ensure a secure, one-time login.

1. Redis Cache
The system uses the internal Redis cache to temporarily store a cryptographic “salt” and a verification key. This data is set to expire after the SUPPORT_LOGIN_TTL and is deleted immediately after the token is successfully used once. This makes the token truly single-use.

2. Cryptography Workflow

  • Token Generation:

    1. The support_login command generates two random 256-bit numbers (key_1 and key_2) and a salt.
    2. key_1 and the salt are stored together in the Redis cache.
    3. key_2 and the salt are hashed with the server’s SECRET_KEY to derive secure encryption and signing keys.
    4. The current timestamp and target user’s details are encrypted (using AES-GCM).
    5. A JWT is created containing the encrypted data, nonce, and MAC tag.
    6. The final URL given to you contains the JWT and key_2.

  • Token Parsing:

    1. When you visit the URL, the backend receives the JWT and key_2.
    2. It uses key_2 to look up the corresponding key_1 and salt from the Redis cache. (If not found, or if already used, the login fails).
    3. Once fetched, the entry is deleted from Redis.
    4. The system re-derives the encryption/signing keys using the fetched salt, the provided key_2, and the server’s SECRET_KEY.
    5. It verifies and decodes the JWT, decrypts the payload, and checks if the timestamp is still valid.
    6. If all checks pass, you are logged in as the target user.

This process ensures that an attacker would need to know the server’s SECRET_KEY, have read/write access to the Redis cache, and intercept a valid token all within the short SUPPORT_LOGIN_TTL window.