Configurable Web Authentication Token Time-to-LiveNEW!

Token Authentication Overview

The web interface supports two authentication mechanisms:

• Basic authentication: Username and password passed with each request
• Token authentication: Token generated once and reused for multiple requests during its validity period

Token authentication is particularly useful for automation tools and scripts that make multiple API calls, as it reduces the overhead of authenticating each request. Previously, authentication tokens were issued with a fixed 24-hour (86400 seconds) validity period. You can now configure a custom default TTL between 1 minute and 24 hours.

Configuring Token TTL

To configure the default token time-to-live:

configure web authentication token default-ttl <seconds>

Where seconds specifies the validity time in seconds (60-86400, default 86400).

Examples:

# Set 1-minute TTL for short-lived automation tasks
configure web authentication token default-ttl 60

# Set 1-hour TTL
configure web authentication token default-ttl 3600

# Restore default 24-hour TTL
configure web authentication token default-ttl 86400

The configuration persists across reboots.

Default TTL Behavior

The configured default TTL applies when an API request for token generation does not include a TTL property in the request body. If an API request specifies a TTL value, that value takes precedence over the configured default.

This allows individual API clients to request specific TTL values while providing a system-wide default for clients that do not specify a TTL.

Viewing Token TTL Configuration

To view the configured token TTL in the system configuration:

show configuration thttpd

Sample output:

#
# Module thttpd configuration.
#
enable web http
enable web https
configure ssl certificate hash-algorithm sha512
configure web authentication token default-ttl 60

To view the token TTL in switch management information:

show switch management

Sample output excerpt:

Web access                       : Enabled (tcp port 80)
                                 : Access Profile : not set
                                 : Auth token default TTL: 60 seconds

Generating Authentication Tokens

Authentication tokens are generated via API calls to the /auth/token endpoint. The token request includes a username and password:

curl --request POST \
  --url http://<switch-ip>/auth/token \
  --header 'content-type: application/json' \
  --data '{
  "username": "admin",
  "password": ""
}'

Sample response showing the configured TTL:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "ttl": 60
}

The ttl field in the response indicates the token's validity period in seconds.

Using Authentication Tokens

Include the authentication token in subsequent API requests using the x-auth-token header:

curl --request GET \
  --url 'http://<switch-ip>/rest/openapi/v0/state/slpp' \
  --header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...'

The token remains valid for the configured TTL period from the time it was generated. After the TTL expires, API requests using that token will fail with an authentication error, and a new token must be obtained.

Use Cases and Best Practices

Short-Lived Tokens (60-3600 seconds):

Appropriate for automation tools like Ansible modules that execute brief tasks. Shorter token lifetimes reduce the risk window if a token is compromised. Use short-lived tokens when:

• Running automated configuration scripts with a defined duration
• Integrating with CI/CD pipelines where jobs complete quickly
• Executing one-time API operations
• Security policies require frequent re-authentication

Standard Tokens (3600-86400 seconds):

Suitable for interactive sessions or longer-running automation tasks requiring extended token validity. Use standard tokens when:

• Running long-duration monitoring or data collection scripts
• Providing API access for interactive development and testing
• Integrating with management systems that maintain persistent connections
• Balancing security with operational convenience

Security Considerations:

• Shorter token lifetimes enhance security by limiting the time window during which a compromised token can be used
• Balance security requirements against operational needs when selecting a TTL value
• Store tokens securely in your automation tools and scripts
• Implement token refresh logic in long-running applications to handle token expiration gracefully
• Use HTTPS for all API communication to protect tokens in transit

Operational Considerations:

• Very short TTLs (60-300 seconds) may require frequent token regeneration in automation scripts
• Ensure your automation tools handle token expiration and renewal appropriately
• Monitor authentication failures that may indicate token expiration issues
• Document the configured TTL value for administrators and automation developers

Integration with Automation Tools

When integrating with automation tools such as Ansible:

1. Configure an appropriate token TTL based on typical task duration
2. Generate an authentication token at the start of the automation workflow
3. Use the token for all API requests during the workflow
4. Implement error handling to detect token expiration and generate a new token if needed
5. Store tokens securely using your automation platform's secret management features

Example workflow for a 5-minute Ansible playbook:

# Configure 10-minute token TTL to allow buffer time
configure web authentication token default-ttl 600

# Ansible playbook uses token authentication
# Token obtained at playbook start
# Token valid for entire playbook execution
# Token automatically expires after 10 minutes