From a56dc4ee7f04d364f0e3c4e2e0e2edc01ba1fefb Mon Sep 17 00:00:00 2001 From: Google APIs Date: Thu, 31 Aug 2017 18:08:59 -0700 Subject: [PATCH] Synchronize new proto changes. --- google/iam/README.md | 39 +-- google/iam/admin/v1/iam.proto | 339 +++++++++++++++++++++++-- google/iam/v1/logging/audit_data.proto | 35 +++ 3 files changed, 365 insertions(+), 48 deletions(-) create mode 100644 google/iam/v1/logging/audit_data.proto diff --git a/google/iam/README.md b/google/iam/README.md index 68e7fa01..c402a9dd 100644 --- a/google/iam/README.md +++ b/google/iam/README.md @@ -1,35 +1,14 @@ -# Google Identity and Access Management (IAM) API +# Introduction -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). +# Key Concepts -Any implementation of an API that offers access control features -will implement the google.iam.v1.IAMPolicy interface. +## Service Account -## Data model +A Service Account is an account used to identify services (non-humans) to Google. +A Service Account has a list of Service Account Keys, which can be used to authenticate to Google. -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. +## Service Account Keys -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. \ No newline at end of file +A Service Account Key is a public/private keypair generated by Google. Google retains the public +key, while the customer is given the private key. The private key can be used to [sign JWTs and +authenticate Service Accounts to Google](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#authorizingrequests). diff --git a/google/iam/admin/v1/iam.proto b/google/iam/admin/v1/iam.proto index 2e2fe2b7..8632b4d2 100644 --- a/google/iam/admin/v1/iam.proto +++ b/google/iam/admin/v1/iam.proto @@ -1,4 +1,4 @@ -// Copyright 2016 Google Inc. +// Copyright 2017 Google Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -42,7 +42,7 @@ option java_package = "com.google.iam.admin.v1"; // `unique_id`. // // All other methods can identify accounts using the format -// `projects/{project}/serviceAccounts/{account}`. +// `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the // `unique_id` of the service account. @@ -104,6 +104,15 @@ service IAM { option (google.api.http) = { post: "/v1/{name=projects/*/serviceAccounts/*}:signBlob" body: "*" }; } + // Signs a JWT using a service account's system-managed private key. + // + // If no expiry time (`exp`) is provided in the `SignJwtRequest`, IAM sets an + // an expiry time of one hour by default. If you request an expiry time of + // more than one hour, the request will fail. + rpc SignJwt(SignJwtRequest) returns (SignJwtResponse) { + option (google.api.http) = { post: "/v1/{name=projects/*/serviceAccounts/*}:signJwt" body: "*" }; + } + // Returns the IAM access control policy for a // [ServiceAccount][google.iam.admin.v1.ServiceAccount]. rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { @@ -128,6 +137,48 @@ service IAM { rpc QueryGrantableRoles(QueryGrantableRolesRequest) returns (QueryGrantableRolesResponse) { option (google.api.http) = { post: "/v1/roles:queryGrantableRoles" body: "*" }; } + + // Lists the Roles defined on a resource. + rpc ListRoles(ListRolesRequest) returns (ListRolesResponse) { + option (google.api.http) = { get: "/v1/roles" }; + } + + // Gets a Role definition. + rpc GetRole(GetRoleRequest) returns (Role) { + option (google.api.http) = { get: "/v1/{name=roles/*}" }; + } + + // Creates a new Role. + rpc CreateRole(CreateRoleRequest) returns (Role) { + option (google.api.http) = { post: "/v1/{parent=organizations/*}/roles" body: "*" }; + } + + // Updates a Role definition. + rpc UpdateRole(UpdateRoleRequest) returns (Role) { + option (google.api.http) = { patch: "/v1/{name=organizations/*/roles/*}" body: "role" }; + } + + // Soft deletes a role. The role is suspended and cannot be used to create new + // IAM Policy Bindings. + // The Role will not be included in `ListRoles()` unless `show_deleted` is set + // in the `ListRolesRequest`. The Role contains the deleted boolean set. + // Existing Bindings remains, but are inactive. The Role can be undeleted + // within 7 days. After 7 days the Role is deleted and all Bindings associated + // with the role are removed. + rpc DeleteRole(DeleteRoleRequest) returns (Role) { + option (google.api.http) = { delete: "/v1/{name=organizations/*/roles/*}" }; + } + + // Undelete a Role, bringing it back in its previous state. + rpc UndeleteRole(UndeleteRoleRequest) returns (Role) { + option (google.api.http) = { post: "/v1/{name=organizations/*/roles/*}:undelete" body: "*" }; + } + + // Lists the permissions testable on a resource. + // A permission is testable if it can be tested for an identity on a resource. + rpc QueryTestablePermissions(QueryTestablePermissionsRequest) returns (QueryTestablePermissionsResponse) { + option (google.api.http) = { post: "/v1/permissions:queryTestablePermissions" body: "*" }; + } } // A service account in the Identity and Access Management API. @@ -139,24 +190,24 @@ service IAM { // // If the account already exists, the account's resource name is returned // in util::Status's ResourceInfo.resource_name in the format of -// projects/{project}/serviceAccounts/{email}. The caller can use the name in -// other methods to access the account. +// projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}. The caller can +// use the name in other methods to access the account. // // All other methods can identify the service account using the format -// `projects/{project}/serviceAccounts/{account}`. +// `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the // `unique_id` of the service account. message ServiceAccount { // The resource name of the service account in the following format: - // `projects/{project}/serviceAccounts/{account}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // // Requests using `-` as a wildcard for the project will infer the project // from the `account` and the `account` value can be the `email` address or // the `unique_id` of the service account. // // In responses the resource name will always be in the format - // `projects/{project}/serviceAccounts/{email}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. string name = 1; // @OutputOnly The id of the project that owns the service account. @@ -230,7 +281,7 @@ message ListServiceAccountsResponse { // The service account get request. message GetServiceAccountRequest { // The resource name of the service account in the following format: - // `projects/{project}/serviceAccounts/{account}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the // `unique_id` of the service account. @@ -240,7 +291,7 @@ message GetServiceAccountRequest { // The service account delete request. message DeleteServiceAccountRequest { // The resource name of the service account in the following format: - // `projects/{project}/serviceAccounts/{account}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the // `unique_id` of the service account. @@ -264,7 +315,7 @@ message ListServiceAccountKeysRequest { } // The resource name of the service account in the following format: - // `projects/{project}/serviceAccounts/{account}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // // Using `-` as a wildcard for the project, will infer the project from // the account. The `account` value can be the `email` address or the @@ -286,7 +337,7 @@ message ListServiceAccountKeysResponse { // The service account key get by id request. message GetServiceAccountKeyRequest { // The resource name of the service account key in the following format: - // `projects/{project}/serviceAccounts/{account}/keys/{key}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}/keys/{key}`. // // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the @@ -316,7 +367,7 @@ message GetServiceAccountKeyRequest { // Service Account API. message ServiceAccountKey { // The resource name of the service account key in the following format - // `projects/{project}/serviceAccounts/{account}/keys/{key}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}/keys/{key}`. string name = 1; // The output format for the private key. @@ -331,7 +382,12 @@ message ServiceAccountKey { ServiceAccountKeyAlgorithm key_algorithm = 8; // The private key data. Only provided in `CreateServiceAccountKey` - // responses. + // responses. Make sure to keep the private key data secure because it + // allows for the assertion of the service account identity. + // When decoded, the private key data can be used to authenticate with + // Google API client libraries and with + // gcloud + // auth activate-service-account. bytes private_key_data = 3; // The public key data. Only provided in `GetServiceAccountKey` responses. @@ -347,7 +403,7 @@ message ServiceAccountKey { // The service account key create request. message CreateServiceAccountKeyRequest { // The resource name of the service account in the following format: - // `projects/{project}/serviceAccounts/{account}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the // `unique_id` of the service account. @@ -358,7 +414,7 @@ message CreateServiceAccountKeyRequest { ServiceAccountPrivateKeyType private_key_type = 2; // Which type of key and algorithm to use for the key. - // The default is currently a 4K RSA key. However this may change in the + // The default is currently a 2K RSA key. However this may change in the // future. ServiceAccountKeyAlgorithm key_algorithm = 3; } @@ -366,7 +422,7 @@ message CreateServiceAccountKeyRequest { // The service account key delete request. message DeleteServiceAccountKeyRequest { // The resource name of the service account key in the following format: - // `projects/{project}/serviceAccounts/{account}/keys/{key}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}/keys/{key}`. // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the // `unique_id` of the service account. @@ -376,7 +432,7 @@ message DeleteServiceAccountKeyRequest { // The service account sign blob request. message SignBlobRequest { // The resource name of the service account in the following format: - // `projects/{project}/serviceAccounts/{account}`. + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. // Using `-` as a wildcard for the project will infer the project from // the account. The `account` value can be the `email` address or the // `unique_id` of the service account. @@ -395,15 +451,59 @@ message SignBlobResponse { bytes signature = 2; } +// The service account sign JWT request. +message SignJwtRequest { + // The resource name of the service account in the following format: + // `projects/{PROJECT_ID}/serviceAccounts/{SERVICE_ACCOUNT_EMAIL}`. + // Using `-` as a wildcard for the project will infer the project from + // the account. The `account` value can be the `email` address or the + // `unique_id` of the service account. + string name = 1; + + // The JWT payload to sign, a JSON JWT Claim set. + string payload = 2; +} + +// The service account sign JWT response. +message SignJwtResponse { + // The id of the key used to sign the JWT. + string key_id = 1; + + // The signed JWT. + string signed_jwt = 2; +} + // A role in the Identity and Access Management API. message Role { + // A stage representing a role's lifecycle phase. + enum RoleLaunchStage { + // The user has indicated this role is currently in an alpha phase. + ALPHA = 0; + + // The user has indicated this role is currently in a beta phase. + BETA = 1; + + // The user has indicated this role is generally available. + GA = 2; + + // The user has indicated this role is being deprecated. + DEPRECATED = 4; + + // This role is disabled and will not contribute permissions to any members + // it is granted to in policies. + DISABLED = 5; + + // The user has indicated this role is currently in an eap phase. + EAP = 6; + } + // The name of the role. // // When Role is used in CreateRole, the role name must not be set. // // When Role is used in output and other input such as UpdateRole, the role // name is the complete path, e.g., roles/logging.viewer for curated roles - // and organizations/{organization-id}/roles/logging.viewer for custom roles. + // and organizations/{ORGANIZATION_ID}/roles/logging.viewer for custom roles. string name = 1; // Optional. A human-readable title for the role. Typically this @@ -412,6 +512,19 @@ message Role { // Optional. A human-readable description for the role. string description = 3; + + // The names of the permissions this role grants when bound in an IAM policy. + repeated string included_permissions = 7; + + // The current launch stage of the role. + RoleLaunchStage stage = 8; + + // Used to perform a consistent read-modify-write. + bytes etag = 9; + + // The current deleted state of the role. This field is read only. + // It will be ignored in calls to CreateRole and UpdateRole. + bool deleted = 11; } // The grantable role query request. @@ -422,12 +535,192 @@ message QueryGrantableRolesRequest { // For example, a Cloud Platform project with id `my-project` will be named // `//cloudresourcemanager.googleapis.com/projects/my-project`. string full_resource_name = 1; + + RoleView view = 2; + + // Optional limit on the number of roles to include in the response. + int32 page_size = 3; + + // Optional pagination token returned in an earlier + // QueryGrantableRolesResponse. + string page_token = 4; } // The grantable role query response. message QueryGrantableRolesResponse { // The list of matching roles. repeated Role roles = 1; + + // To retrieve the next page of results, set + // `QueryGrantableRolesRequest.page_token` to this value. + string next_page_token = 2; +} + +// The request to get all roles defined under a resource. +message ListRolesRequest { + // The resource name of the parent resource in one of the following formats: + // `` (empty string) -- this refers to curated roles. + // `organizations/{ORGANIZATION_ID}` + // `projects/{PROJECT_ID}` + string parent = 1; + + // Optional limit on the number of roles to include in the response. + int32 page_size = 2; + + // Optional pagination token returned in an earlier ListRolesResponse. + string page_token = 3; + + // Optional view for the returned Role objects. + RoleView view = 4; + + // Include Roles that have been deleted. + bool show_deleted = 6; +} + +// The response containing the roles defined under a resource. +message ListRolesResponse { + // The Roles defined on this resource. + repeated Role roles = 1; + + // To retrieve the next page of results, set + // `ListRolesRequest.page_token` to this value. + string next_page_token = 2; +} + +// The request to get the definition of an existing role. +message GetRoleRequest { + // The resource name of the role in one of the following formats: + // `roles/{ROLE_NAME}` + // `organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}` + // `projects/{PROJECT_ID}/roles/{ROLE_NAME}` + string name = 1; +} + +// The request to create a new role. +message CreateRoleRequest { + // The resource name of the parent resource in one of the following formats: + // `organizations/{ORGANIZATION_ID}` + // `projects/{PROJECT_ID}` + string parent = 1; + + // The role id to use for this role. + string role_id = 2; + + // The Role resource to create. + Role role = 3; +} + +// The request to update a role. +message UpdateRoleRequest { + // The resource name of the role in one of the following formats: + // `roles/{ROLE_NAME}` + // `organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}` + // `projects/{PROJECT_ID}/roles/{ROLE_NAME}` + string name = 1; + + // The updated role. + Role role = 2; + + // A mask describing which fields in the Role have changed. + google.protobuf.FieldMask update_mask = 3; +} + +// The request to delete an existing role. +message DeleteRoleRequest { + // The resource name of the role in one of the following formats: + // `organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}` + // `projects/{PROJECT_ID}/roles/{ROLE_NAME}` + string name = 1; + + // Used to perform a consistent read-modify-write. + bytes etag = 2; +} + +// The request to undelete an existing role. +message UndeleteRoleRequest { + // The resource name of the role in one of the following formats: + // `organizations/{ORGANIZATION_ID}/roles/{ROLE_NAME}` + // `projects/{PROJECT_ID}/roles/{ROLE_NAME}` + string name = 1; + + // Used to perform a consistent read-modify-write. + bytes etag = 2; +} + +// A permission which can be included by a role. +message Permission { + // A stage representing a permission's lifecycle phase. + enum PermissionLaunchStage { + // The permission is currently in an alpha phase. + ALPHA = 0; + + // The permission is currently in a beta phase. + BETA = 1; + + // The permission is generally available. + GA = 2; + + // The permission is being deprecated. + DEPRECATED = 3; + } + + // The state of the permission with regards to custom roles. + enum CustomRolesSupportLevel { + // Permission is fully supported for custom role use. + SUPPORTED = 0; + + // Permission is being tested to check custom role compatibility. + TESTING = 1; + + // Permission is not supported for custom role use. + NOT_SUPPORTED = 2; + } + + // The name of this Permission. + string name = 1; + + // The title of this Permission. + string title = 2; + + // A brief description of what this Permission is used for. + string description = 3; + + // This permission can ONLY be used in predefined roles. + bool only_in_predefined_roles = 4; + + // The current launch stage of the permission. + PermissionLaunchStage stage = 5; + + // The current custom role support level. + CustomRolesSupportLevel custom_roles_support_level = 6; +} + +// A request to get permissions which can be tested on a resource. +message QueryTestablePermissionsRequest { + // Required. The full resource name to query from the list of testable + // permissions. + // + // The name follows the Google Cloud Platform resource format. + // For example, a Cloud Platform project with id `my-project` will be named + // `//cloudresourcemanager.googleapis.com/projects/my-project`. + string full_resource_name = 1; + + // Optional limit on the number of permissions to include in the response. + int32 page_size = 2; + + // Optional pagination token returned in an earlier + // QueryTestablePermissionsRequest. + string page_token = 3; +} + +// The response containing permissions which can be tested on a resource. +message QueryTestablePermissionsResponse { + // The Permissions testable on the requested resource. + repeated Permission permissions = 1; + + // To retrieve the next page of results, set + // `QueryTestableRolesRequest.page_token` to this value. + string next_page_token = 2; } // Supported key algorithms. @@ -467,3 +760,13 @@ enum ServiceAccountPublicKeyType { // Raw public key. TYPE_RAW_PUBLIC_KEY = 2; } + +// A view for Role objects. +enum RoleView { + // Omits the `included_permissions` field. + // This is the default value. + BASIC = 0; + + // Returns all fields. + FULL = 1; +} diff --git a/google/iam/v1/logging/audit_data.proto b/google/iam/v1/logging/audit_data.proto new file mode 100644 index 00000000..d3f803fe --- /dev/null +++ b/google/iam/v1/logging/audit_data.proto @@ -0,0 +1,35 @@ +// Copyright 2017 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.logging; + +import "google/api/annotations.proto"; +import "google/iam/v1/policy.proto"; + +option csharp_namespace = "Google.Cloud.Iam.V1.Logging"; +option go_package = "google.golang.org/genproto/googleapis/iam/v1/logging;logging"; +option java_multiple_files = true; +option java_outer_classname = "AuditDataProto"; +option java_package = "com.google.iam.v1.logging"; + + +// Audit log information specific to Cloud IAM. This message is serialized +// as an `Any` type in the `ServiceData` message of an +// `AuditLog` message. +message AuditData { + // Policy delta between the original policy and the newly set policy. + google.iam.v1.PolicyDelta policy_delta = 2; +}