3 * Copyright 2015 gRPC authors.
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
19 #ifndef GRPCPP_SECURITY_CREDENTIALS_H
20 #define GRPCPP_SECURITY_CREDENTIALS_H
26 #include <grpc/grpc_security_constants.h>
27 #include <grpcpp/channel.h>
28 #include <grpcpp/impl/codegen/client_interceptor.h>
29 #include <grpcpp/impl/codegen/grpc_library.h>
30 #include <grpcpp/security/auth_context.h>
31 #include <grpcpp/security/tls_credentials_options.h>
32 #include <grpcpp/support/channel_arguments.h>
33 #include <grpcpp/support/status.h>
34 #include <grpcpp/support/string_ref.h>
39 class CallCredentials;
40 class SecureCallCredentials;
41 class SecureChannelCredentials;
42 class ChannelCredentials;
44 std::shared_ptr<Channel> CreateCustomChannel(
45 const grpc::string& target,
46 const std::shared_ptr<grpc::ChannelCredentials>& creds,
47 const grpc::ChannelArguments& args);
49 namespace experimental {
50 std::shared_ptr<grpc::Channel> CreateCustomChannelWithInterceptors(
51 const grpc::string& target,
52 const std::shared_ptr<grpc::ChannelCredentials>& creds,
53 const grpc::ChannelArguments& args,
55 std::unique_ptr<grpc::experimental::ClientInterceptorFactoryInterface>>
56 interceptor_creators);
58 /// Builds XDS Credentials.
59 std::shared_ptr<ChannelCredentials> XdsCredentials(
60 const std::shared_ptr<ChannelCredentials>& fallback_creds);
61 } // namespace experimental
63 /// A channel credentials object encapsulates all the state needed by a client
64 /// to authenticate with a server for a given channel.
65 /// It can make various assertions, e.g., about the client’s identity, role
66 /// for all the calls on that channel.
68 /// \see https://grpc.io/docs/guides/auth.html
69 class ChannelCredentials : private grpc::GrpcLibraryCodegen {
72 ~ChannelCredentials() override;
75 friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
76 const std::shared_ptr<ChannelCredentials>& channel_creds,
77 const std::shared_ptr<CallCredentials>& call_creds);
79 // TODO(yashykt): We need this friend declaration mainly for access to
80 // AsSecureCredentials(). Once we are able to remove insecure builds from gRPC
81 // (and also internal dependencies on the indirect method of creating a
82 // channel through credentials), we would be able to remove this.
83 friend std::shared_ptr<ChannelCredentials> grpc::experimental::XdsCredentials(
84 const std::shared_ptr<ChannelCredentials>& fallback_creds);
86 virtual SecureChannelCredentials* AsSecureCredentials() = 0;
89 friend std::shared_ptr<grpc::Channel> CreateCustomChannel(
90 const grpc::string& target,
91 const std::shared_ptr<grpc::ChannelCredentials>& creds,
92 const grpc::ChannelArguments& args);
94 friend std::shared_ptr<grpc::Channel>
95 grpc::experimental::CreateCustomChannelWithInterceptors(
96 const grpc::string& target,
97 const std::shared_ptr<grpc::ChannelCredentials>& creds,
98 const grpc::ChannelArguments& args,
99 std::vector<std::unique_ptr<
100 grpc::experimental::ClientInterceptorFactoryInterface>>
101 interceptor_creators);
103 virtual std::shared_ptr<Channel> CreateChannelImpl(
104 const grpc::string& target, const ChannelArguments& args) = 0;
106 // This function should have been a pure virtual function, but it is
107 // implemented as a virtual function so that it does not break API.
108 virtual std::shared_ptr<Channel> CreateChannelWithInterceptors(
109 const grpc::string& /*target*/, const ChannelArguments& /*args*/,
110 std::vector<std::unique_ptr<
111 grpc::experimental::ClientInterceptorFactoryInterface>>
112 /*interceptor_creators*/) {
116 // TODO(yashkt): This is a hack that is needed since InsecureCredentials can
117 // not use grpc_channel_credentials internally and should be removed after
118 // insecure builds are removed from gRPC.
119 virtual bool IsInsecure() const { return false; }
122 /// A call credentials object encapsulates the state needed by a client to
123 /// authenticate with a server for a given call on a channel.
125 /// \see https://grpc.io/docs/guides/auth.html
126 class CallCredentials : private grpc::GrpcLibraryCodegen {
129 ~CallCredentials() override;
131 /// Apply this instance's credentials to \a call.
132 virtual bool ApplyToCall(grpc_call* call) = 0;
133 virtual grpc::string DebugString() {
134 return "CallCredentials did not provide a debug string";
138 friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
139 const std::shared_ptr<ChannelCredentials>& channel_creds,
140 const std::shared_ptr<CallCredentials>& call_creds);
142 friend std::shared_ptr<CallCredentials> CompositeCallCredentials(
143 const std::shared_ptr<CallCredentials>& creds1,
144 const std::shared_ptr<CallCredentials>& creds2);
146 virtual SecureCallCredentials* AsSecureCredentials() = 0;
149 /// Options used to build SslCredentials.
150 struct SslCredentialsOptions {
151 /// The buffer containing the PEM encoding of the server root certificates. If
152 /// this parameter is empty, the default roots will be used. The default
153 /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
154 /// environment variable pointing to a file on the file system containing the
156 grpc::string pem_root_certs;
158 /// The buffer containing the PEM encoding of the client's private key. This
159 /// parameter can be empty if the client does not have a private key.
160 grpc::string pem_private_key;
162 /// The buffer containing the PEM encoding of the client's certificate chain.
163 /// This parameter can be empty if the client does not have a certificate
165 grpc::string pem_cert_chain;
168 // Factories for building different types of Credentials The functions may
169 // return empty shared_ptr when credentials cannot be created. If a
170 // Credentials pointer is returned, it can still be invalid when used to create
171 // a channel. A lame channel will be created then and all rpcs will fail on it.
173 /// Builds credentials with reasonable defaults.
175 /// \warning Only use these credentials when connecting to a Google endpoint.
176 /// Using these credentials to connect to any other service may result in this
177 /// service being able to impersonate your client for requests to Google
179 std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials();
181 /// Builds SSL Credentials given SSL specific options
182 std::shared_ptr<ChannelCredentials> SslCredentials(
183 const SslCredentialsOptions& options);
185 /// Builds credentials for use when running in GCE
187 /// \warning Only use these credentials when connecting to a Google endpoint.
188 /// Using these credentials to connect to any other service may result in this
189 /// service being able to impersonate your client for requests to Google
191 std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials();
193 constexpr long kMaxAuthTokenLifetimeSecs = 3600;
195 /// Builds Service Account JWT Access credentials.
196 /// json_key is the JSON key string containing the client's private key.
197 /// token_lifetime_seconds is the lifetime in seconds of each Json Web Token
198 /// (JWT) created with this credentials. It should not exceed
199 /// \a kMaxAuthTokenLifetimeSecs or will be cropped to this value.
200 std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials(
201 const grpc::string& json_key,
202 long token_lifetime_seconds = kMaxAuthTokenLifetimeSecs);
204 /// Builds refresh token credentials.
205 /// json_refresh_token is the JSON string containing the refresh token along
206 /// with a client_id and client_secret.
208 /// \warning Only use these credentials when connecting to a Google endpoint.
209 /// Using these credentials to connect to any other service may result in this
210 /// service being able to impersonate your client for requests to Google
212 std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials(
213 const grpc::string& json_refresh_token);
215 /// Builds access token credentials.
216 /// access_token is an oauth2 access token that was fetched using an out of band
219 /// \warning Only use these credentials when connecting to a Google endpoint.
220 /// Using these credentials to connect to any other service may result in this
221 /// service being able to impersonate your client for requests to Google
223 std::shared_ptr<CallCredentials> AccessTokenCredentials(
224 const grpc::string& access_token);
226 /// Builds IAM credentials.
228 /// \warning Only use these credentials when connecting to a Google endpoint.
229 /// Using these credentials to connect to any other service may result in this
230 /// service being able to impersonate your client for requests to Google
232 std::shared_ptr<CallCredentials> GoogleIAMCredentials(
233 const grpc::string& authorization_token,
234 const grpc::string& authority_selector);
236 /// Combines a channel credentials and a call credentials into a composite
237 /// channel credentials.
238 std::shared_ptr<ChannelCredentials> CompositeChannelCredentials(
239 const std::shared_ptr<ChannelCredentials>& channel_creds,
240 const std::shared_ptr<CallCredentials>& call_creds);
242 /// Combines two call credentials objects into a composite call credentials.
243 std::shared_ptr<CallCredentials> CompositeCallCredentials(
244 const std::shared_ptr<CallCredentials>& creds1,
245 const std::shared_ptr<CallCredentials>& creds2);
247 /// Credentials for an unencrypted, unauthenticated channel
248 std::shared_ptr<ChannelCredentials> InsecureChannelCredentials();
250 /// User defined metadata credentials.
251 class MetadataCredentialsPlugin {
253 virtual ~MetadataCredentialsPlugin() {}
255 /// If this method returns true, the Process function will be scheduled in
256 /// a different thread from the one processing the call.
257 virtual bool IsBlocking() const { return true; }
259 /// Type of credentials this plugin is implementing.
260 virtual const char* GetType() const { return ""; }
262 /// Gets the auth metatada produced by this plugin.
263 /// The fully qualified method name is:
264 /// service_url + "/" + method_name.
265 /// The channel_auth_context contains (among other things), the identity of
267 virtual grpc::Status GetMetadata(
268 grpc::string_ref service_url, grpc::string_ref method_name,
269 const grpc::AuthContext& channel_auth_context,
270 std::multimap<grpc::string, grpc::string>* metadata) = 0;
272 virtual grpc::string DebugString() {
273 return "MetadataCredentialsPlugin did not provide a debug string";
277 std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
278 std::unique_ptr<MetadataCredentialsPlugin> plugin);
280 /// Builds External Account credentials.
281 /// json_string is the JSON string containing the credentials options.
282 /// scopes contains the scopes to be binded with the credentials.
283 std::shared_ptr<CallCredentials> ExternalAccountCredentials(
284 const grpc::string& json_string, const std::vector<grpc::string>& scopes);
286 namespace experimental {
288 /// Options for creating STS Oauth Token Exchange credentials following the IETF
289 /// draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16.
290 /// Optional fields may be set to empty string. It is the responsibility of the
291 /// caller to ensure that the subject and actor tokens are refreshed on disk at
292 /// the specified paths.
293 struct StsCredentialsOptions {
294 grpc::string token_exchange_service_uri; // Required.
295 grpc::string resource; // Optional.
296 grpc::string audience; // Optional.
297 grpc::string scope; // Optional.
298 grpc::string requested_token_type; // Optional.
299 grpc::string subject_token_path; // Required.
300 grpc::string subject_token_type; // Required.
301 grpc::string actor_token_path; // Optional.
302 grpc::string actor_token_type; // Optional.
305 grpc::Status StsCredentialsOptionsFromJson(const std::string& json_string,
306 StsCredentialsOptions* options);
308 /// Creates STS credentials options from the $STS_CREDENTIALS environment
309 /// variable. This environment variable points to the path of a JSON file
310 /// comforming to the schema described above.
311 grpc::Status StsCredentialsOptionsFromEnv(StsCredentialsOptions* options);
313 std::shared_ptr<CallCredentials> StsCredentials(
314 const StsCredentialsOptions& options);
316 std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin(
317 std::unique_ptr<MetadataCredentialsPlugin> plugin,
318 grpc_security_level min_security_level);
320 /// Options used to build AltsCredentials.
321 struct AltsCredentialsOptions {
322 /// service accounts of target endpoint that will be acceptable
323 /// by the client. If service accounts are provided and none of them matches
324 /// that of the server, authentication will fail.
325 std::vector<grpc::string> target_service_accounts;
328 /// Builds ALTS Credentials given ALTS specific options
329 std::shared_ptr<ChannelCredentials> AltsCredentials(
330 const AltsCredentialsOptions& options);
332 /// Builds Local Credentials.
333 std::shared_ptr<ChannelCredentials> LocalCredentials(
334 grpc_local_connect_type type);
336 /// Builds TLS Credentials given TLS options.
337 std::shared_ptr<ChannelCredentials> TlsCredentials(
338 const TlsChannelCredentialsOptions& options);
340 } // namespace experimental
343 #endif // GRPCPP_SECURITY_CREDENTIALS_H