`multicloud.sts`¶

Security Token Service — cloud-agnostic identity and short-lived credentials. See the STS guide for task-focused walkthroughs.

Cloud-agnostic STS client package.

Public entry point — :class:StsClient::

from multicloud.sts.sts_client import StsClient

with StsClient(provider="aws", region="us-west-2") as sts:
    identity = sts.get_caller_identity()
    creds = sts.assume_role(
        "arn:aws:iam::123:role/MyRole",
        session_name="dev",
    )

Provider classes (AwsSts, GcpSts, ...) live in sibling distributions (multicloud-sts-aws, -gcp, -ali) and are discovered at runtime via setuptools entry points. They are hidden behind the registry; users never reference them directly.

StsClient ¶

StsClient(
    *,
    provider: str,
    region: Optional[str] = None,
    endpoint: Optional[str] = None,
    credentials_overrider: Optional[
        CredentialsOverrider
    ] = None,
    properties: Optional[Mapping[str, Any]] = None
)

Cloud-agnostic Security Token Service client.

Parameters:

Name	Type	Description	Default
`provider`	`str`	Registered provider id used to select the implementation.	required
`region`	`Optional[str]`	Region (interpreted per provider). Optional; falls back to provider defaults.	`None`
`endpoint`	`Optional[str]`	Endpoint override URL. Optional.	`None`
`credentials_overrider`	`Optional[CredentialsOverrider]`	Override default credential resolution. Optional.	`None`
`properties`	`Optional[Mapping[str, Any]]`	Provider-specific extras passed through to the driver constructor as keyword arguments.	`None`

get_caller_identity ¶

get_caller_identity(
    *, aud: Optional[str] = None
) -> CallerIdentity

Return identity info for the current credentials.

Parameters:

Name	Type	Description	Default
`aud`	`Optional[str]`	Target audience for the identity token. Some providers use this for audience-scoped token generation; others ignore it.	`None`

assume_role ¶

assume_role(
    role: str,
    *,
    session_name: str = "",
    expiration: int = 3600,
    external_id: Optional[str] = None,
    policy: Optional[str] = None,
    tags: Optional[Mapping[str, str]] = None,
    credential_scope: Optional[CredentialScope] = None
) -> StsCredentials

Assume a role and return temporary credentials.

Parameters:

Name	Type	Description	Default
`role`	`str`	Cloud resource name to assume.	required
`session_name`	`str`	Session identifier.	`''`
`expiration`	`int`	Duration in seconds (default 3600).	`3600`
`external_id`	`Optional[str]`	External ID for cross-account access (optional).	`None`
`policy`	`Optional[str]`	Inline policy to scope down permissions (optional).	`None`
`tags`	`Optional[Mapping[str, str]]`	Session tags (optional).	`None`
`credential_scope`	`Optional[CredentialScope]`	Optional scope to downscope credentials.	`None`

get_access_token ¶

get_access_token(
    *,
    audience: Optional[str] = None,
    scopes: Optional[list[str]] = None,
    duration_seconds: Optional[int] = None
) -> StsCredentials

Retrieve a fresh access token from the provider.

Parameters:

Name	Type	Description	Default
`audience`	`Optional[str]`	Target audience for an audience-scoped token. Interpreted per provider; see the provider implementation for details. Mutually exclusive with `scopes`.	`None`
`scopes`	`Optional[list[str]]`	OAuth scopes for a scoped token. Interpreted per provider; see the provider implementation for details. Mutually exclusive with `audience`.	`None`
`duration_seconds`	`Optional[int]`	Requested token duration. Interpreted per provider; some providers may ignore or cap this value (optional).	`None`

generate_service_account_token ¶

generate_service_account_token(
    target_principal: str,
    *,
    scopes: list[str],
    lifetime: int = 3600
) -> StsCredentials

Generate a token for a target service account via impersonation.

Parameters:

Name	Type	Description	Default
`target_principal`	`str`	Service account to impersonate. Format is interpreted per provider; see the provider implementation for details.	required
`scopes`	`list[str]`	OAuth scopes to request on the generated token.	required
`lifetime`	`int`	Token lifetime in seconds (default 3600). Supported range and behaviour are provider-specific; see the provider implementation for details.	`3600`

assume_role_with_web_identity ¶

assume_role_with_web_identity(
    role: str,
    web_identity_token: str,
    *,
    session_name: str = "",
    expiration: int = 3600
) -> StsCredentials

Exchange a web identity (OIDC) token for temporary credentials.

Parameters:

Name	Type	Description	Default
`role`	`str`	Cloud resource identifier to assume (interpretation is provider-specific).	required
`web_identity_token`	`str`	The OIDC/JWT token proving external identity.	required
`session_name`	`str`	Session identifier (optional; provider support varies).	`''`
`expiration`	`int`	Requested duration in seconds (default 3600). Provider support varies; some providers may ignore this parameter.	`3600`

close ¶

close() -> None

Release underlying resources.

StsUtilities ¶

StsUtilities(
    *,
    provider: str,
    region: Optional[str] = None,
    credentials_overrider: Optional[
        CredentialsOverrider
    ] = None,
    properties: Optional[Mapping[str, Any]] = None
)

Cloud-agnostic STS utility functions (offline request signing).

Companion to :class:StsClient for utilities that sign a request locally instead of calling the provider. The signed request is handed to another system that replays it to verify the caller's identity.

Parameters:

Name	Type	Description	Default
`provider`	`str`	Registered provider id used to select the implementation.	required
`region`	`Optional[str]`	Region (interpreted per provider). Optional for some providers; required by others for request signing.	`None`
`credentials_overrider`	`Optional[CredentialsOverrider]`	Override default credential resolution. Optional.	`None`
`properties`	`Optional[Mapping[str, Any]]`	Provider-specific extras passed through to the driver constructor as keyword arguments.	`None`

create_signed_auth_request ¶

create_signed_auth_request(
    *, custom_headers: Optional[Mapping[str, str]] = None
) -> SignedAuthRequest

Produce a signed identity request for cloud-native auth.

Parameters:

Name	Type	Description	Default
`custom_headers`	`Optional[Mapping[str, str]]`	Extra headers to fold into the signature so the system replaying the request can bind them to the identity.	`None`

AvailabilityCondition `dataclass` ¶

AvailabilityCondition(
    resource_prefix: Optional[str] = None,
    title: Optional[str] = None,
    description: Optional[str] = None,
)

Condition that must be met for a ScopeRule to apply.

Currently supports prefix-based resource restriction.

BaseSts ¶

BaseSts(
    region: Optional[str] = None,
    *,
    endpoint_url: Optional[str] = None,
    credentials_overrider: Optional[
        CredentialsOverrider
    ] = None,
    validator: Optional[StsValidator] = None
)

Bases: Provider, ABC

Base class for substrate-specific STS implementations.

Providers extend this class and implement :meth:do_get_caller_identity, :meth:do_assume_role, :meth:do_get_access_token, and :meth:do_generate_service_account_token. All cross-cutting concerns (validation, default arg handling) happen in the public methods so providers don't have to repeat them.

get_caller_identity ¶

get_caller_identity(
    *, aud: Optional[str] = None
) -> CallerIdentity

Return identity info for the current credentials.

Parameters:

Name	Type	Description	Default
`aud`	`Optional[str]`	Target audience for the identity token. Some providers use this for audience-scoped token generation; others ignore it.	`None`

assume_role ¶

assume_role(
    role: str,
    *,
    session_name: str = "",
    expiration: int = 3600,
    external_id: Optional[str] = None,
    policy: Optional[str] = None,
    tags: Optional[Mapping[str, str]] = None,
    credential_scope: Optional[CredentialScope] = None
) -> StsCredentials

Assume a role and return temporary credentials.

Parameters:

Name	Type	Description	Default
`role`	`str`	Cloud resource name to assume.	required
`session_name`	`str`	Session identifier.	`''`
`expiration`	`int`	Duration in seconds (default 3600).	`3600`
`external_id`	`Optional[str]`	External ID for cross-account access (optional).	`None`
`policy`	`Optional[str]`	Inline policy to scope down permissions (optional).	`None`
`tags`	`Optional[Mapping[str, str]]`	Session tags (optional).	`None`
`credential_scope`	`Optional[CredentialScope]`	Optional scope to downscope credentials.	`None`

Returns:

Type	Description
`StsCredentials`	StsCredentials with temporary access tokens.

get_access_token ¶

get_access_token(
    *,
    audience: Optional[str] = None,
    scopes: Optional[list[str]] = None,
    duration_seconds: Optional[int] = None
) -> StsCredentials

Retrieve a fresh access token from the provider.

Parameters:

Name	Type	Description	Default
`audience`	`Optional[str]`	Target audience for an audience-scoped token. Interpreted per provider; see the provider implementation for details. Mutually exclusive with `scopes`.	`None`
`scopes`	`Optional[list[str]]`	OAuth scopes for a scoped token. Interpreted per provider; see the provider implementation for details. Mutually exclusive with `audience`.	`None`
`duration_seconds`	`Optional[int]`	Requested token duration. Interpreted per provider; some providers may ignore or cap this value (optional).	`None`

Returns:

Type	Description
`StsCredentials`	StsCredentials with the token in `security_token`.

generate_service_account_token ¶

generate_service_account_token(
    target_principal: str,
    *,
    scopes: list[str],
    lifetime: int = 3600
) -> StsCredentials

Generate a token for a target service account via impersonation.

Behaviour, required permissions, and supported lifetime range are provider-specific; see the provider do_generate_service_account_token implementation for details.

Parameters:

Name	Type	Description	Default
`target_principal`	`str`	Service account to impersonate. Format is interpreted per provider; see the provider implementation for details.	required
`scopes`	`list[str]`	OAuth scopes to request on the generated token.	required
`lifetime`	`int`	Token lifetime in seconds (default 3600). Supported range and behaviour are provider-specific; see the provider implementation for details.	`3600`

Returns:

Type	Description
`StsCredentials`	StsCredentials with the impersonated token in `security_token`.

assume_role_with_web_identity ¶

assume_role_with_web_identity(
    role: str,
    web_identity_token: str,
    *,
    session_name: str = "",
    expiration: int = 3600
) -> StsCredentials

Exchange a web identity (OIDC) token for temporary credentials.

Federated sign-in: the caller presents an OIDC/JWT token minted by an external identity provider and receives short-lived cloud credentials in return — no long-lived cloud keys required.

Parameters:

Name	Type	Description	Default
`role`	`str`	Cloud resource name to assume, interpreted by each provider as its federated-identity resource identifier.	required
`web_identity_token`	`str`	The OIDC/JWT token proving the caller's external identity.	required
`session_name`	`str`	Session identifier (optional; provider may ignore).	`''`
`expiration`	`int`	Requested duration in seconds (default 3600). Interpreted per provider; some providers may honor, cap, or ignore it.	`3600`

Returns:

Type	Description
`StsCredentials`	StsCredentials with temporary access tokens.

do_get_caller_identity `abstractmethod` ¶

do_get_caller_identity(
    *, aud: Optional[str] = None
) -> CallerIdentity

Provider-specific implementation of get_caller_identity.

do_assume_role `abstractmethod` ¶

do_assume_role(
    role: str,
    *,
    session_name: str,
    expiration: int,
    external_id: Optional[str],
    policy: Optional[str],
    tags: Mapping[str, str],
    credential_scope: Optional[CredentialScope]
) -> StsCredentials

Provider-specific implementation of assume_role.

do_get_access_token `abstractmethod` ¶

do_get_access_token(
    *,
    audience: Optional[str] = None,
    scopes: Optional[list[str]] = None,
    duration_seconds: Optional[int] = None
) -> StsCredentials

Provider-specific implementation of get_access_token.

do_generate_service_account_token `abstractmethod` ¶

do_generate_service_account_token(
    target_principal: str,
    *,
    scopes: list[str],
    lifetime: int
) -> StsCredentials

Provider-specific implementation of generate_service_account_token.

do_assume_role_with_web_identity `abstractmethod` ¶

do_assume_role_with_web_identity(
    role: str,
    web_identity_token: str,
    *,
    session_name: str,
    expiration: int
) -> StsCredentials

Provider-specific implementation of assume_role_with_web_identity.

close ¶

close() -> None

Release underlying resources. Default is a no-op.

CallerIdentity `dataclass` ¶

CallerIdentity(
    user_id: str = "",
    cloud_resource_name: str = "",
    account_id: str = "",
)

Cloud-agnostic caller identity.

user_id: unique identifier of the calling entity
cloud_resource_name: cloud resource identifier or identity proof
account_id: cloud account/project that owns the identity

CredentialScope `dataclass` ¶

CredentialScope(rules: tuple[ScopeRule, ...] = ())

Used with assume_role to downscope credentials.

Empty rules means no restrictions applied.

CredentialsOverrider `dataclass` ¶

CredentialsOverrider(
    credentials_type: CredentialsType,
    session_credentials: Optional[StsCredentials] = None,
    role: Optional[str] = None,
    duration_seconds: Optional[int] = None,
    session_name: Optional[str] = None,
    web_identity_token_supplier: Optional[
        Callable[[], str]
    ] = None,
)

Override the default credentials resolution.

Modeled as a grouped configuration object because its fields are interdependent and validated as a unit — the required subset of fields changes based on credentials_type.

Used when a service needs to: 1. Supply explicit session credentials (SESSION) 2. Assume a role from another account (ASSUME_ROLE) 3. Exchange a web identity token for credentials (ASSUME_ROLE_WEB_IDENTITY)

If credentials_type is SESSION, session_credentials must be provided. If credentials_type is ASSUME_ROLE, role is required. If credentials_type is ASSUME_ROLE_WEB_IDENTITY, role and web_identity_token_supplier are required.

role is provider-interpreted: each provider maps this string to its native role identifier format (e.g. an ARN, a service-account email, or a RAM role name).

CredentialsType ¶

Bases: Enum

Type of credential override to apply.

ScopeRule `dataclass` ¶

ScopeRule(
    available_resource: str,
    available_permissions: tuple[str, ...],
    availability_condition: Optional[
        AvailabilityCondition
    ] = None,
)

A single resource + permissions entry within a CredentialScope.

Attributes:

Name	Type	Description
`available_resource`	`str`	URI of the resource.
`available_permissions`	`tuple[str, ...]`	Tuple of permission strings granted on the resource.
`availability_condition`	`Optional[AvailabilityCondition]`	Optional condition to further narrow access.

StsCredentials `dataclass` ¶

StsCredentials(
    access_key_id: str = "",
    access_key_secret: str = "",
    security_token: str = "",
    expiration: Optional[datetime] = None,
)

Cloud-agnostic representation of temporary credentials.

All providers normalize their native credential type into this shape.

access_key_id: identity key or empty when not applicable
access_key_secret: secret key or empty when not applicable
security_token: session/bearer token (all providers)
expiration: token expiry time (all providers)

StsValidator ¶

Input validator; raises :class:InvalidArgumentException.

BaseStsUtilities ¶

BaseStsUtilities(
    region: Optional[str] = None,
    *,
    credentials_overrider: Optional[
        CredentialsOverrider
    ] = None
)

Bases: Provider, ABC

Base class for substrate-specific STS utility implementations.

Providers extend this class and implement :meth:do_create_signed_auth_request. Cross-cutting concerns (argument normalization) happen in the public method so providers don't have to repeat them.

create_signed_auth_request ¶

create_signed_auth_request(
    *, custom_headers: Optional[Mapping[str, str]] = None
) -> SignedAuthRequest

Produce a signed identity request for cloud-native auth.

Parameters:

Name	Type	Description	Default
`custom_headers`	`Optional[Mapping[str, str]]`	Extra headers to fold into the signature so the broker replaying the request can bind them to the identity.	`None`

Returns:

Type	Description
`SignedAuthRequest`	SignedAuthRequest with the signed method, url, headers, body,
`SignedAuthRequest`	and the credentials used to sign it.

do_create_signed_auth_request `abstractmethod` ¶

do_create_signed_auth_request(
    *, custom_headers: Mapping[str, str]
) -> SignedAuthRequest

Provider-specific implementation of create_signed_auth_request.

close ¶

close() -> None

Release underlying resources. Default is a no-op.

SignedAuthRequest `dataclass` ¶

SignedAuthRequest(
    method: str,
    url: str,
    headers: Mapping[str, str],
    body: bytes,
    credentials: StsCredentials,
)

A signed-but-unsent identity request.

Produced by :meth:BaseStsUtilities.create_signed_auth_request. The caller forwards the request itself — method, url, headers, and body — to an identity broker, which replays it to the provider to prove the caller's identity.

Security: this is a replayable identity proof — the signed headers (and any session token on credentials) let anyone holding them impersonate the signer until the signature expires. Treat it as a secret: __repr__ redacts the sensitive parts, but dataclasses.asdict and direct field access do not.

method: HTTP method of the signed request
url: fully-qualified request URL
headers: signed request headers; redacted in repr
body: request body bytes
credentials: non-secret signer identity (key id + session token); the long-term signing secret is omitted

multicloud.sts¶

StsClient ¶

get_caller_identity ¶

assume_role ¶

get_access_token ¶

generate_service_account_token ¶

assume_role_with_web_identity ¶

close ¶

StsUtilities ¶

create_signed_auth_request ¶

AvailabilityCondition dataclass ¶

BaseSts ¶

get_caller_identity ¶

assume_role ¶

get_access_token ¶

generate_service_account_token ¶

assume_role_with_web_identity ¶

do_get_caller_identity abstractmethod ¶

do_assume_role abstractmethod ¶

do_get_access_token abstractmethod ¶

do_generate_service_account_token abstractmethod ¶

do_assume_role_with_web_identity abstractmethod ¶

close ¶

CallerIdentity dataclass ¶

CredentialScope dataclass ¶

CredentialsOverrider dataclass ¶

CredentialsType ¶

ScopeRule dataclass ¶

StsCredentials dataclass ¶

StsValidator ¶

BaseStsUtilities ¶

create_signed_auth_request ¶

do_create_signed_auth_request abstractmethod ¶

close ¶

SignedAuthRequest dataclass ¶

`multicloud.sts`¶

AvailabilityCondition `dataclass` ¶

do_get_caller_identity `abstractmethod` ¶

do_assume_role `abstractmethod` ¶

do_get_access_token `abstractmethod` ¶

do_generate_service_account_token `abstractmethod` ¶

do_assume_role_with_web_identity `abstractmethod` ¶

CallerIdentity `dataclass` ¶

CredentialScope `dataclass` ¶

CredentialsOverrider `dataclass` ¶

ScopeRule `dataclass` ¶

StsCredentials `dataclass` ¶

do_create_signed_auth_request `abstractmethod` ¶

SignedAuthRequest `dataclass` ¶