googleapis/google/cloud/ces/v1beta/auth.proto

// Copyright 2026 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.ces.v1beta;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";

option go_package = "cloud.google.com/go/ces/apiv1beta/cespb;cespb";
option java_multiple_files = true;
option java_outer_classname = "AuthProto";
option java_package = "com.google.cloud.ces.v1beta";
option (google.api.resource_definition) = {
  type: "secretmanager.googleapis.com/SecretVersion"
  pattern: "projects/{project}/secrets/{secret}/versions/{secret_version}"
};

// Configurations for authentication with API key.
message ApiKeyConfig {
  // The location of the API key in the request.
  enum RequestLocation {
    // Unspecified. This value should not be used.
    REQUEST_LOCATION_UNSPECIFIED = 0;

    // Represents the key in http header.
    HEADER = 1;

    // Represents the key in query string.
    QUERY_STRING = 2;
  }

  // Required. The parameter name or the header name of the API key.
  // E.g., If the API request is "https://example.com/act?X-Api-Key=<API
  // KEY>", "X-Api-Key" would be the parameter name.
  string key_name = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The name of the SecretManager secret version resource storing the
  // API key. Format: `projects/{project}/secrets/{secret}/versions/{version}`
  //
  // Note: You should grant `roles/secretmanager.secretAccessor` role to the CES
  // service agent
  // `service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com`.
  string api_key_secret_version = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/SecretVersion"
    }
  ];

  // Required. Key location in the request.
  RequestLocation request_location = 3 [(google.api.field_behavior) = REQUIRED];
}

// Configurations for authentication with OAuth.
message OAuthConfig {
  // OAuth grant types. Only [client credential
  // grant](https://oauth.net/2/grant-types/client-credentials) is supported.
  enum OauthGrantType {
    // Unspecified. Defaults to CLIENT_CREDENTIAL.
    OAUTH_GRANT_TYPE_UNSPECIFIED = 0;

    // Represents the [client credential
    // flow](https://oauth.net/2/grant-types/client-credentials).
    CLIENT_CREDENTIAL = 1;
  }

  // Required. OAuth grant types.
  OauthGrantType oauth_grant_type = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The client ID from the OAuth provider.
  string client_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The name of the SecretManager secret version resource storing the
  // client secret.
  // Format: `projects/{project}/secrets/{secret}/versions/{version}`
  //
  // Note: You should grant `roles/secretmanager.secretAccessor` role to the CES
  // service agent
  // `service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com`.
  string client_secret_version = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/SecretVersion"
    }
  ];

  // Required. The token endpoint in the OAuth provider to exchange for an
  // access token.
  string token_endpoint = 4 [(google.api.field_behavior) = REQUIRED];

  // Optional. The OAuth scopes to grant.
  repeated string scopes = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Configurations for authentication with [ID
// token](https://cloud.google.com/docs/authentication/token-types#id) generated
// from service agent.
message ServiceAgentIdTokenAuthConfig {}

// Configurations for authentication using a custom service account.
message ServiceAccountAuthConfig {
  // Required. The email address of the service account used for authentication.
  // CES uses this service account to exchange an access token and the access
  // token is then sent in the `Authorization` header of the request.
  //
  // The service account must have the
  // `roles/iam.serviceAccountTokenCreator` role granted to the
  // CES service agent
  // `service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com`.
  string service_account = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The OAuth scopes to grant. If not specified, the default scope
  // `https://www.googleapis.com/auth/cloud-platform` is used.
  repeated string scopes = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Configurations for authentication with a bearer token.
message BearerTokenConfig {
  // Required. The bearer token.
  // Must be in the format `$context.variables.<name_of_variable>`.
  string token = 1 [(google.api.field_behavior) = REQUIRED];
}

// End-user authentication configuration used for Connection calls.
// The field values must be the names of context variables in the format
// `$context.variables.<name_of_variable>`.
message EndUserAuthConfig {
  // Oauth 2.0 Authorization Code authentication configuration.
  message Oauth2AuthCodeConfig {
    // Required. Oauth token parameter name to pass through.
    // Must be in the format `$context.variables.<name_of_variable>`.
    string oauth_token = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // JWT Profile Oauth 2.0 Authorization Grant authentication configuration.
  message Oauth2JwtBearerConfig {
    // Required. Issuer parameter name to pass through.
    // Must be in the format `$context.variables.<name_of_variable>`.
    string issuer = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. Subject parameter name to pass through.
    // Must be in the format `$context.variables.<name_of_variable>`.
    string subject = 2 [(google.api.field_behavior) = REQUIRED];

    // Required. Client parameter name to pass through.
    // Must be in the format `$context.variables.<name_of_variable>`.
    string client_key = 3 [(google.api.field_behavior) = REQUIRED];
  }

  // The auth configuration.
  oneof auth_config {
    // Oauth 2.0 Authorization Code authentication.
    Oauth2AuthCodeConfig oauth2_auth_code_config = 2;

    // JWT Profile Oauth 2.0 Authorization Grant authentication.
    Oauth2JwtBearerConfig oauth2_jwt_bearer_config = 3;
  }
}

// Authentication information required for API calls.
message ApiAuthentication {
  // The auth configuration.
  oneof auth_config {
    // Optional. Config for API key auth.
    ApiKeyConfig api_key_config = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Config for OAuth.
    OAuthConfig oauth_config = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Config for ID token auth generated from CES service agent.
    ServiceAgentIdTokenAuthConfig service_agent_id_token_auth_config = 3
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Config for service account authentication.
    ServiceAccountAuthConfig service_account_auth_config = 4
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Config for bearer token auth.
    BearerTokenConfig bearer_token_config = 5
        [(google.api.field_behavior) = OPTIONAL];
  }
}