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.mindlab section of a project’s pyproject.toml file as follows:

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

Amazon Web Services

The authentication logic is implemented in AWSAuth, which looks for the credentials of the organization_id named profile, where organization_id 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: Optional[str] = None, project: Optional[str] = None)

Google Cloud Platform authentication manager.

project(project: Optional[str] = None) → str

Return the project name.

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

project_id(organization: Optional[str] = None, project: Optional[str] = None) → str

Return the project ID.

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

organization_credentials_path(organization: Optional[str] = None) → Optional[Path]

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: Optional[str] = None, project: Optional[str] = None) → Credentials: Return the organization credentials when they exist or the application default credentials.

organization(organization: Optional[str] = None) → str

Return the organization name.

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

organization_id(organization: Optional[str] = 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]

organization(organization: Optional[str] = None) → str

Return the organization name.

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

organization_id(organization: Optional[str] = None) → str

Return the organization ID.

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

session(organization: Optional[str] = None) → Session: Return a session that uses the organization ID named profile credentials (if it exists).