doc(common): make authentication docs easier to find

I created a page for all the authentication components. I also moved
some general overview stuff out of the `Credentials` class into the
components overview.

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<Credentials>` 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<Credentials>;
+};
+
 /**
  * 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<Credentials> MakeInsecureCredentials();
 
@@ -142,6 +110,8 @@ std::shared_ptr<Credentials> 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<Credentials> MakeGoogleDefaultCredentials();
 
@@ -154,6 +124,8 @@ std::shared_ptr<Credentials> MakeGoogleDefaultCredentials();
  *
  * @see https://cloud.google.com/docs/authentication for more information on
  *     authentication in GCP.
+ *
+ * @ingroup guac
  */
 std::shared_ptr<Credentials> MakeAccessTokenCredentials(
     std::string const& access_token,
@@ -191,6 +163,8 @@ std::shared_ptr<Credentials> 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<Credentials> MakeImpersonateServiceAccountCredentials(
     std::shared_ptr<Credentials> base_credentials,
@@ -228,30 +202,36 @@ std::shared_ptr<Credentials> 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<Credentials> MakeServiceAccountCredentials(
     std::string json_object);
 
-/// Configure the delegates for `MakeImpersonateServiceAccountCredentials()`
+/**
+ * Configure the delegates for `MakeImpersonateServiceAccountCredentials()`
+ * @ingroup guac
+ */
 struct DelegatesOption {
   using Type = std::vector<std::string>;
 };
 
-/// Configure the scopes for `MakeImpersonateServiceAccountCredentials()`
+/**
+ * Configure the scopes for `MakeImpersonateServiceAccountCredentials()`
+ * @ingroup guac
+ */
 struct ScopesOption {
   using Type = std::vector<std::string>;
 };
 
-/// 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<Credentials>;
-};
-
 /**
  * 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<AccessTokenLifetimeOption, CARootsFilePathOption,
                DelegatesOption, ScopesOption, UnifiedCredentialsOption>;

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<T>](@ref google::cloud::StatusOr) returns a value on success

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
+
+*/