Google Cloud C++ Client  1.42.0
C++ Client Library for Google Cloud Platform
credentials.h
Go to the documentation of this file.
1 // Copyright 2021 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_CREDENTIALS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_CREDENTIALS_H
17 
18 #include "google/cloud/options.h"
19 #include "google/cloud/version.h"
20 #include <chrono>
21 #include <memory>
22 #include <string>
23 #include <vector>
24 
25 namespace google {
26 namespace cloud {
28 namespace internal {
29 class CredentialsVisitor;
30 } // namespace internal
31 
32 /**
33  * The public interface for Google's Unified Auth Client (GUAC) library.
34  *
35  * The Unified Auth Client library allows C++ applications to configure
36  * authentication for both REST-based and gRPC-based client libraries. The
37  * library public interface is (intentionally) very narrow. Applications
38  * describe the type of authentication they want, the libraries used this
39  * description to initialize the internal components used in the authentication
40  * flows.
41  *
42  * @par Limitations
43  * The C++ GUAC library does not allow applications to create their own
44  * credential types. It is not possible to extend the GUAC library without
45  * changing internal components. If you need additional functionality please
46  * file a [feature request] on GitHub. Likewise, creating the components that
47  * implement (as opposed to *describing*) authentication flows are also
48  * considered implementation details. If you would like to use them in your
49  * own libraries please file a [feature request].
50  *
51  * @see https://cloud.google.com/docs/authentication for more information on
52  * authentication in GCP.
53  *
54  * [feature request]: https://github.com/googleapis/google-cloud-cpp/issues
55  */
56 class Credentials {
57  public:
58  virtual ~Credentials() = 0;
59 
60  private:
61  friend class internal::CredentialsVisitor;
62  virtual void dispatch(internal::CredentialsVisitor& visitor) = 0;
63 };
64 
65 /**
66  * Create insecure (aka anonymous, aka unauthenticated) credentials.
67  *
68  * These credentials are mostly intended for testing. Integration tests running
69  * against an emulator do not need to authenticate. In fact, it may be
70  * impossible to connect to an emulator using SSL/TLS because the emulators
71  * typically run without secure communication.
72  *
73  * In addition, unit tests may benefit from using these credentials: loading the
74  * default credentials unnecessarily slows down the unit tests, and in some
75  * CI environments the credentials may fail to load, creating confusing warnings
76  * and sometimes even errors.
77  */
79 
80 /**
81  * Creates the default credentials.
82  *
83  * These are the most commonly used credentials, and are expected to meet the
84  * needs of most applications. The Google Default Credentials conform to
85  * [aip/4110]. Consider using these credentials when:
86  *
87  * - Your application is deployed to a GCP environment such as GCE, GKE, or
88  * Cloud Run. Each of these deployment environments provides a default service
89  * account to the application, and offers mechanisms to change the default
90  * credentials without any code changes to your application.
91  * - You are testing or developing the application on a workstation (physical or
92  * virtual). These credentials will use your preferences as set with
93  * [gcloud auth application-default]. These preferences can be your own GCP
94  * user credentials, or some service account.
95  * - Regardless of where your application is running, you can use the
96  * `GOOGLE_APPLICATION_CREDENTIALS` environment variable to override the
97  * defaults. This environment variable should point to a file containing a
98  * service account key file, or a JSON object describing your user
99  * credentials.
100  *
101  * @see https://cloud.google.com/docs/authentication for more information on
102  * authentication in GCP.
103  *
104  * [aip/4110]: https://google.aip.dev/auth/4110
105  * [gcloud auth application-default]:
106  * https://cloud.google.com/sdk/gcloud/reference/auth/application-default
107  */
109 
110 /**
111  * Creates credentials with a fixed access token.
112  *
113  * These credentials are useful when using an out-of-band mechanism to fetch
114  * access tokens. Note that access tokens are time limited, you will need to
115  * manually refresh the tokens created by the
116  *
117  * @see https://cloud.google.com/docs/authentication for more information on
118  * authentication in GCP.
119  */
121  std::string const& access_token,
122  std::chrono::system_clock::time_point expiration);
123 
124 /**
125  * Creates credentials for service account impersonation.
126  *
127  * Service account impersonation allows one account (user or service account)
128  * to *act as* a second account. This can be useful in multi-tenant services,
129  * where the service may perform some actions with an specific account
130  * associated with a tenant. The tenant can grant or restrict permissions to
131  * this tenant account.
132  *
133  * When using service account impersonation is important to distinguish between
134  * the credentials used to *obtain* the target account credentials (the
135  * @p base_credentials) parameter, and the credentials representing the
136  * @p target_service_account.
137  *
138  * Use `AccessTokenLifetimeOption` to configure the maximum lifetime of the
139  * obtained credentials. The default is 1h (3600s), see [IAM quotas] for the
140  * limits set by the platform and how to override them.
141  *
142  * Use `DelegatesOption` to configure a sequence of intermediate service
143  * account, each of which has permissions to impersonate the next and the
144  * last one has permissions to impersonate @p target_service_account.
145  *
146  * Use `ScopesOption` to restrict the authentication scope for the obtained
147  * credentials. See below for possible values.
148  *
149  * [IAM quotas]: https://cloud.google.com/iam/quotas
150  * @see https://cloud.google.com/docs/authentication for more information on
151  * authentication in GCP.
152  * @see https://cloud.google.com/iam/docs/impersonating-service-accounts for
153  * information on managing service account impersonation.
154  * @see https://developers.google.com/identity/protocols/oauth2/scopes for
155  * authentication scopes in Google Cloud Platform.
156  */
158  std::shared_ptr<Credentials> base_credentials,
159  std::string target_service_account, Options opts = {});
160 
161 /**
162  * Creates service account credentials from a JSON object in string form.
163  *
164  * The @p json_object is expected to be in the format described by [aip/4112].
165  * Such an object contains the identity of a service account, as well as a
166  * private key that can be used to sign tokens, showing the caller was holding
167  * the private key.
168  *
169  * In GCP one can create several "keys" for each service account, and these
170  * keys are downloaded as a JSON "key file". The contents of such a file are
171  * in the format required by this function. Remember that key files and their
172  * contents should be treated as any other secret with security implications,
173  * think of them as passwords (because they are!), don't store them or output
174  * them where unauthorized persons may read them.
175  *
176  * As stated above, most applications should probably use default credentials,
177  * maybe pointing them to a file with these contents. Using this function may be
178  * useful when the json object is obtained from a Cloud Secret Manager or a
179  * similar service.
180  *
181  * [aip/4112]: https://google.aip.dev/auth/4112
182  */
184  std::string json_object);
185 
186 /// Configure the delegates for `MakeImpersonateServiceAccountCredentials()`
188  using Type = std::vector<std::string>;
189 };
190 
191 /// Configure the scopes for `MakeImpersonateServiceAccountCredentials()`
192 struct ScopesOption {
193  using Type = std::vector<std::string>;
194 };
195 
196 /// Configure the access token lifetime
198  using Type = std::chrono::seconds;
199 };
200 
201 /// A wrapper to store credentials into an options
203  using Type = std::shared_ptr<Credentials>;
204 };
205 
206 /**
207  * Configures a custom CA (Certificates Authority) certificates file.
208  *
209  * Most applications should use the system's root certificates and should avoid
210  * setting this option unnecessarily. A common exception to this recommendation
211  * are containerized applications. These often deploy without system's root
212  * certificates and need to explicitly configure a root of trust.
213  *
214  * The value of this option should be the name of a file in [PEM format].
215  * Consult your security team and/or system administrator for the contents of
216  * this file. Be aware of the security implications of adding new CA
217  * certificates to this file. Only use trustworthy sources for the CA
218  * certificates.
219  *
220  * For REST-based libraries this configures the [CAINFO option] in libcurl.
221  * These are used for all credentials that require authentication, including the
222  * default credentials.
223  *
224  * For gRPC-based libraries this configures the `pem_roots_cert` parameter in
225  * [grpc::SslCredentialsOptions].
226  *
227  * @warning gRPC does not have a programmatic mechanism to set the CA
228  * certificates for the default credentials. This option only has no effect
229  * with `MakeGoogleDefaultCredentials()`, or
230  * `MakeServiceAccountCredentials()`.
231  * Consider using the `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` environment
232  * variable in these cases.
233  *
234  * @note CA certificates can be revoked or expire, plan for updates in your
235  * deployment.
236  *
237  * @see https://en.wikipedia.org/wiki/Certificate_authority for a general
238  * introduction to SSL certificate authorities.
239  *
240  * [CAINFO Option]: https://curl.se/libcurl/c/CURLOPT_CAINFO.html
241  * [PEM format]: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
242  * [grpc::SslCredentialsOptions]:
243  * https://grpc.github.io/grpc/cpp/structgrpc_1_1_ssl_credentials_options.html
244  */
246  using Type = std::string;
247 };
248 
249 namespace internal {
250 
251 /**
252  * Use an insecure channel for AccessToken authentication.
253  *
254  * This is useful when testing against emulators, where it is impossible to
255  * create a secure channel.
256  */
257 struct UseInsecureChannelOption {
258  using Type = bool;
259 };
260 
261 } // namespace internal
263 } // namespace cloud
264 } // namespace google
265 
266 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_CREDENTIALS_H