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/{configuration}.json file, where configuration defaults to the organization_id, which is derived from the provided organization value by replacing dots with dashes. If the credentials file does not exist, we use the application default credentials.

Note

We recommend using the gcpl script for creating a credentials file.

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

abstractmethod __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, oauth_user_email: str | None = None, ignore_cached_oauth_credentials: bool = False)

Google Cloud Platform authentication manager.

Parameters:

organization – The organization name to use.
project – The project name to use.
oauth_user_email – Make sure that the obtained credentials belong to the given user when using the OAuth 2.0 flow.
ignore_cached_oauth_credentials – Whether to ignore existing cached OAuth 2.0 credentials (effectively forcing the user to re-authenticate, unless appropriately scoped organization or application default credentials exist).

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}.

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

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

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

Return the organization credentials or the application default credentials.

If the obtained credentials does not have the necessary scopes, an OAuth 2.0 flow is triggered. The client ID and client secret are loaded from Secret Manager as a string-encoded JSON object with the client_id and client_secret keys. The client ID and client secret can be obtained by creating a new OAuth 2.0 desktop client in Google Cloud console (under https://console.cloud.google.com/apis/credentials).

Parameters:

organization – The organization name to use.
project – The project name to use.
scopes – The scopes to request.
oauth_credentials_key – The Secret Manager key to use for caching the obtained OAuth 2.0 credentials. Defaults to the oauth_credentials_key value set in pyproject.toml under the tool.stormware.google section, or stormware-google-oauth-credentials if not set. If the secret does not exist, the credentials will be cached using local storage under $XDG_CONFIG_HOME/stormware/google/{oauth_credentials_key}.json.
oauth_client_secrets_key – The Secret Manager key for the OAuth 2.0 client ID and client secrets. Defaults to the oauth_client_secrets_key value set in pyproject.toml under the tool.stormware.google section, or stormware-google-oauth-client-secrets if not set.

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).