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.

Microsoft

The authentication logic is implemented in MicrosoftAuth. The exact details can be found in the class documentation.

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.

abstractmethod get(key: str, default: str | None = None) → str | None

Retrieve the secret under the given key if it exists and has an active version.

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, service_account_email: str | None = None, oauth_flow: bool | None = None, oauth_scopes: Iterable[str] | None = None, oauth_user_email: str | None = None, oauth_force_reauth: bool = False, oauth_credentials_key: str | None = None, oauth_client_secrets_key: str | None = None)

Google Cloud Platform authentication manager.

Parameters:

  • organization – The organization name to use.

  • project – The project name to use.

  • service_account_email – The service account to impersonate. Defaults to the service_account_email value in pyproject.toml under the tool.stormware.google section.

  • oauth_flow – Whether to use only the OAuth 2.0 flow (True), disallow the OAuth 2.0 flow (False), or use the OAuth 2.0 flow only when the OAuth user email is specified (None).

  • oauth_user_email – The email address of the user that should complete the OAuth 2.0 flow.

  • oauth_scopes – The OAuth 2.0 scopes to request. Defaults to using the registered scopes, or, if no scopes are registered, then the oauth_scopes value set in pyproject.toml under the tool.stormware.google section, or, if no such value is set, then to all connector scopes.

  • oauth_force_reauth – Whether to force the user to re-authenticate in the OAuth 2.0 flow.

  • 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/{project}/google/{oauth_credentials_key}.json, where project is the project.name value in the pyproject.toml file.

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

static register(*connectors: type[Connector]) → None

Register connector authentication scopes.

clear_cache() → None

Clear the credentials cache.

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.

credentials(*, organization: str | None = None, project: str | None = None, scopes: Iterable[str] | None = None) → Credentials

Return the organization credentials, application default credentials or user credentials.

For the OAuth 2.0 flow 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 requested credential scopes.

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.

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

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

class stormware.microsoft.auth.MicrosoftAuth(*, organization: str | None = None, project: str | None = None, secret_store: SecretStore | None = None, developer_token_key: str | None = None, oauth_force_reauth: bool = False, oauth_credentials_key: str | None = None, oauth_client_secrets_key: str | None = None, environment: str = 'production')

Microsoft authentication manager.

Parameters:

  • organization – The organization name to use.

  • project – The project name to use.

  • secret_store – The secret store to use for retrieving the credentials. Uses the default secret store when not provided.

  • developer_token_key – The Secret Manager key to use for the developer token. Defaults to the developer_token_key value set in pyproject.toml under the tool.stormware.microsoft section, or stormware-microsoft-developer-token if not set.

  • oauth_force_reauth – Whether to force the user to re-authenticate in the OAuth 2.0 flow.

  • 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.microsoft section, or stormware-microsoft-oauth-credentials if not set. If the secret does not exist, the credentials will be cached using local storage under $XDG_CONFIG_HOME/stormware/{project}/microsoft/{oauth_credentials_key}.json, where project is the project.name value in the pyproject.toml file.

  • 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.microsoft section, or stormware-microsoft-oauth-client-secrets if not set.

  • environment – The environment to use.

Authentication

The OAuth client secrets are loaded from the secret store using the provided key. The secret must be a string-encoded JSON object with the client_id, client_secret and tenant keys. The client ID, client secret and tenant can be obtained by creating a Microsoft Azure web app (under https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade with a redirect URI of “http://localhost:42942”). The client ID is the value found in the “Overview” section under “Application (client) ID”, and the tenant is the value found under “Directory (tenant) ID”. The client secret can be generated in the “Certificates & secrets” section.

The developer token is loaded from the secret store using the provided key. It can be obtained under “Settings > Developer settings” in Microsoft Advertising (at https://ads.microsoft.com).

authorization_data() → AuthorizationData

Return the authorization data for the Microsoft Advertising SDK.

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.

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