Authentication Configuration

AnyVar supports optional bearer token authentication for REST API endpoints. When enabled, all API requests must include a valid bearer token in the Authorization header. Authentication can be disabled by leaving all authentication environment variables unset.

Authentication Modes

AnyVar supports two modes of authentication that can be used independently or in combination:

  1. Literal Token Validation: Validate against a predefined list of static tokens

  2. JWT Token Validation: Validate JSON Web Tokens (JWT) using OpenID Connect (OIDC) workflow

If neither mode is configured (all authentication environment variables are unset), authentication is disabled and no bearer token is required.

Authentication Behavior

When authentication is enabled, AnyVar validates bearer tokens as follows:

  • If ANYVAR_AUTH_TOKEN_LIST is configured, the token is checked against the list of allowed literal tokens

  • If JWT validation is configured (ANYVAR_AUTH_ISSUER_URL and ANYVAR_AUTH_JWKS_URI are set), the token is validated as a JWT

  • If the token matches either validation method, the request is authorized

  • If the token fails both validation methods (or if no validation methods are configured but a token is provided), a 401 Unauthorized response is returned

JWT tokens are cached after successful validation to improve performance and reduce repeated validation overhead. The cache automatically purges expired tokens every hour.

Configuration Parameters

Literal Token Authentication

Use this mode to validate against a static list of pre-shared tokens.

Environment Variable

Description

ANYVAR_AUTH_TOKEN_LIST

Comma-separated list of literal bearer tokens that are accepted for authentication. Example: "token1,token2,token3"

JWT Token Authentication

Use this mode to validate JWT tokens issued by an OpenID Connect provider. Both ANYVAR_AUTH_ISSUER_URL and ANYVAR_AUTH_JWKS_URI must be set for JWT validation to be enabled.

Required Parameters

Environment Variable

Description

ANYVAR_AUTH_ISSUER_URL

JWT issuer URL (iss claim). The token’s iss claim must match this value exactly.

ANYVAR_AUTH_JWKS_URI

JWKS (JSON Web Key Set) URI used to retrieve public keys for JWT signature validation. Example: "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys"

Optional Claim Validation

These optional parameters enable validation of specific JWT claims. If set, tokens must satisfy the configured constraints:

Environment Variable

Description

ANYVAR_AUTH_AUDIENCES

Comma-separated list of allowed audience values (aud claim). At least one audience in the token must match one of the configured audiences.

ANYVAR_AUTH_APPIDS

Comma-separated list of allowed application IDs (appid claim). The token’s appid claim must match one of the configured values.

ANYVAR_AUTH_SCOPES

Comma-separated list of required scopes (scope claim). The token must contain at least one of the configured scopes.

ANYVAR_AUTH_EMAILS

Comma-separated list of allowed email addresses (email claim). The token’s email claim must match one of the configured values (case-insensitive).

ANYVAR_AUTH_SUBJECTS

Comma-separated list of allowed subject values (sub claim). The token’s sub claim must match one of the configured values.

JWT Token Requirements

All JWT tokens must include the following claims:

  • iat (issued at time)

  • exp (expiration time)

  • iss (issuer)

  • sub (subject)

Tokens are validated for signature authenticity, expiration, and issuer. The signature is verified using RS256 algorithm with public keys retrieved from the JWKS URI.

Example Configuration

Literal Token Authentication

# Enable authentication with literal tokens
ANYVAR_AUTH_TOKEN_LIST="my-secret-token-1,my-secret-token-2"

JWT Token Authentication with Azure AD

# Enable JWT authentication with Azure AD
ANYVAR_AUTH_ISSUER_URL="https://login.microsoftonline.com/{tenant-id}/v2.0"
ANYVAR_AUTH_JWKS_URI="https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys"
ANYVAR_AUTH_AUDIENCES="api://{client-id}"
ANYVAR_AUTH_SCOPES="access_as_user"

Combined Authentication

# Accept both literal tokens and JWT tokens
ANYVAR_AUTH_TOKEN_LIST="admin-token-123"
ANYVAR_AUTH_ISSUER_URL="https://login.microsoftonline.com/{tenant-id}/v2.0"
ANYVAR_AUTH_JWKS_URI="https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys"
ANYVAR_AUTH_AUDIENCES="api://{client-id}"

Using Bearer Tokens

When authentication is enabled, include the bearer token in the Authorization header of all API requests:

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://your-anyvar-instance.com/variation

Without a valid token, requests will receive a 401 Unauthorized response.

Security Considerations

  • Keep tokens secure: Never commit literal tokens to version control. Use environment variables or secret management systems.

  • Use HTTPS: Always deploy AnyVar with HTTPS in production to protect tokens in transit.

  • Token rotation: Regularly rotate literal tokens and use short-lived JWT tokens when possible.

  • Principle of least privilege: Configure claim validation (audiences, scopes, emails, subjects) to restrict access to only authorized users and applications.

  • Monitor authentication logs: Review authentication logs for unauthorized access attempts.