From ecea2e20198937afab6aaddd51af470695bd81e5 Mon Sep 17 00:00:00 2001 From: wora Date: Wed, 22 Jul 2015 13:20:07 -0700 Subject: [PATCH] Initial submit of Google Identity and Access Management API v1. This is a meta interface that needs to be implemented by each API service that will use IAM API for access control. This interface is client facing. The implementation will use a different API. --- google/iam/README.md | 35 +++++++++++ google/iam/v1/iam_policy.proto | 98 +++++++++++++++++++++++++++++ google/iam/v1/policy.proto | 111 +++++++++++++++++++++++++++++++++ 3 files changed, 244 insertions(+) create mode 100644 google/iam/README.md create mode 100644 google/iam/v1/iam_policy.proto create mode 100644 google/iam/v1/policy.proto diff --git a/google/iam/README.md b/google/iam/README.md new file mode 100644 index 00000000..0aaf0352 --- /dev/null +++ b/google/iam/README.md @@ -0,0 +1,35 @@ +# 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 resource 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 +policies are modeled as virtual properties of resources, and 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. \ No newline at end of file diff --git a/google/iam/v1/iam_policy.proto b/google/iam/v1/iam_policy.proto new file mode 100644 index 00000000..63495804 --- /dev/null +++ b/google/iam/v1/iam_policy.proto @@ -0,0 +1,98 @@ +// Copyright (c) 2015, Google Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.iam.v1; + +import "google/iam/v1/policy.proto"; + +option java_multiple_files = true; +option java_outer_classname = "IamPolicyProto"; +option java_package = "com.google.iam.v1"; + + +// ## API Overview +// +// Any implementation of an API that offers access control features +// implements 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. Service +// implementations can choose the granularity of access control and the +// supported permissions for their resources. +// 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. +// +// ## Policy Structure +// +// See google.iam.v1.Policy +// +// 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. +service IAMPolicy { + // Sets the access control policy on the specified resource. Replaces any + // existing policy. + rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy); + + // Gets the access control policy for a resource. Is empty if the + // policy or the resource does not exist. + rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy); + + // Returns permissions that a caller has on the specified resource. + rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse); +} + +// Request message for `SetIamPolicy` method. +message SetIamPolicyRequest { + // REQUIRED: The resource for which policy is being specified. + // Resource is usually specified as a path, such as, + // projects/{project}/zones/{zone}/disks/{disk}. + string resource = 1; + + // REQUIRED: The complete policy to be applied to the 'resource'. The size of + // the policy is limited to a few 10s of KB. An empty policy is in general a + // valid policy but certain services (like Projects) might reject them. + Policy policy = 2; +} + +// Request message for `GetIamPolicy` method. +message GetIamPolicyRequest { + // REQUIRED: The resource for which policy is being requested. Resource + // is usually specified as a path, such as, projects/{project}. + string resource = 1; +} + +// Request message for `TestIamPermissions` method. +message TestIamPermissionsRequest { + // REQUIRED: The resource for which policy detail is being requested. + // Resource is usually specified as a path, such as, projects/{project}. + string resource = 1; + + // The set of permissions to check for the 'resource'. Permissions with + // wildcards (such as '*' or 'storage.*') are not allowed. + repeated string permissions = 2; +} + +// Response message for `TestIamPermissions` method. +message TestIamPermissionsResponse { + // A subset of `TestPermissionsRequest.permissions` that the caller is + // allowed. + repeated string permissions = 1; +} diff --git a/google/iam/v1/policy.proto b/google/iam/v1/policy.proto new file mode 100644 index 00000000..45933329 --- /dev/null +++ b/google/iam/v1/policy.proto @@ -0,0 +1,111 @@ +// Copyright (c) 2015, Google Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.iam.v1; + +import public "google/iam/v1/rule.proto"; + +option java_multiple_files = true; +option java_outer_classname = "PolicyProto"; +option java_package = "com.google.iam.v1"; + + +// # Overview +// +// The `Policy` defines an access control policy language. It is used to +// define policies that are attached to resources like files, folders, VMs, +// etc. +// +// +// # Policy structure +// +// A `Policy` consists of a list of bindings. A `Binding` binds a set of members +// to a role, where the members include user accounts, user groups, user +// domains, and service accounts. A 'role' is a named set of permissions, +// defined by IAM. The definition of a role is outside the policy. +// +// A permission check first determines the roles that include the specified +// permission, and then determines if the principal specified 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. +// +// Policy examples: +// +// ``` +// { +// "bindings": [ +// { +// "role": "roles/owner", +// "members": [ +// "user:mike@example.com", +// "group:admins@example.com", +// "domain:google.com", +// "serviceAccount:frontend@example.iam.gserviceaccounts.com"] +// }, +// { +// "role": "roles/viewer", +// "members": ["user:sean@example.com"] +// } +// ] +// } +// ``` +message Policy { + // The policy language version. The version of the policy is + // represented by the etag. The default version is 0. + int32 version = 1; + + // It is an error to specify multiple bindings for the same role. + // It is an error to specify a binding with no members. + repeated Binding bindings = 4; + + repeated google.iam.v1.Rule rules = 2; + + // Can be used to perform a read-modify-write. + bytes etag = 3; +} + +// Associates members with roles. See below for allowed +// formats of members. +message Binding { + // The name of the role to which the members should be bound. + // Examples: "roles/viewer", "roles/editor", "roles/owner". + // Required + string role = 1; + + // Format of member entries: + // 1. allUsers + // Matches any requesting principal (users, service accounts or anonymous). + // + // 2. allAuthenticatedUsers + // Matches any requesting authenticated principal (users or service + // accounts). + // + // 3. user:{emailid} + // A google user account using an email address. + // For example alice@gmail.com, joe@example.com + // + // 4. serviceAccount:{emailid} + // An service account email. + // + // 5. group:{emailid} + // A google group with an email address. For example + // auth-ti-cloud@google.com + // + // 6. domain:{domain} + // A Google Apps domain name. + // For example google.com, example.com + repeated string members = 2; +}