diff --git a/google/cloud/credentials.h b/google/cloud/credentials.h index 05155106f0206..5de449ce317a2 100644 --- a/google/cloud/credentials.h +++ b/google/cloud/credentials.h @@ -30,66 +30,24 @@ class CredentialsVisitor; } // namespace internal /** - * The public interface for Google's Unified Auth Client (GUAC) library. - * - * The Unified Auth Client library allows C++ applications to configure - * authentication for both REST-based and gRPC-based client libraries. The - * library public interface is (intentionally) very narrow. Applications - * describe the type of authentication they want, the libraries used this - * description to initialize the internal components used in the authentication - * flows. - * - * A complete overview of authentication and authorization for Google Cloud is - * outside the scope of this reference guide. We recommend the [IAM overview] - * instead. The following brief introduction may help as you read the reference - * documentation for components related to authentication: - * - * - The `Credentials` class and the factory functions that create - * `std::shared_ptr` objects are related to *authentication*. - * That is they allow you to define what *principal* is making RPCs to GCP. - * - The problem of *authorization*, that is, what principals can perform what - * operations, is resolved by the [IAM Service] in GCP. If you need to use - * this service, the [C++ IAM client library] may be useful. Some services - * embed IAM operations in their APIs, in that case, the C++ client library - * for the service may be easier to use. - * - There are two types of "principals" in GCP. - * - **Service Accounts**: is an account for an application or compute - * workload instead of an individual end user. - * - **Google Accounts**: represents a developer, an administrator, or any - * other person who interacts with Google Cloud. - * - Most applications should use `GoogleDefaultCredentials()`. This allows your - * administrator to configure the service account used in your workload by - * setting the default service account in the GCP environment where your - * application is deployed (e.g. GCE, GKE, or Cloud Run). - * - During development, `GoogleDefaultCredentials()` uses the - * `GOOGLE_APPLICATION_CREDENTIALS` environment variable to load an - * alternative service account key. The value of this environment variable is - * the full path of a file which contains the service account key. - * - During development, if `GOOGLE_APPLICATION_CREDENTIALS` is not set then - * `GoogleDefaultCredentials()` will use the account configured via - * `gcloud auth application-default login`. This can be either a service - * account or a Google Account, such as the developer's account. - * - Neither `google auth application-default` nor - * `GOOGLE_APPLICATION_CREDENTIALS` are recommended for production workloads. - * - * @par Limitations - * The C++ GUAC library does not allow applications to create their own - * credential types. It is not possible to extend the GUAC library without - * changing internal components. If you need additional functionality please - * file a [feature request] on GitHub. Likewise, creating the components that - * implement (as opposed to *describing*) authentication flows are also - * considered implementation details. If you would like to use them in your - * own libraries please file a [feature request]. + * An opaque representation of the authentication configuration. + * + * Applications use factory functions to provide the authentication parameters + * (for example, a raw access token). The factory function encapsulates the + * parameters in an instance of this class. The interface in this class is + * (intentionally) very narrow. Only the internal components in the client + * libraries should need to access the details of this class. * * @see https://cloud.google.com/docs/authentication for more information on * authentication in GCP. * * @see https://cloud.google.com/iam for more information on the IAM Service. * - * [feature request]: https://github.com/googleapis/google-cloud-cpp/issues * [IAM overview]: https://cloud.google.com/iam/docs/overview * [IAM Service]: https://cloud.google.com/iam/docs * [C++ IAM client library]: https://googleapis.dev/cpp/google-cloud-iam/latest/ + * + * @ingroup guac */ class Credentials { public: @@ -100,6 +58,14 @@ class Credentials { virtual void dispatch(internal::CredentialsVisitor& visitor) = 0; }; +/** + * A wrapper to store credentials into an options + * @ingroup guac + */ +struct UnifiedCredentialsOption { + using Type = std::shared_ptr; +}; + /** * Create insecure (aka anonymous, aka unauthenticated) credentials. * @@ -112,6 +78,8 @@ class Credentials { * default credentials unnecessarily slows down the unit tests, and in some * CI environments the credentials may fail to load, creating confusing warnings * and sometimes even errors. + * + * @ingroup guac */ std::shared_ptr MakeInsecureCredentials(); @@ -142,6 +110,8 @@ std::shared_ptr MakeInsecureCredentials(); * [aip/4110]: https://google.aip.dev/auth/4110 * [gcloud auth application-default]: * https://cloud.google.com/sdk/gcloud/reference/auth/application-default + * + * @ingroup guac */ std::shared_ptr MakeGoogleDefaultCredentials(); @@ -154,6 +124,8 @@ std::shared_ptr MakeGoogleDefaultCredentials(); * * @see https://cloud.google.com/docs/authentication for more information on * authentication in GCP. + * + * @ingroup guac */ std::shared_ptr MakeAccessTokenCredentials( std::string const& access_token, @@ -191,6 +163,8 @@ std::shared_ptr MakeAccessTokenCredentials( * information on managing service account impersonation. * @see https://developers.google.com/identity/protocols/oauth2/scopes for * authentication scopes in Google Cloud Platform. + * + * @ingroup guac */ std::shared_ptr MakeImpersonateServiceAccountCredentials( std::shared_ptr base_credentials, @@ -228,30 +202,36 @@ std::shared_ptr MakeImpersonateServiceAccountCredentials( * [service account]: https://cloud.google.com/iam/docs/overview#service_account * [service account key]: * https://cloud.google.com/iam/docs/creating-managing-service-account-keys#iam-service-account-keys-create-cpp + * + * @ingroup guac */ std::shared_ptr MakeServiceAccountCredentials( std::string json_object); -/// Configure the delegates for `MakeImpersonateServiceAccountCredentials()` +/** + * Configure the delegates for `MakeImpersonateServiceAccountCredentials()` + * @ingroup guac + */ struct DelegatesOption { using Type = std::vector; }; -/// Configure the scopes for `MakeImpersonateServiceAccountCredentials()` +/** + * Configure the scopes for `MakeImpersonateServiceAccountCredentials()` + * @ingroup guac + */ struct ScopesOption { using Type = std::vector; }; -/// Configure the access token lifetime +/** + * Configure the access token lifetime + * @ingroup guac + */ struct AccessTokenLifetimeOption { using Type = std::chrono::seconds; }; -/// A wrapper to store credentials into an options -struct UnifiedCredentialsOption { - using Type = std::shared_ptr; -}; - /** * Configures a custom CA (Certificates Authority) certificates file. * @@ -290,12 +270,14 @@ struct UnifiedCredentialsOption { * [PEM format]: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail * [grpc::SslCredentialsOptions]: * https://grpc.github.io/grpc/cpp/structgrpc_1_1_ssl_credentials_options.html + * + * @ingroup guac */ struct CARootsFilePathOption { using Type = std::string; }; -/// A list of GUAC options. +/// A list of options related to authentication. using UnifiedCredentialsOptionList = OptionList; diff --git a/google/cloud/doc/common-main.dox b/google/cloud/doc/common-main.dox index 74c3fc128a81b..1c059dd4df967 100644 --- a/google/cloud/doc/common-main.dox +++ b/google/cloud/doc/common-main.dox @@ -6,6 +6,11 @@ This library contains common components shared by all the Google Cloud C++ Client Libraries. Including: +- [Credentials](@ref google::cloud::Credentials) are used to configure + authentication in the client libraries. See @ref guac for more + details on authentication. +- [Options](@ref google::cloud::Options) are used to override the client library + default configuration. - [Status](@ref google::cloud::Status) error codes and details from an operation. - [StatusOr](@ref google::cloud::StatusOr) returns a value on success diff --git a/google/cloud/doc/guac.dox b/google/cloud/doc/guac.dox new file mode 100644 index 0000000000000..546c64373b635 --- /dev/null +++ b/google/cloud/doc/guac.dox @@ -0,0 +1,73 @@ +/*! +@defgroup guac Authentication Components + +Most services in Google Cloud Platform requires the client to authenticate the +requests. Notable exceptions include public buckets in GCS and public data +sets in BigQuery. The C++ client libraries are automatically configured +to use "Google Default Credentials", some applications may need to override this +default. The functions and classes related to change the authentication +configuration are documented here. + +This document is not a general introduction to authentication for Google Cloud +Platform. For readers seeking such an introduction we recommend +[Authentication at Google] as a good starting point. Covering authorization in +any detail is also out of scope. We recommend reading the [IAM overview] if that +is of interest. + +In most cases applications can control the [principal][principal-overview] +used by the client libraries without having to change any code. By default the +client libraries use [Application Default Credentials] which can be configured +via environment variables, the `gcloud` CLI, or by changing the service account +associated with your deployment environment (GCE, Cloud Run, GKE, etc.) + +## General Concepts + +As mentioned complete overview of authentication and authorization for Google +Cloud is outside the scope of this document. The following brief introduction +may help as you read the reference documentation for components related to +authentication. + +Google Cloud Platform largely uses [OAuth2] access tokens for authentication. +There are multiple ways to create such tokens. For example, when running on +GCE the VM has access to a metadata server that can create these tokens for +any application running on the VM. As another example, you can download a +[service account keyfile] and the C++ client libraries will create access +tokens using the contents of this file. + +Access tokens usually expire in about an hour. The client libraries +automatically refresh these tokens when needed. The only exception is +`MakeAccessTokenCredentials()` where the application provides the access token. + +## Development Workstations + +During development the most common configuration to use Application Default +Credentials are: + +1. Use the `gcloud auth application-default` to authentication using the + developer's account for authentication. +1. Set `GOOGLE_APPLICATION_CREDENTIALS` environment variable to load a service + account key. The value of this environment variable is the full path of a + file which contains the service account key. +1. If you are using a GCE instance as your development environment, simply + use the service account of the GCE machine to access GCP services. + +## Limitations + +The C++ authentication components do not allow applications to create their +own credential types. It is not possible to extend the C++ libraries without +changing internal components. If you need additional functionality please +file a [feature request] on GitHub. Likewise, creating the components that +implement (as opposed to *describing*) authentication flows are also +considered implementation details. If you would like to use them in your +own libraries please file a [feature request]. We cannot promise that we will +be able to satisfy these requests, but we will give them full consideration. + +[principal-overview]: https://cloud.google.com/iam/docs/overview#how_cloud_iam_works +[Authentication at Google]: https://cloud.google.com/docs/authentication +[IAM overview]: https://cloud.google.com/iam/docs/overview +[Application Default Credentials]: https://cloud.google.com/docs/authentication/application-default-credentials +[Oauth2]: https://oauth.net/2/ +[service account keyfile]: https://cloud.google.com/iam/docs/creating-managing-service-account-keys +[feature request]: https://github.com/googleapis/google-cloud-cpp/issues + +*/