Authentication Strategies

Relevant source files

The following files were used as context for generating this wiki page:

• singer_sdk/authenticators.py
• cookiecutter/tap-template/{{cookiecutter.tap_id}}/{{cookiecutter.library_name}}/auth.py
• cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md
• cookiecutter/tap-template/cookiecutter.json
• CLAUDE.md
• pyproject.toml

Authentication Strategies in the Meltano Singer SDK provide a standardized framework for verifying identity and authorizing access to external data sources. These strategies are primarily used by "Taps" (extractors) to interact with REST and GraphQL APIs securely. The SDK offers several pre-built authenticator classes that handle common protocols such as API Keys, Basic Auth, OAuth2, and JWT, reducing the amount of boilerplate code developers must write.

The core logic resides in singer_sdk/authenticators.py, which defines the base Authenticator class and specialized implementations. By utilizing these strategies, developers ensure that sensitive credentials like tokens and keys are handled according to Singer best practices, including support for secret masking in configurations and automatic token refresh where applicable.

Sources: singer_sdk/authenticators.py, cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md:68-87, CLAUDE.md:87-92

Core Authenticator Framework

The SDK employs an object-oriented approach to authentication. The Authenticator base class establishes the contract for all authentication methods. For REST-based streams, the authenticator is typically integrated into the Client or Stream class to modify request headers or query parameters before they are sent to the source API.

Authentication Methods Overview

The project supports several standard authentication methods, selectable during project scaffolding:

Method	Implementation Detail	Configuration Source
API Key	Passed via headers or query parameters.	config (e.g., api_key)
Bearer Token	Included in Authorization header as Bearer {token}.	auth_token config property
Basic Auth	Username/Password encoded to Base64.	Config credentials
OAuth2	Implements token exchange and automatic refresh.	client_id, client_secret
JWT	Generates tokens using defined claims and signing keys.	Config & auth.py logic

Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md:68-87, cookiecutter/tap-template/cookiecutter.json:11-18

Class Hierarchy

The following diagram illustrates the relationship between the different authenticator classes provided by the SDK:

The hierarchy ensures that specific authentication types can inherit common logic while providing custom methods for applying credentials to requests.

Sources: singer_sdk/authenticators.py, cookiecutter/tap-template/{{cookiecutter.tap_id}}/{{cookiecutter.library_name}}/auth.py:19-45

OAuth2 Implementation

The OAuthAuthenticator class provides a robust implementation for the OAuth2 protocol, specifically focusing on the client_credentials grant type. It manages the lifecycle of the access token, including requesting the token from a resource server and attaching it to outgoing requests.

Singleton Pattern

In the tap templates, authenticators often use SingletonMeta. This ensures that multiple streams within the same tap instance share a single authenticator, preventing redundant authentication requests and token exhaustion.

class MySourceAuthenticator(OAuthAuthenticator, metaclass=SingletonMeta):
    """Authenticator class for MySource."""

    @property
    def oauth_request_body(self) -> dict:
        return {
            "resource": "https://example.com",
            "scope": self.oauth_scopes,
            "client_id": self.client_id,
            "client_secret": self.client_secret,
            "grant_type": "client_credentials",
        }

Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/{{cookiecutter.library_name}}/auth.py:19-35

OAuth2 Sequence Flow

This sequence diagram shows how the SDK handles authentication during a data extraction request:

JWT (JSON Web Token) Strategies

For sources requiring JWT, the SDK provides OAuthJWTAuthenticator. This strategy involves generating a signed token locally before presenting it to the API.

Features of JWT Authentication:

• Token Generation: Uses libraries like PyJWT and cryptography (specified in pyproject.toml extras).
• Header Injection: The generated token is automatically included in the Authorization header.
• Configurable Claims: Developers can define custom claims and expiration durations within the auth.py file.

Sources: pyproject.toml:96-99, cookiecutter/tap-template/{{cookiecutter.tap_id}}/{{cookiecutter.library_name}}/auth.py:38-44

Security and Configuration

Authentication strategies are tightly coupled with the SDK's configuration system. Credentials must be defined in the Tap class's config_jsonschema.

Configuration Best Practices:

1. Secret Masking: Properties containing sensitive data (keys, passwords, secrets) must be marked with secret=True in the schema. This ensures they are masked in logs and handled securely by Meltano.
2. Meltano Sync: Settings in the Python code must match the settings block in meltano.yml to prevent configuration drift.
3. Environment Variables: The SDK supports loading credentials from environment variables (e.g., TAP_MYSOURCE_API_KEY) when --config=ENV is used.

Setting	Type	Secret	Description
api_key	StringType	Yes	Token for API Key auth.
client_secret	StringType	Yes	OAuth2 client secret.
auth_token	StringType	Yes	Permanent Bearer token.

Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/AGENTS.md:144-180, cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:52-56

Conclusion

Authentication Strategies in the Meltano Singer SDK provide a structured, extensible way to handle identity across various API types. By using the provided authenticator classes, developers gain built-in support for token lifecycles, singleton instance management, and secure configuration handling, ensuring that Singer taps remain both functional and secure.