Skip to main content

Client and CLI Authentication

Client and CLI Authentication secures access to protected resources by verifying the identity of non-human clients and human users interacting through command-line interfaces. It ensures that only authorized entities can perform operations, maintaining the integrity and confidentiality of your services.

Primary Purpose​

The primary purpose of client and CLI authentication is to establish trust between a client application or a command-line interface and the backend services it interacts with. This involves:

  • Identity Verification: Confirming that the client or user is who they claim to be.
  • Access Control: Granting or denying access to specific resources or operations based on the verified identity and associated permissions.
  • Auditing: Providing a verifiable trail of actions performed by authenticated entities.

Core Features​

The authentication system provides robust mechanisms for managing client and CLI identities and their access.

  • Multiple Authentication Flows: Supports various methods tailored for different client types:
    • API Key Authentication: Simple, stateless authentication for automated scripts and services using a pre-shared secret.
    • OAuth 2.0 Client Credentials Grant: Ideal for machine-to-machine communication where a client application needs to access resources on its own behalf, without user involvement.
    • OAuth 2.0 Authorization Code Grant with PKCE: Designed for CLI applications, enabling secure user login through a browser and subsequent token exchange without exposing secrets.
    • JSON Web Token (JWT) Handling: Generates, validates, and decodes JWTs for secure information exchange and session management.
  • Credential Management: Facilitates secure storage and retrieval of authentication credentials.
    • Configuration Files: Supports storing API keys, client IDs, and other configuration details in secure, user-specific files (e.g., ~/.config/my_app/credentials.json).
    • Environment Variables: Allows credentials to be provided via environment variables, suitable for CI/CD pipelines and containerized environments.
    • Interactive Prompts: For CLI users, provides interactive prompts for usernames, passwords, or multi-factor authentication (MFA) codes.
  • Token Lifecycle Management: Handles the entire lifecycle of access tokens.
    • Token Generation: Issues new access tokens upon successful authentication.
    • Token Validation: Verifies the authenticity, expiry, and scope of incoming tokens.
    • Token Refresh: Automatically renews expired access tokens using refresh tokens, minimizing user re-authentication.
    • Token Revocation: Provides mechanisms to invalidate compromised or no-longer-needed tokens.
  • Session Management: For CLI interactions, maintains authenticated sessions, reducing the need for repeated logins.
  • Error Handling and Feedback: Provides clear, actionable error messages for authentication failures, aiding in debugging and user experience.

Common Use Cases​

Client and CLI authentication is essential for a wide range of scenarios where programmatic or command-line access to services is required.

  • Automated Scripting: A Python script needs to upload data to a cloud storage service. The script authenticates using an API key or OAuth 2.0 client credentials to obtain an access token, which is then used to authorize the upload request.

    from my_app.auth import AuthClient
    from my_app.api import StorageClient

    # Authenticate using an API key configured via environment variable or config file
    auth_client = AuthClient.from_config()
    access_token = auth_client.get_access_token()

    storage_client = StorageClient(token=access_token)
    storage_client.upload_file("data.csv", "my-bucket/data.csv")

  • CI/CD Pipelines: A continuous integration pipeline deploys a new version of a service. The pipeline authenticates with the deployment service using client credentials, ensuring that only the authorized pipeline can initiate deployments.

    # Example using a CLI tool within a CI/CD pipeline
    # MY_APP_CLIENT_ID and MY_APP_CLIENT_SECRET are set as environment variables
    my-app deploy service-name --version 1.2.3 --region us-east-1

    The underlying CLI utility automatically uses the environment variables to perform an OAuth 2.0 Client Credentials grant.

  • Developer CLI Tools: A developer uses a command-line tool to manage resources (e.g., virtual machines, databases). The CLI utility guides the user through an interactive browser-based login (OAuth 2.0 Authorization Code Grant with PKCE), caches the resulting tokens, and automatically refreshes them for subsequent commands.

    # First-time login
    my-app login
    # (Opens browser for authentication, then returns to CLI)

    # Subsequent commands use the cached token
    my-app list vms
    my-app create database --name my-prod-db

  • Third-Party Integrations: An external analytics platform needs to pull data from your service. It authenticates using a dedicated API key or OAuth 2.0 client credentials provided by your system, ensuring secure and controlled data access.

Integration Points and Best Practices​

Integrating the authentication system involves configuring credentials and ensuring they are correctly applied to outgoing requests.

  • Client Initialization: When creating client instances for your services, pass the authenticated session or token. The AuthClient provides methods to retrieve valid tokens.

    from my_app.auth import AuthClient
    from my_app.service import MyServiceClient

    # Initialize AuthClient, which can load credentials from config or env vars
    auth_client = AuthClient()

    # Obtain an authenticated session or token
    # The get_authenticated_session() method handles token refresh automatically
    authenticated_session = auth_client.get_authenticated_session()

    # Pass the session to your service client
    service_client = MyServiceClient(session=authenticated_session)
    data = service_client.fetch_data()

  • CLI Configuration: For CLI tools, the CLIAuthenticator component manages user profiles and token caching. Users can switch between different authentication contexts (e.g., different accounts or environments).

    from my_app.cli_auth import CLIAuthenticator

    # Configure a new profile
    CLIAuthenticator.configure_profile("dev-env", client_id="...", client_secret="...")

    # Log in to a specific profile
    CLIAuthenticator.login(profile_name="dev-env")

    # Get the active authenticated client for CLI commands
    active_client = CLIAuthenticator.get_active_client()

  • Security Considerations:

    • Never hardcode credentials directly in source code. Use environment variables, secure configuration files, or secret management services.
    • Use short-lived access tokens to minimize the impact of token compromise. Rely on refresh tokens for long-term access.
    • Securely store refresh tokens and API keys. For CLI tools, this typically means encrypted storage on the user's local machine.
    • Implement rate limiting on authentication endpoints to mitigate brute-force attacks.
    • Enable Multi-Factor Authentication (MFA) for CLI logins where supported, adding an extra layer of security.
    • Regularly rotate API keys and client secrets.

Limitations and Considerations​

  • OAuth 2.0 Complexity: While powerful, correctly implementing and configuring OAuth 2.0 flows (especially Authorization Code with PKCE) requires careful attention to detail to avoid security vulnerabilities.
  • Token Revocation Latency: Revoked tokens might still be considered valid by services until their expiry or until revocation lists are propagated, potentially leading to a brief window of unauthorized access.
  • Performance Overhead: Frequent token validation or refresh operations can introduce minor latency. The system optimizes this by caching valid tokens and performing asynchronous refreshes where possible.
  • Dependency on Identity Provider: The system relies on an external Identity Provider (IdP) for user authentication in OAuth 2.0 flows. Ensure the IdP is reliable and secure.