Authentication

External APIs typically require the caller to present a set of authentication credentials. In the case of cloud infrastructure providers (Google Cloud Platform and Amazon Web Services in particular) Stormware uses locally available credentials that are generated and also used by cloud CLI tools.

Note

You must install the google extra when using the Google Cloud Platform authentication mechanism.

Note

You must install the amazon extra when using the Amazon Web Services authentication mechanism.

Google Cloud Platform

The default authentication mechanism (implemented in GCPAuth) first looks for a set of credentials in the $XDG_CONFIG_HOME/gcloud/credentials/{organization_id}.json file, where organization_id is derived from the provided organization value by replacing dots with dashes. If the organization credentials file does not exist, we use the application default credentials.

Note

We recommend using the gcpl script for generating organization credentials. Note that you need to add the -s stormware option if you are using Google connectors that are not related to the Google Cloud Platform (for example, the Google Sheets connector).

A default organization and project can be set under the tool.stormware section of a project’s pyproject.toml file as follows:

[tool.stormware]
organization = 'example.com'
project = 'my-project'

If the project is not provided, the project.name value is used from the pyproject.toml file instead.

Amazon Web Services

The authentication logic is implemented in AWSAuth – we look for the credentials of the organization_id named profile, which is derived the same way as it is for the Google Cloud Platform authentication. If the credentials cannot be found for the named profile then the boto3 credential location mechanism is used.

Note

We recommend using the awsl script for generating named profile credentials.

Secret Store

The credentials for most connectors are retrieved from a secret store, which has the following abstract interface:

class stormware.secrets.SecretStore

abstract __getitem__(key: str) → str: Retrieve the secret under the given key.

Stormware comes with two built-in secret store implementations for Google Cloud Platform and Amazon Web Services, and further secret stores can be easily added by simply inheriting and implementing the SecretStore interface.

Note

When no secret store is explicitly provided the connectors default to using the Google Cloud Secret Manager store when the google extra is installed and the AWS Secrets Manager store when the amazon extra is installed. If both extras are installed, the Google Cloud Secret Manager store takes precedence.

For further information regarding connector authentication please consult the documentation of the specific connector that you intend to use.

Authentication Managers

class stormware.google.auth.GCPAuth(organization: str | None = None, project: str | None = None)

Google Cloud Platform authentication manager.

project(project: str | None = None) → str

Return the project name.

Defaults to the project value set in pyproject.toml under the tool.stormware section or the name value set under the project section.

project_id(organization: str | None = None, project: str | None = None) → str

Return the project ID.

The project ID is constructed as {project}-{organization_id}.

organization_credentials_path(organization: str | None = None) → Path | None

Return the path to the organization credentials or None if it does not exist.

Constructed as $XDG_CONFIG_HOME/gcloud/credentials/{organization_id}.json.

credentials(organization: str | None = None, project: str | None = None) → Credentials: Return the organization credentials when they exist or the application default credentials.

organization(organization: str | None = None) → str

Return the organization name.

Defaults to the organization value set in pyproject.toml under the tool.stormware section.

organization_id(organization: str | None = None) → str

Return the organization ID.

The organization ID is derived from the organization name by replacing dots with dashes.

class stormware.amazon.auth.AWSAuth(*args: Any, credentials: Path = PosixPath('~/.aws/credentials'), **kwargs: Any)

Amazon Web Services authentication manager.

profiles

The available named profiles.

Type:: set[str]

profile(organization: str | None = None) → str | None: Return the profile name (same as the organization ID) or None if it does not exist.

organization(organization: str | None = None) → str

Return the organization name.

Defaults to the organization value set in pyproject.toml under the tool.stormware section.

organization_id(organization: str | None = None) → str

Return the organization ID.

The organization ID is derived from the organization name by replacing dots with dashes.

session(organization: str | None = None, region: str | None = None) → Session: Return a session that uses named profile credentials (if it exists).