googleapis/google/cloud/accessapproval/v1/accessapproval.proto
Google APIs 9415ba048a chore: update copyright year for auto-generated protos
PiperOrigin-RevId: 732130682
2025-02-28 07:26:00 -08:00

697 lines
26 KiB
Protocol Buffer

// Copyright 2025 Google LLC
//
// 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.cloud.accessapproval.v1;
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
option csharp_namespace = "Google.Cloud.AccessApproval.V1";
option go_package = "cloud.google.com/go/accessapproval/apiv1/accessapprovalpb;accessapprovalpb";
option java_multiple_files = true;
option java_outer_classname = "AccessApprovalProto";
option java_package = "com.google.cloud.accessapproval.v1";
option php_namespace = "Google\\Cloud\\AccessApproval\\V1";
option ruby_package = "Google::Cloud::AccessApproval::V1";
// This API allows a customer to manage accesses to cloud resources by
// Google personnel. It defines the following resource model:
//
// - The API has a collection of
// [ApprovalRequest][google.cloud.accessapproval.v1.ApprovalRequest]
// resources, named `approvalRequests/{approval_request}`
// - The API has top-level settings per Project/Folder/Organization, named
// `accessApprovalSettings`
//
// The service also periodically emails a list of recipients, defined at the
// Project/Folder/Organization level in the accessApprovalSettings, when there
// is a pending ApprovalRequest for them to act on. The ApprovalRequests can
// also optionally be published to a Pub/Sub topic owned by the customer
// (contact support if you would like to enable Pub/Sub notifications).
//
// ApprovalRequests can be approved or dismissed. Google personnel can only
// access the indicated resource or resources if the request is approved
// (subject to some exclusions:
// https://cloud.google.com/access-approval/docs/overview#exclusions).
//
// Note: Using Access Approval functionality will mean that Google may not be
// able to meet the SLAs for your chosen products, as any support response times
// may be dramatically increased. As such the SLAs do not apply to any service
// disruption to the extent impacted by Customer's use of Access Approval. Do
// not enable Access Approval for projects where you may require high service
// availability and rapid response by Google Cloud Support.
//
// After a request is approved or dismissed, no further action may be taken on
// it. Requests with the requested_expiration in the past or with no activity
// for 14 days are considered dismissed. When an approval expires, the request
// is considered dismissed.
//
// If a request is not approved or dismissed, we call it pending.
service AccessApproval {
option (google.api.default_host) = "accessapproval.googleapis.com";
option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
// Lists approval requests associated with a project, folder, or organization.
// Approval requests can be filtered by state (pending, active, dismissed).
// The order is reverse chronological.
rpc ListApprovalRequests(ListApprovalRequestsMessage) returns (ListApprovalRequestsResponse) {
option (google.api.http) = {
get: "/v1/{parent=projects/*}/approvalRequests"
additional_bindings {
get: "/v1/{parent=folders/*}/approvalRequests"
}
additional_bindings {
get: "/v1/{parent=organizations/*}/approvalRequests"
}
};
option (google.api.method_signature) = "parent";
}
// Gets an approval request. Returns NOT_FOUND if the request does not exist.
rpc GetApprovalRequest(GetApprovalRequestMessage) returns (ApprovalRequest) {
option (google.api.http) = {
get: "/v1/{name=projects/*/approvalRequests/*}"
additional_bindings {
get: "/v1/{name=folders/*/approvalRequests/*}"
}
additional_bindings {
get: "/v1/{name=organizations/*/approvalRequests/*}"
}
};
option (google.api.method_signature) = "name";
}
// Approves a request and returns the updated ApprovalRequest.
//
// Returns NOT_FOUND if the request does not exist. Returns
// FAILED_PRECONDITION if the request exists but is not in a pending state.
rpc ApproveApprovalRequest(ApproveApprovalRequestMessage) returns (ApprovalRequest) {
option (google.api.http) = {
post: "/v1/{name=projects/*/approvalRequests/*}:approve"
body: "*"
additional_bindings {
post: "/v1/{name=folders/*/approvalRequests/*}:approve"
body: "*"
}
additional_bindings {
post: "/v1/{name=organizations/*/approvalRequests/*}:approve"
body: "*"
}
};
}
// Dismisses a request. Returns the updated ApprovalRequest.
//
// NOTE: This does not deny access to the resource if another request has been
// made and approved. It is equivalent in effect to ignoring the request
// altogether.
//
// Returns NOT_FOUND if the request does not exist.
//
// Returns FAILED_PRECONDITION if the request exists but is not in a pending
// state.
rpc DismissApprovalRequest(DismissApprovalRequestMessage) returns (ApprovalRequest) {
option (google.api.http) = {
post: "/v1/{name=projects/*/approvalRequests/*}:dismiss"
body: "*"
additional_bindings {
post: "/v1/{name=folders/*/approvalRequests/*}:dismiss"
body: "*"
}
additional_bindings {
post: "/v1/{name=organizations/*/approvalRequests/*}:dismiss"
body: "*"
}
};
}
// Invalidates an existing ApprovalRequest. Returns the updated
// ApprovalRequest.
//
// NOTE: This does not deny access to the resource if another request has been
// made and approved. It only invalidates a single approval.
//
// Returns FAILED_PRECONDITION if the request exists but is not in an approved
// state.
rpc InvalidateApprovalRequest(InvalidateApprovalRequestMessage) returns (ApprovalRequest) {
option (google.api.http) = {
post: "/v1/{name=projects/*/approvalRequests/*}:invalidate"
body: "*"
additional_bindings {
post: "/v1/{name=folders/*/approvalRequests/*}:invalidate"
body: "*"
}
additional_bindings {
post: "/v1/{name=organizations/*/approvalRequests/*}:invalidate"
body: "*"
}
};
}
// Gets the settings associated with a project, folder, or organization.
rpc GetAccessApprovalSettings(GetAccessApprovalSettingsMessage) returns (AccessApprovalSettings) {
option (google.api.http) = {
get: "/v1/{name=projects/*/accessApprovalSettings}"
additional_bindings {
get: "/v1/{name=folders/*/accessApprovalSettings}"
}
additional_bindings {
get: "/v1/{name=organizations/*/accessApprovalSettings}"
}
};
option (google.api.method_signature) = "name";
}
// Updates the settings associated with a project, folder, or organization.
// Settings to update are determined by the value of field_mask.
rpc UpdateAccessApprovalSettings(UpdateAccessApprovalSettingsMessage) returns (AccessApprovalSettings) {
option (google.api.http) = {
patch: "/v1/{settings.name=projects/*/accessApprovalSettings}"
body: "settings"
additional_bindings {
patch: "/v1/{settings.name=folders/*/accessApprovalSettings}"
body: "settings"
}
additional_bindings {
patch: "/v1/{settings.name=organizations/*/accessApprovalSettings}"
body: "settings"
}
};
option (google.api.method_signature) = "settings,update_mask";
}
// Deletes the settings associated with a project, folder, or organization.
// This will have the effect of disabling Access Approval for the project,
// folder, or organization, but only if all ancestors also have Access
// Approval disabled. If Access Approval is enabled at a higher level of the
// hierarchy, then Access Approval will still be enabled at this level as
// the settings are inherited.
rpc DeleteAccessApprovalSettings(DeleteAccessApprovalSettingsMessage) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/v1/{name=projects/*/accessApprovalSettings}"
additional_bindings {
delete: "/v1/{name=folders/*/accessApprovalSettings}"
}
additional_bindings {
delete: "/v1/{name=organizations/*/accessApprovalSettings}"
}
};
option (google.api.method_signature) = "name";
}
// Retrieves the service account that is used by Access Approval to access KMS
// keys for signing approved approval requests.
rpc GetAccessApprovalServiceAccount(GetAccessApprovalServiceAccountMessage) returns (AccessApprovalServiceAccount) {
option (google.api.http) = {
get: "/v1/{name=projects/*/serviceAccount}"
additional_bindings {
get: "/v1/{name=folders/*/serviceAccount}"
}
additional_bindings {
get: "/v1/{name=organizations/*/serviceAccount}"
}
};
option (google.api.method_signature) = "name";
}
}
// Home office and physical location of the principal.
message AccessLocations {
// The "home office" location of the principal. A two-letter country code
// (ISO 3166-1 alpha-2), such as "US", "DE" or "GB" or a region code. In some
// limited situations Google systems may refer refer to a region code instead
// of a country code.
// Possible Region Codes:
//
// * ASI: Asia
// * EUR: Europe
// * OCE: Oceania
// * AFR: Africa
// * NAM: North America
// * SAM: South America
// * ANT: Antarctica
// * ANY: Any location
string principal_office_country = 1;
// Physical location of the principal at the time of the access. A
// two-letter country code (ISO 3166-1 alpha-2), such as "US", "DE" or "GB" or
// a region code. In some limited situations Google systems may refer refer to
// a region code instead of a country code.
// Possible Region Codes:
//
// * ASI: Asia
// * EUR: Europe
// * OCE: Oceania
// * AFR: Africa
// * NAM: North America
// * SAM: South America
// * ANT: Antarctica
// * ANY: Any location
string principal_physical_location_country = 2;
}
message AccessReason {
// Type of access justification.
enum Type {
// Default value for proto, shouldn't be used.
TYPE_UNSPECIFIED = 0;
// Customer made a request or raised an issue that required the principal to
// access customer data. `detail` is of the form ("#####" is the issue ID):
//
// * "Feedback Report: #####"
// * "Case Number: #####"
// * "Case ID: #####"
// * "E-PIN Reference: #####"
// * "Google-#####"
// * "T-#####"
CUSTOMER_INITIATED_SUPPORT = 1;
// The principal accessed customer data in order to diagnose or resolve a
// suspected issue in services. Often this access is used to confirm that
// customers are not affected by a suspected service issue or to remediate a
// reversible system issue.
GOOGLE_INITIATED_SERVICE = 2;
// Google initiated service for security, fraud, abuse, or compliance
// purposes.
GOOGLE_INITIATED_REVIEW = 3;
// The principal was compelled to access customer data in order to respond
// to a legal third party data request or process, including legal processes
// from customers themselves.
THIRD_PARTY_DATA_REQUEST = 4;
// The principal accessed customer data in order to diagnose or resolve a
// suspected issue in services or a known outage.
GOOGLE_RESPONSE_TO_PRODUCTION_ALERT = 5;
}
// Type of access justification.
Type type = 1;
// More detail about certain reason types. See comments for each type above.
string detail = 2;
}
// Information about the digital signature of the resource.
message SignatureInfo {
// The digital signature.
bytes signature = 1;
// How this signature may be verified.
oneof verification_info {
// The public key for the Google default signing, encoded in PEM format. The
// signature was created using a private key which may be verified using
// this public key.
string google_public_key_pem = 2;
// The resource name of the customer CryptoKeyVersion used for signing.
string customer_kms_key_version = 3;
}
}
// A decision that has been made to approve access to a resource.
message ApproveDecision {
// The time at which approval was granted.
google.protobuf.Timestamp approve_time = 1;
// The time at which the approval expires.
google.protobuf.Timestamp expire_time = 2;
// If set, denotes the timestamp at which the approval is invalidated.
google.protobuf.Timestamp invalidate_time = 3;
// The signature for the ApprovalRequest and details on how it was signed.
SignatureInfo signature_info = 4;
// True when the request has been auto-approved.
bool auto_approved = 5;
}
// A decision that has been made to dismiss an approval request.
message DismissDecision {
// The time at which the approval request was dismissed.
google.protobuf.Timestamp dismiss_time = 1;
// This field will be true if the ApprovalRequest was implicitly dismissed due
// to inaction by the access approval approvers (the request is not acted
// on by the approvers before the exiration time).
bool implicit = 2;
}
// The properties associated with the resource of the request.
message ResourceProperties {
// Whether an approval will exclude the descendants of the resource being
// requested.
bool excludes_descendants = 1;
}
// A request for the customer to approve access to a resource.
message ApprovalRequest {
option (google.api.resource) = {
type: "accessapproval.googleapis.com/ApprovalRequest"
pattern: "projects/{project}/approvalRequests/{approval_request}"
pattern: "folders/{folder}/approvalRequests/{approval_request}"
pattern: "organizations/{organization}/approvalRequests/{approval_request}"
};
// The resource name of the request. Format is
// "{projects|folders|organizations}/{id}/approvalRequests/{approval_request}".
string name = 1;
// The resource for which approval is being requested. The format of the
// resource name is defined at
// https://cloud.google.com/apis/design/resource_names. The resource name here
// may either be a "full" resource name (e.g.
// "//library.googleapis.com/shelves/shelf1/books/book2") or a "relative"
// resource name (e.g. "shelves/shelf1/books/book2") as described in the
// resource name specification.
string requested_resource_name = 2;
// Properties related to the resource represented by requested_resource_name.
ResourceProperties requested_resource_properties = 9;
// The justification for which approval is being requested.
AccessReason requested_reason = 3;
// The locations for which approval is being requested.
AccessLocations requested_locations = 4;
// The time at which approval was requested.
google.protobuf.Timestamp request_time = 5;
// The requested expiration for the approval. If the request is approved,
// access will be granted from the time of approval until the expiration time.
google.protobuf.Timestamp requested_expiration = 6;
// The current decision on the approval request.
oneof decision {
// Access was approved.
ApproveDecision approve = 7;
// The request was dismissed.
DismissDecision dismiss = 8;
}
}
// Represents the type of enrollment for a given service to Access Approval.
enum EnrollmentLevel {
// Default value for proto, shouldn't be used.
ENROLLMENT_LEVEL_UNSPECIFIED = 0;
// Service is enrolled in Access Approval for all requests
BLOCK_ALL = 1;
}
// Represents the enrollment of a cloud resource into a specific service.
message EnrolledService {
// The product for which Access Approval will be enrolled. Allowed values are
// listed below (case-sensitive):
//
// * all
// * GA
// * App Engine
// * BigQuery
// * Cloud Bigtable
// * Cloud Key Management Service
// * Compute Engine
// * Cloud Dataflow
// * Cloud Dataproc
// * Cloud DLP
// * Cloud EKM
// * Cloud HSM
// * Cloud Identity and Access Management
// * Cloud Logging
// * Cloud Pub/Sub
// * Cloud Spanner
// * Cloud SQL
// * Cloud Storage
// * Google Kubernetes Engine
// * Organization Policy Serivice
// * Persistent Disk
// * Resource Manager
// * Secret Manager
// * Speaker ID
//
// Note: These values are supported as input for legacy purposes, but will not
// be returned from the API.
//
// * all
// * ga-only
// * appengine.googleapis.com
// * bigquery.googleapis.com
// * bigtable.googleapis.com
// * container.googleapis.com
// * cloudkms.googleapis.com
// * cloudresourcemanager.googleapis.com
// * cloudsql.googleapis.com
// * compute.googleapis.com
// * dataflow.googleapis.com
// * dataproc.googleapis.com
// * dlp.googleapis.com
// * iam.googleapis.com
// * logging.googleapis.com
// * orgpolicy.googleapis.com
// * pubsub.googleapis.com
// * spanner.googleapis.com
// * secretmanager.googleapis.com
// * speakerid.googleapis.com
// * storage.googleapis.com
//
// Calls to UpdateAccessApprovalSettings using 'all' or any of the
// XXX.googleapis.com will be translated to the associated product name
// ('all', 'App Engine', etc.).
//
// Note: 'all' will enroll the resource in all products supported at both 'GA'
// and 'Preview' levels.
//
// More information about levels of support is available at
// https://cloud.google.com/access-approval/docs/supported-services
string cloud_product = 1;
// The enrollment level of the service.
EnrollmentLevel enrollment_level = 2;
}
// Settings on a Project/Folder/Organization related to Access Approval.
message AccessApprovalSettings {
option (google.api.resource) = {
type: "accessapproval.googleapis.com/AccessApprovalSettings"
pattern: "projects/{project}/accessApprovalSettings"
pattern: "folders/{folder}/accessApprovalSettings"
pattern: "organizations/{organization}/accessApprovalSettings"
};
// The resource name of the settings. Format is one of:
//
// * "projects/{project}/accessApprovalSettings"
// * "folders/{folder}/accessApprovalSettings"
// * "organizations/{organization}/accessApprovalSettings"
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/AccessApprovalSettings"
}];
// A list of email addresses to which notifications relating to approval
// requests should be sent. Notifications relating to a resource will be sent
// to all emails in the settings of ancestor resources of that resource. A
// maximum of 50 email addresses are allowed.
repeated string notification_emails = 2;
// A list of Google Cloud Services for which the given resource has Access
// Approval enrolled. Access requests for the resource given by name against
// any of these services contained here will be required to have explicit
// approval. If name refers to an organization, enrollment can be done for
// individual services. If name refers to a folder or project, enrollment can
// only be done on an all or nothing basis.
//
// If a cloud_product is repeated in this list, the first entry will be
// honored and all following entries will be discarded. A maximum of 10
// enrolled services will be enforced, to be expanded as the set of supported
// services is expanded.
repeated EnrolledService enrolled_services = 3;
// Output only. This field is read only (not settable via
// UpdateAccessApprovalSettings method). If the field is true, that
// indicates that at least one service is enrolled for Access Approval in one
// or more ancestors of the Project or Folder (this field will always be
// unset for the organization since organizations do not have ancestors).
bool enrolled_ancestor = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
// The asymmetric crypto key version to use for signing approval requests.
// Empty active_key_version indicates that a Google-managed key should be used
// for signing. This property will be ignored if set by an ancestor of this
// resource, and new non-empty values may not be set.
string active_key_version = 6;
// Output only. This field is read only (not settable via UpdateAccessApprovalSettings
// method). If the field is true, that indicates that an ancestor of this
// Project or Folder has set active_key_version (this field will always be
// unset for the organization since organizations do not have ancestors).
bool ancestor_has_active_key_version = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. This field is read only (not settable via UpdateAccessApprovalSettings
// method). If the field is true, that indicates that there is some
// configuration issue with the active_key_version configured at this level in
// the resource hierarchy (e.g. it doesn't exist or the Access Approval
// service account doesn't have the correct permissions on it, etc.) This key
// version is not necessarily the effective key version at this level, as key
// versions are inherited top-down.
bool invalid_key_version = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
}
// Access Approval service account related to a project/folder/organization.
message AccessApprovalServiceAccount {
option (google.api.resource) = {
type: "accessapproval.googleapis.com/AccessApprovalServiceAccount"
pattern: "projects/{project}/serviceAccount"
pattern: "folders/{folder}/serviceAccount"
pattern: "organizations/{organization}/serviceAccount"
};
// The resource name of the Access Approval service account. Format is one of:
//
// * "projects/{project}/serviceAccount"
// * "folders/{folder}/serviceAccount"
// * "organizations/{organization}/serviceAccount"
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/AccessApprovalServiceAccount"
}];
// Email address of the service account.
string account_email = 2;
}
// Request to list approval requests.
message ListApprovalRequestsMessage {
// The parent resource. This may be "projects/{project}",
// "folders/{folder}", or "organizations/{organization}".
string parent = 1 [(google.api.resource_reference) = {
child_type: "accessapproval.googleapis.com/ApprovalRequest"
}];
// A filter on the type of approval requests to retrieve. Must be one of the
// following values:
//
// * [not set]: Requests that are pending or have active approvals.
// * ALL: All requests.
// * PENDING: Only pending requests.
// * ACTIVE: Only active (i.e. currently approved) requests.
// * DISMISSED: Only requests that have been dismissed, or requests that
// are not approved and past expiration.
// * EXPIRED: Only requests that have been approved, and the approval has
// expired.
// * HISTORY: Active, dismissed and expired requests.
string filter = 2;
// Requested page size.
int32 page_size = 3;
// A token identifying the page of results to return.
string page_token = 4;
}
// Response to listing of ApprovalRequest objects.
message ListApprovalRequestsResponse {
// Approval request details.
repeated ApprovalRequest approval_requests = 1;
// Token to retrieve the next page of results, or empty if there are no more.
string next_page_token = 2;
}
// Request to get an approval request.
message GetApprovalRequestMessage {
// The name of the approval request to retrieve.
// Format:
// "{projects|folders|organizations}/{id}/approvalRequests/{approval_request}"
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/ApprovalRequest"
}];
}
// Request to approve an ApprovalRequest.
message ApproveApprovalRequestMessage {
// Name of the approval request to approve.
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/ApprovalRequest"
}];
// The expiration time of this approval.
google.protobuf.Timestamp expire_time = 2;
}
// Request to dismiss an approval request.
message DismissApprovalRequestMessage {
// Name of the ApprovalRequest to dismiss.
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/ApprovalRequest"
}];
}
// Request to invalidate an existing approval.
message InvalidateApprovalRequestMessage {
// Name of the ApprovalRequest to invalidate.
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/ApprovalRequest"
}];
}
// Request to get access approval settings.
message GetAccessApprovalSettingsMessage {
// The name of the AccessApprovalSettings to retrieve.
// Format: "{projects|folders|organizations}/{id}/accessApprovalSettings"
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/AccessApprovalSettings"
}];
}
// Request to update access approval settings.
message UpdateAccessApprovalSettingsMessage {
// The new AccessApprovalSettings.
AccessApprovalSettings settings = 1;
// The update mask applies to the settings. Only the top level fields of
// AccessApprovalSettings (notification_emails & enrolled_services) are
// supported. For each field, if it is included, the currently stored value
// will be entirely overwritten with the value of the field passed in this
// request.
//
// For the `FieldMask` definition, see
// https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask
// If this field is left unset, only the notification_emails field will be
// updated.
google.protobuf.FieldMask update_mask = 2;
}
// Request to delete access approval settings.
message DeleteAccessApprovalSettingsMessage {
// Name of the AccessApprovalSettings to delete.
string name = 1 [(google.api.resource_reference) = {
type: "accessapproval.googleapis.com/AccessApprovalSettings"
}];
}
// Request to get an Access Approval service account.
message GetAccessApprovalServiceAccountMessage {
// Name of the AccessApprovalServiceAccount to retrieve.
string name = 1;
}