Synchronize new proto changes.

This commit is contained in:
Google APIs 2017-08-31 18:08:59 -07:00
parent 1bf90f3c53
commit a56dc4ee7f
3 changed files with 365 additions and 48 deletions

View File

@ -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.
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).

View File

@ -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
// <a href="/sdk/gcloud/reference/auth/activate-service-account">gcloud
// auth activate-service-account</a>.
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;
}

View File

@ -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;
}