As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Identity and Access Management

Non-API-specific IAM policy definitions

For allowed roles / permissions, see: https://cloud.google.com/iam/docs/understanding-roles

Example usage:

# ``get_iam_policy`` returns a :class:'~google.api_core.iam.Policy`.
policy = resource.get_iam_policy(requested_policy_version=3)

phred = "user:phred@example.com"
admin_group = "group:admins@groups.example.com"
account = "serviceAccount:account-1234@accounts.example.com"

policy.version = 3
policy.bindings = [
    {
        "role": "roles/owner",
        "members": {phred, admin_group, account}
    },
    {
        "role": "roles/editor",
        "members": {"allAuthenticatedUsers"}
    },
    {
        "role": "roles/viewer",
        "members": {"allUsers"}
        "condition": {
            "title": "request_time",
            "description": "Requests made before 2021-01-01T00:00:00Z",
            "expression": "request.time < timestamp("2021-01-01T00:00:00Z")"
        }
    }
]

resource.set_iam_policy(policy)
google.api_core.iam.OWNER_ROLE = 'roles/owner'

Generic role implying all rights to an object.

google.api_core.iam.EDITOR_ROLE = 'roles/editor'

Generic role implying rights to modify an object.

google.api_core.iam.VIEWER_ROLE = 'roles/viewer'

Generic role implying rights to access an object.

exception google.api_core.iam.InvalidOperationException[source]

Bases: Exception

Raised when trying to use Policy class as a dict.

class google.api_core.iam.Policy(etag=None, version=None)[source]

Bases: collections.abc.MutableMapping

IAM Policy

Parameters

  • etag (Optional[str]) – ETag used to identify a unique of the policy

  • version (Optional[int]) – The syntax schema version of the policy.

Note

Using conditions in bindings requires the policy’s version to be set to 3 or greater, depending on the versions that are currently supported.

Accessing the policy using dict operations will raise InvalidOperationException when the policy’s version is set to 3.

Use the policy.bindings getter/setter to retrieve and modify the policy’s bindings.

See:

IAM Policy https://cloud.google.com/iam/reference/rest/v1/Policy Policy versions https://cloud.google.com/iam/docs/policies#versions Conditions overview https://cloud.google.com/iam/docs/conditions-overview.

__check_version__()[source]

Raise InvalidOperationException if version is greater than 1 or policy contains conditions.

property bindings

The policy’s list of bindings.

A binding is specified by a dictionary with keys:

  • role (str): Role that is assigned to members.

  • members (set of str): Specifies the identities associated to this binding.

  • condition (dict of str:str): Specifies a condition under which this binding will apply.

    • title (str): Title for the condition.

    • description (:obj:str, optional): Description of the condition.

    • expression: A CEL expression.

Type:

list of dict

See:

Policy versions https://cloud.google.com/iam/docs/policies#versions Conditions overview https://cloud.google.com/iam/docs/conditions-overview.

Example:

USER = "user:phred@example.com"
ADMIN_GROUP = "group:admins@groups.example.com"
SERVICE_ACCOUNT = "serviceAccount:account-1234@accounts.example.com"
CONDITION = {
    "title": "request_time",
    "description": "Requests made before 2021-01-01T00:00:00Z", # Optional
    "expression": "request.time < timestamp("2021-01-01T00:00:00Z")"
}

# Set policy's version to 3 before setting bindings containing conditions.
policy.version = 3

policy.bindings = [
    {
        "role": "roles/viewer",
        "members": {USER, ADMIN_GROUP, SERVICE_ACCOUNT},
        "condition": CONDITION
    },
    ...
]
property owners

Legacy access to owner role.

Raise InvalidOperationException if version is greater than 1 or policy contains conditions.

DEPRECATED: use policy.bindings to access bindings instead.

property editors

Legacy access to editor role.

Raise InvalidOperationException if version is greater than 1 or policy contains conditions.

DEPRECATED: use policy.bindings to access bindings instead.

property viewers

Legacy access to viewer role.

Raise InvalidOperationException if version is greater than 1 or policy contains conditions.

DEPRECATED: use policy.bindings to modify bindings instead.

static user(email)[source]

Factory method for a user member.

Parameters

email (str) – E-mail for this particular user.

Returns

A member string corresponding to the given user.

Return type

str

static service_account(email)[source]

Factory method for a service account member.

Parameters

email (str) – E-mail for this particular service account.

Returns

A member string corresponding to the given service account.

Return type

str

static group(email)[source]

Factory method for a group member.

Parameters

email (str) – An id or e-mail for this particular group.

Returns

A member string corresponding to the given group.

Return type

str

static domain(domain)[source]

Factory method for a domain member.

Parameters

domain (str) – The domain for this member.

Returns

A member string corresponding to the given domain.

Return type

str

static all_users()[source]

Factory method for a member representing all users.

Returns

A member string representing all users.

Return type

str

static authenticated_users()[source]

Factory method for a member representing all authenticated users.

Returns

A member string representing all authenticated users.

Return type

str

classmethod from_api_repr(resource)[source]

Factory: create a policy from a JSON resource.

Parameters

resource (dict) – policy resource returned by getIamPolicy API.

Returns

the parsed policy

Return type

Policy

to_api_repr()[source]

Render a JSON policy resource.

Returns

a resource to be passed to the setIamPolicy API.

Return type

dict