`multicloud.iam`¶

Cloud-agnostic Identity & Access Management. Create identities, attach inline policies, and manage access.

Cloud-agnostic IAM client package.

Public entry point — :class:IamClient::

from multicloud.iam.iam_client import (
    IamClient,
    TrustConfiguration,
    CreateOptions,
)

with IamClient(provider="aws", region="us-west-2") as client:
    identity_id = client.create_identity(
        "MyRole",
        tenant_id="123456789012",
        trust_config=TrustConfiguration(),
        options=CreateOptions(),
    )

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

IamClient ¶

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

Cloud-agnostic IAM identity management client.

Parameters:

Name	Type	Description	Default
`provider`	`str`	Provider id — `"aws"` or `"gcp"`.	required
`region`	`Optional[str]`	Region (interpreted per provider). Optional.	`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`

create_identity ¶

create_identity(
    identity_name: str,
    *,
    description: Optional[str] = None,
    tenant_id: str,
    region: Optional[str] = None,
    trust_config: Optional[TrustConfiguration] = None,
    options: Optional[CreateOptions] = None
) -> str

Create an identity, or return the existing one if it already exists.

This operation is idempotent: if the identity already exists, providers return the existing identity ID rather than raising an exception.

Parameters:

Name	Type	Description	Default
`identity_name`	`str`	Name of the identity to create.	required
`description`	`Optional[str]`	Human-readable description.	`None`
`tenant_id`	`str`	Account or project identifier that owns the identity.	required
`region`	`Optional[str]`	Region override (optional).	`None`
`trust_config`	`Optional[TrustConfiguration]`	Trust relationship configuration (optional).	`None`
`options`	`Optional[CreateOptions]`	Additional creation options (optional).	`None`

Returns:

Type	Description
`str`	Provider-specific identity identifier (e.g. ARN, email).

get_identity ¶

get_identity(
    identity_name: str,
    *,
    tenant_id: str,
    region: Optional[str] = None
) -> str

Retrieve an identity's provider-specific identifier.

Parameters:

Name	Type	Description	Default
`identity_name`	`str`	Name of the identity to look up.	required
`tenant_id`	`str`	Account or project identifier that owns the identity.	required
`region`	`Optional[str]`	Region override (optional).	`None`

Returns:

Type	Description
`str`	Provider-specific identity identifier (e.g. ARN, email).

delete_identity ¶

delete_identity(
    identity_name: str,
    *,
    tenant_id: str,
    region: Optional[str] = None
) -> None

Delete an identity from the cloud provider.

Parameters:

Name	Type	Description	Default
`identity_name`	`str`	Name of the identity to delete.	required
`tenant_id`	`str`	Account or project identifier that owns the identity.	required
`region`	`Optional[str]`	Region override (optional).	`None`

attach_inline_policy ¶

attach_inline_policy(
    identity_name: str,
    *,
    policy_document: PolicyDocument,
    tenant_id: str,
    region: Optional[str] = None
) -> None

Attach an inline policy to an identity.

get_inline_policy_details ¶

get_inline_policy_details(
    identity_name: str,
    *,
    policy_name: str,
    tenant_id: str,
    region: Optional[str] = None
) -> Optional[str]

Retrieve an inline policy document as JSON string.

get_attached_policies ¶

get_attached_policies(
    identity_name: str,
    *,
    tenant_id: str,
    region: Optional[str] = None
) -> List[str]

List names of policies attached to an identity.

remove_policy ¶

remove_policy(
    identity_name: str,
    *,
    policy_name: str,
    tenant_id: str,
    region: Optional[str] = None
) -> None

Remove a policy from an identity.

close ¶

close() -> None

Release underlying resources.

AttachInlinePolicyRequest `dataclass` ¶

AttachInlinePolicyRequest(
    identity_name: str,
    policy_document: PolicyDocument,
    tenant_id: str = "",
    region: Optional[str] = None,
)

Internal request object for attach_inline_policy.

BaseIam ¶

BaseIam(
    region: Optional[str] = None,
    *,
    credentials_overrider: Optional[
        CredentialsOverrider
    ] = None,
    validator: Optional[IamValidator] = None
)

Bases: Provider, ABC

Base class for substrate-specific IAM implementations.

Providers extend this class and implement do_* abstract methods plus translate_error. Validation and request construction happen in the public methods.

create_identity ¶

create_identity(
    identity_name: str,
    *,
    description: Optional[str] = None,
    tenant_id: str,
    region: Optional[str] = None,
    trust_config: Optional[TrustConfiguration] = None,
    options: Optional[CreateOptions] = None
) -> str

Create an identity, or return the existing one if it already exists.

This operation has idempotent/upsert semantics: if the identity already exists, providers return the existing identity ID rather than raising ResourceExistsException.

get_identity ¶

get_identity(
    identity_name: str,
    *,
    tenant_id: str,
    region: Optional[str] = None
) -> str

Validate, build request, then delegate to :meth:do_get_identity.

delete_identity ¶

delete_identity(
    identity_name: str,
    *,
    tenant_id: str,
    region: Optional[str] = None
) -> None

Validate, build request, then delegate to :meth:do_delete_identity.

attach_inline_policy ¶

attach_inline_policy(
    identity_name: str,
    *,
    policy_document: PolicyDocument,
    tenant_id: str,
    region: Optional[str] = None
) -> None

Attach an inline policy to an identity.

get_inline_policy_details ¶

get_inline_policy_details(
    identity_name: str,
    *,
    policy_name: str,
    tenant_id: str,
    region: Optional[str] = None
) -> Optional[str]

Retrieve an inline policy document as JSON string.

get_attached_policies ¶

get_attached_policies(
    identity_name: str,
    *,
    tenant_id: str,
    region: Optional[str] = None
) -> List[str]

List names of policies attached to an identity.

remove_policy ¶

remove_policy(
    identity_name: str,
    *,
    policy_name: str,
    tenant_id: str,
    region: Optional[str] = None
) -> None

Remove a policy from an identity.

do_create_identity `abstractmethod` ¶

do_create_identity(request: CreateIdentityRequest) -> str

Provider-specific identity creation.

do_get_identity `abstractmethod` ¶

do_get_identity(request: GetIdentityRequest) -> str

Provider-specific identity retrieval.

do_delete_identity `abstractmethod` ¶

do_delete_identity(request: DeleteIdentityRequest) -> None

Provider-specific identity deletion.

do_attach_inline_policy `abstractmethod` ¶

do_attach_inline_policy(
    request: AttachInlinePolicyRequest,
) -> None

Provider-specific policy attachment.

do_get_inline_policy_details `abstractmethod` ¶

do_get_inline_policy_details(
    request: GetInlinePolicyDetailsRequest,
) -> Optional[str]

Provider-specific policy retrieval.

do_get_attached_policies `abstractmethod` ¶

do_get_attached_policies(
    request: GetAttachedPoliciesRequest,
) -> List[str]

Provider-specific policy listing.

do_remove_policy `abstractmethod` ¶

do_remove_policy(request: RemovePolicyRequest) -> None

Provider-specific policy removal.

close ¶

close() -> None

Release underlying resources. Default is a no-op.

CreateIdentityRequest `dataclass` ¶

CreateIdentityRequest(
    identity_name: str,
    description: Optional[str] = None,
    tenant_id: str = "",
    region: Optional[str] = None,
    trust_config: Optional[TrustConfiguration] = None,
    options: Optional[CreateOptions] = None,
)

Internal request object for create_identity — used between driver and provider.

CreateOptions `dataclass` ¶

CreateOptions(
    path: Optional[str] = None,
    max_session_duration: Optional[int] = None,
    permission_boundary: Optional[str] = None,
)

Optional configuration for identity creation.

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.

DeleteIdentityRequest `dataclass` ¶

DeleteIdentityRequest(
    identity_name: str,
    tenant_id: str = "",
    region: Optional[str] = None,
)

Internal request object for delete_identity.

GetAttachedPoliciesRequest `dataclass` ¶

GetAttachedPoliciesRequest(
    identity_name: str,
    tenant_id: str = "",
    region: Optional[str] = None,
)

Internal request object for get_attached_policies.

GetIdentityRequest `dataclass` ¶

GetIdentityRequest(
    identity_name: str,
    tenant_id: str = "",
    region: Optional[str] = None,
)

Internal request object for get_identity.

GetInlinePolicyDetailsRequest `dataclass` ¶

GetInlinePolicyDetailsRequest(
    identity_name: str,
    policy_name: str = "",
    tenant_id: str = "",
    region: Optional[str] = None,
)

Internal request object for get_inline_policy_details.

IamValidator ¶

Input validator; raises :class:InvalidArgumentException.

RemovePolicyRequest `dataclass` ¶

RemovePolicyRequest(
    identity_name: str,
    policy_name: str = "",
    tenant_id: str = "",
    region: Optional[str] = None,
)

Internal request object for remove_policy.

TrustConfiguration `dataclass` ¶

TrustConfiguration(
    trusted_principals: List[str] = list(),
    conditions: Dict[str, Dict[str, Any]] = dict(),
)

Trust relationship configuration for identity creation.

Principal identifiers are accepted in their provider-native format.

Action `dataclass` ¶

Action(service: str, operation: str)

Substrate-neutral action in 'service:operation' format.

of `staticmethod` ¶

of(action: str) -> 'Action'

Parse 'service:operation' format string.

wildcard `staticmethod` ¶

wildcard(service: str) -> 'Action'

Create wildcard action 'service:*'.

ComputeActions ¶

Predefined compute service actions.

ConditionOperator ¶

Bases: str, Enum

Condition operators for policy conditions.

Effect ¶

Bases: str, Enum

Policy effect — whether a statement grants or denies access.

IamActions ¶

Predefined IAM service actions.

PolicyDocument `dataclass` ¶

PolicyDocument(
    name: Optional[str] = None,
    version: Optional[str] = None,
    statements: Tuple[Statement, ...] = (),
)

Cloud-agnostic policy document — a named collection of statements.

Statement `dataclass` ¶

Statement(
    sid: Optional[str] = None,
    effect: Optional[Effect] = None,
    principals: Tuple[str, ...] = (),
    actions: Tuple[Action, ...] = (),
    resources: Tuple[str, ...] = (),
    conditions: Mapping[str, Mapping[str, Any]] = dict(),
)

Single policy statement — an effect applied to actions on resources.

StorageActions ¶

Predefined storage service actions.

multicloud.iam¶

IamClient ¶

create_identity ¶

get_identity ¶

delete_identity ¶

attach_inline_policy ¶

get_inline_policy_details ¶

get_attached_policies ¶

remove_policy ¶

close ¶

AttachInlinePolicyRequest dataclass ¶

BaseIam ¶

create_identity ¶

get_identity ¶

delete_identity ¶

attach_inline_policy ¶

get_inline_policy_details ¶

get_attached_policies ¶

remove_policy ¶

do_create_identity abstractmethod ¶

do_get_identity abstractmethod ¶

do_delete_identity abstractmethod ¶

do_attach_inline_policy abstractmethod ¶

do_get_inline_policy_details abstractmethod ¶

do_get_attached_policies abstractmethod ¶

do_remove_policy abstractmethod ¶

close ¶

CreateIdentityRequest dataclass ¶

CreateOptions dataclass ¶

CredentialsOverrider dataclass ¶

CredentialsType ¶

DeleteIdentityRequest dataclass ¶

GetAttachedPoliciesRequest dataclass ¶

GetIdentityRequest dataclass ¶

GetInlinePolicyDetailsRequest dataclass ¶

IamValidator ¶

RemovePolicyRequest dataclass ¶

TrustConfiguration dataclass ¶

Action dataclass ¶

of staticmethod ¶

wildcard staticmethod ¶

ComputeActions ¶

ConditionOperator ¶

Effect ¶

IamActions ¶

PolicyDocument dataclass ¶

Statement dataclass ¶

StorageActions ¶

`multicloud.iam`¶

AttachInlinePolicyRequest `dataclass` ¶

do_create_identity `abstractmethod` ¶

do_get_identity `abstractmethod` ¶

do_delete_identity `abstractmethod` ¶

do_attach_inline_policy `abstractmethod` ¶

do_get_inline_policy_details `abstractmethod` ¶

do_get_attached_policies `abstractmethod` ¶

do_remove_policy `abstractmethod` ¶

CreateIdentityRequest `dataclass` ¶

CreateOptions `dataclass` ¶

CredentialsOverrider `dataclass` ¶

DeleteIdentityRequest `dataclass` ¶

GetAttachedPoliciesRequest `dataclass` ¶

GetIdentityRequest `dataclass` ¶

GetInlinePolicyDetailsRequest `dataclass` ¶

RemovePolicyRequest `dataclass` ¶

TrustConfiguration `dataclass` ¶

Action `dataclass` ¶

of `staticmethod` ¶

wildcard `staticmethod` ¶

PolicyDocument `dataclass` ¶

Statement `dataclass` ¶