diff --git a/google/iam/v1/iam_meta_api.yaml b/google/iam/v1/iam_meta_api.yaml new file mode 100644 index 00000000..93985679 --- /dev/null +++ b/google/iam/v1/iam_meta_api.yaml @@ -0,0 +1,85 @@ +type: google.api.Service +config_version: 2 +name: iam-meta-api.googleapis.com +title: IAM Meta API + +apis: +- name: google.iam.v1.IAMPolicy + +types: +- name: google.iam.v1.PolicyDelta + +documentation: + summary: Manages access control for Google Cloud Platform resources. + overview: |- + # Google Identity and Access Management (IAM) API + + Documentation of the access control API that will be implemented by all + 1st party services provided by the Google Cloud Platform (like Cloud + Storage, Compute Engine, App Engine). + + Any implementation of an API that offers access control features + will implement the google.iam.v1.IAMPolicy interface. + + ## Data model + + Access control is applied when a principal (user or service account), + takes some action on a resource exposed by a service. Resources, + identified by + URI-like names, are the unit of access control specification. It is up to + the service implementations to choose what granularity of access control + to support and what set of actions (permissions) to support for the + resources + they provide. For example one database service may allow access control to + be specified only at the Table level, whereas another might allow access + control to also be specified at the Column level. + + This is intentionally not a CRUD style API because access control policies + are created and deleted implicitly with the resources to which they are + attached. + + ## Policy + + A `Policy` consists of a list of bindings. A `Binding` binds a set of + members to a role, where the members can include user accounts, user + groups, user + domains, and service accounts. A role is a named set of permissions, + defined by the IAM system. The definition of a role is outside the + policy. + + A permission check involves determining the roles that include the + specified permission, and then determining if the principal specified by + the check is a member of a binding to at least one of these roles. The + membership check is recursive when a group is bound to a role. + rules: + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + description: |- + Gets the access control policy for a resource. Returns an empty policy + if the resource exists and does not have a policy set. + + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + description: |- + Sets the access control policy on the specified resource. Replaces + any existing policy. + + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + description: |- + Returns permissions that a caller has on the specified resource. If the + resource does not exist, this will return an empty set of + permissions, not a NOT_FOUND error. + + Note: This operation is designed to be used for building + permission-aware UIs and command-line tools, not for authorization + checking. This operation may "fail open" without warning. + +http: + rules: + - selector: google.iam.v1.IAMPolicy.GetIamPolicy + post: '/v1/{resource=**}:getIamPolicy' + body: '*' + - selector: google.iam.v1.IAMPolicy.SetIamPolicy + post: '/v1/{resource=**}:setIamPolicy' + body: '*' + - selector: google.iam.v1.IAMPolicy.TestIamPermissions + post: '/v1/{resource=**}:testIamPermissions' + body: '*' diff --git a/google/iam/v1/policy.proto b/google/iam/v1/policy.proto index a5e4803f..027a9705 100644 --- a/google/iam/v1/policy.proto +++ b/google/iam/v1/policy.proto @@ -32,27 +32,36 @@ option php_namespace = "Google\\Cloud\\Iam\\V1"; // specify access control policies for Cloud Platform resources. // // -// A `Policy` consists of a list of `bindings`. A `binding` binds a list of -// `members` to a `role`, where the members can be user accounts, Google groups, -// Google domains, and service accounts. A `role` is a named list of permissions -// defined by IAM. +// A `Policy` is a collection of `bindings`. A `binding` binds one or more +// `members` to a single `role`. Members can be user accounts, service accounts, +// Google groups, and domains (such as G Suite). A `role` is a named list of +// permissions (defined by IAM or configured by users). A `binding` can +// optionally specify a `condition`, which is a logic expression that further +// constrains the role binding based on attributes about the request and/or +// target resource. // // **JSON Example** // // { // "bindings": [ // { -// "role": "roles/owner", +// "role": "role/resourcemanager.organizationAdmin", // "members": [ // "user:mike@example.com", // "group:admins@example.com", // "domain:google.com", -// "serviceAccount:my-other-app@appspot.gserviceaccount.com" +// "serviceAccount:my-project-id@appspot.gserviceaccount.com" // ] // }, // { -// "role": "roles/viewer", -// "members": ["user:sean@example.com"] +// "role": "roles/resourcemanager.organizationViewer", +// "members": ["user:eve@example.com"], +// "condition": { +// "title": "expirable access", +// "description": "Does not grant access after Sep 2020", +// "expression": "request.time < +// timestamp('2020-10-01T00:00:00.000Z')", +// } // } // ] // } @@ -64,12 +73,15 @@ option php_namespace = "Google\\Cloud\\Iam\\V1"; // - user:mike@example.com // - group:admins@example.com // - domain:google.com -// - serviceAccount:my-other-app@appspot.gserviceaccount.com -// role: roles/owner +// - serviceAccount:my-project-id@appspot.gserviceaccount.com +// role: roles/resourcemanager.organizationAdmin // - members: -// - user:sean@example.com -// role: roles/viewer -// +// - user:eve@example.com +// role: roles/resourcemanager.organizationViewer +// condition: +// title: expirable access +// description: Does not grant access after Sep 2020 +// expression: request.time < timestamp('2020-10-01T00:00:00.000Z') // // For a description of IAM and its features, see the // [IAM developer's guide](https://cloud.google.com/iam/docs). @@ -79,12 +91,18 @@ message Policy { // Valid values are 0, 1, and 3. Requests specifying an invalid value will be // rejected. // - // Policies with any conditional bindings must specify version 3. Policies - // without any conditional bindings may specify any valid value or leave the - // field unset. + // Operations affecting conditional bindings must specify version 3. This can + // be either setting a conditional policy, modifying a conditional binding, + // or removing a conditional binding from the stored conditional policy. + // Operations on non-conditional policies may specify any valid value or + // leave the field unset. + // + // If no etag is provided in the call to `setIamPolicy`, any version + // compliance checks on the incoming and/or stored policy is skipped. int32 version = 1; - // Associates a list of `members` to a `role`. + // Associates a list of `members` to a `role`. Optionally may specify a + // `condition` that determines when binding is in effect. // `bindings` with no members will result in an error. repeated Binding bindings = 4; @@ -97,7 +115,9 @@ message Policy { // ensure that their change will be applied to the same version of the policy. // // If no `etag` is provided in the call to `setIamPolicy`, then the existing - // policy is overwritten. + // policy is overwritten. Due to blind-set semantics of an etag-less policy, + // 'setIamPolicy' will not fail even if either of incoming or stored policy + // does not meet the version requirements. bytes etag = 3; }