1 // 2 // 3 // Copyright 2015 gRPC authors. 4 // 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 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 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. 16 // 17 // 18 19 #ifndef GRPCPP_SECURITY_CREDENTIALS_H 20 #define GRPCPP_SECURITY_CREDENTIALS_H 21 22 #include <map> 23 #include <memory> 24 #include <vector> 25 26 #include <grpc/grpc_security_constants.h> 27 #include <grpcpp/channel.h> 28 #include <grpcpp/impl/grpc_library.h> 29 #include <grpcpp/security/auth_context.h> 30 #include <grpcpp/security/tls_credentials_options.h> 31 #include <grpcpp/support/channel_arguments.h> 32 #include <grpcpp/support/client_interceptor.h> 33 #include <grpcpp/support/status.h> 34 #include <grpcpp/support/string_ref.h> 35 36 struct grpc_call; 37 38 namespace grpc { 39 class CallCredentials; 40 class ChannelCredentials; 41 namespace testing { 42 std::string GetOauth2AccessToken(); 43 } 44 45 std::shared_ptr<Channel> CreateCustomChannel( 46 const grpc::string& target, 47 const std::shared_ptr<grpc::ChannelCredentials>& creds, 48 const grpc::ChannelArguments& args); 49 50 namespace experimental { 51 std::shared_ptr<grpc::Channel> CreateCustomChannelWithInterceptors( 52 const grpc::string& target, 53 const std::shared_ptr<grpc::ChannelCredentials>& creds, 54 const grpc::ChannelArguments& args, 55 std::vector< 56 std::unique_ptr<grpc::experimental::ClientInterceptorFactoryInterface>> 57 interceptor_creators); 58 } // namespace experimental 59 60 /// Builds XDS Credentials. 61 std::shared_ptr<ChannelCredentials> XdsCredentials( 62 const std::shared_ptr<ChannelCredentials>& fallback_creds); 63 64 /// A channel credentials object encapsulates all the state needed by a client 65 /// to authenticate with a server for a given channel. 66 /// It can make various assertions, e.g., about the client’s identity, role 67 /// for all the calls on that channel. 68 /// 69 /// \see https://grpc.io/docs/guides/auth.html 70 class ChannelCredentials : private grpc::internal::GrpcLibrary { 71 public: 72 ~ChannelCredentials() override; 73 74 protected: 75 explicit ChannelCredentials(grpc_channel_credentials* creds); 76 c_creds()77 grpc_channel_credentials* c_creds() { return c_creds_; } 78 79 private: 80 friend std::shared_ptr<grpc::Channel> CreateCustomChannel( 81 const grpc::string& target, 82 const std::shared_ptr<grpc::ChannelCredentials>& creds, 83 const grpc::ChannelArguments& args); 84 friend std::shared_ptr<grpc::Channel> 85 grpc::experimental::CreateCustomChannelWithInterceptors( 86 const grpc::string& target, 87 const std::shared_ptr<grpc::ChannelCredentials>& creds, 88 const grpc::ChannelArguments& args, 89 std::vector<std::unique_ptr< 90 grpc::experimental::ClientInterceptorFactoryInterface>> 91 interceptor_creators); 92 friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials( 93 const std::shared_ptr<ChannelCredentials>& channel_creds, 94 const std::shared_ptr<CallCredentials>& call_creds); 95 friend class XdsChannelCredentialsImpl; 96 CreateChannelImpl(const grpc::string & target,const ChannelArguments & args)97 virtual std::shared_ptr<Channel> CreateChannelImpl( 98 const grpc::string& target, const ChannelArguments& args) { 99 return CreateChannelWithInterceptors(target, args, {}); 100 } 101 102 virtual std::shared_ptr<Channel> CreateChannelWithInterceptors( 103 const grpc::string& target, const ChannelArguments& args, 104 std::vector<std::unique_ptr< 105 grpc::experimental::ClientInterceptorFactoryInterface>> 106 interceptor_creators); 107 108 grpc_channel_credentials* const c_creds_; 109 }; 110 111 /// A call credentials object encapsulates the state needed by a client to 112 /// authenticate with a server for a given call on a channel. 113 /// 114 /// \see https://grpc.io/docs/guides/auth.html 115 class CallCredentials : private grpc::internal::GrpcLibrary { 116 public: 117 ~CallCredentials() override; 118 119 /// Apply this instance's credentials to \a call. 120 bool ApplyToCall(grpc_call* call); 121 122 grpc::string DebugString(); 123 124 protected: 125 explicit CallCredentials(grpc_call_credentials* creds); 126 127 private: 128 friend std::shared_ptr<ChannelCredentials> CompositeChannelCredentials( 129 const std::shared_ptr<ChannelCredentials>& channel_creds, 130 const std::shared_ptr<CallCredentials>& call_creds); 131 friend class CompositeCallCredentialsImpl; 132 friend std::string grpc::testing::GetOauth2AccessToken(); 133 134 grpc_call_credentials* c_creds_ = nullptr; 135 }; 136 137 /// Options used to build SslCredentials. 138 struct SslCredentialsOptions { 139 /// The buffer containing the PEM encoding of the server root certificates. If 140 /// this parameter is empty, the default roots will be used. The default 141 /// roots can be overridden using the \a GRPC_DEFAULT_SSL_ROOTS_FILE_PATH 142 /// environment variable pointing to a file on the file system containing the 143 /// roots. 144 grpc::string pem_root_certs; 145 146 /// The buffer containing the PEM encoding of the client's private key. This 147 /// parameter can be empty if the client does not have a private key. 148 grpc::string pem_private_key; 149 150 /// The buffer containing the PEM encoding of the client's certificate chain. 151 /// This parameter can be empty if the client does not have a certificate 152 /// chain. 153 grpc::string pem_cert_chain; 154 }; 155 156 // Factories for building different types of Credentials The functions may 157 // return empty shared_ptr when credentials cannot be created. If a 158 // Credentials pointer is returned, it can still be invalid when used to create 159 // a channel. A lame channel will be created then and all rpcs will fail on it. 160 161 /// Builds credentials with reasonable defaults. 162 /// 163 /// \warning Only use these credentials when connecting to a Google endpoint. 164 /// Using these credentials to connect to any other service may result in this 165 /// service being able to impersonate your client for requests to Google 166 /// services. 167 std::shared_ptr<ChannelCredentials> GoogleDefaultCredentials(); 168 169 /// Builds SSL Credentials given SSL specific options 170 std::shared_ptr<ChannelCredentials> SslCredentials( 171 const SslCredentialsOptions& options); 172 173 /// Builds credentials for use when running in GCE 174 /// 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 178 /// services. 179 std::shared_ptr<CallCredentials> GoogleComputeEngineCredentials(); 180 181 constexpr long kMaxAuthTokenLifetimeSecs = 3600; 182 183 /// Builds Service Account JWT Access credentials. 184 /// json_key is the JSON key string containing the client's private key. 185 /// token_lifetime_seconds is the lifetime in seconds of each Json Web Token 186 /// (JWT) created with this credentials. It should not exceed 187 /// \a kMaxAuthTokenLifetimeSecs or will be cropped to this value. 188 std::shared_ptr<CallCredentials> ServiceAccountJWTAccessCredentials( 189 const grpc::string& json_key, 190 long token_lifetime_seconds = kMaxAuthTokenLifetimeSecs); 191 192 /// Builds refresh token credentials. 193 /// json_refresh_token is the JSON string containing the refresh token along 194 /// with a client_id and client_secret. 195 /// 196 /// \warning Only use these credentials when connecting to a Google endpoint. 197 /// Using these credentials to connect to any other service may result in this 198 /// service being able to impersonate your client for requests to Google 199 /// services. 200 std::shared_ptr<CallCredentials> GoogleRefreshTokenCredentials( 201 const grpc::string& json_refresh_token); 202 203 /// Builds access token credentials. 204 /// access_token is an oauth2 access token that was fetched using an out of band 205 /// mechanism. 206 /// 207 /// \warning Only use these credentials when connecting to a Google endpoint. 208 /// Using these credentials to connect to any other service may result in this 209 /// service being able to impersonate your client for requests to Google 210 /// services. 211 std::shared_ptr<CallCredentials> AccessTokenCredentials( 212 const grpc::string& access_token); 213 214 /// Builds IAM credentials. 215 /// 216 /// \warning Only use these credentials when connecting to a Google endpoint. 217 /// Using these credentials to connect to any other service may result in this 218 /// service being able to impersonate your client for requests to Google 219 /// services. 220 std::shared_ptr<CallCredentials> GoogleIAMCredentials( 221 const grpc::string& authorization_token, 222 const grpc::string& authority_selector); 223 224 /// Combines a channel credentials and a call credentials into a composite 225 /// channel credentials. 226 std::shared_ptr<ChannelCredentials> CompositeChannelCredentials( 227 const std::shared_ptr<ChannelCredentials>& channel_creds, 228 const std::shared_ptr<CallCredentials>& call_creds); 229 230 /// Combines two call credentials objects into a composite call credentials. 231 std::shared_ptr<CallCredentials> CompositeCallCredentials( 232 const std::shared_ptr<CallCredentials>& creds1, 233 const std::shared_ptr<CallCredentials>& creds2); 234 235 /// Credentials for an unencrypted, unauthenticated channel 236 std::shared_ptr<ChannelCredentials> InsecureChannelCredentials(); 237 238 /// User defined metadata credentials. 239 class MetadataCredentialsPlugin { 240 public: ~MetadataCredentialsPlugin()241 virtual ~MetadataCredentialsPlugin() {} 242 243 /// If this method returns true, the Process function will be scheduled in 244 /// a different thread from the one processing the call. IsBlocking()245 virtual bool IsBlocking() const { return true; } 246 247 /// Type of credentials this plugin is implementing. GetType()248 virtual const char* GetType() const { return ""; } 249 250 /// Gets the auth metatada produced by this plugin. 251 /// The fully qualified method name is: 252 /// service_url + "/" + method_name. 253 /// The channel_auth_context contains (among other things), the identity of 254 /// the server. 255 virtual grpc::Status GetMetadata( 256 grpc::string_ref service_url, grpc::string_ref method_name, 257 const grpc::AuthContext& channel_auth_context, 258 std::multimap<grpc::string, grpc::string>* metadata) = 0; 259 DebugString()260 virtual grpc::string DebugString() { 261 return "MetadataCredentialsPlugin did not provide a debug string"; 262 } 263 }; 264 265 std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin( 266 std::unique_ptr<MetadataCredentialsPlugin> plugin); 267 268 /// Builds External Account credentials. 269 /// json_string is the JSON string containing the credentials options. 270 /// scopes contains the scopes to be binded with the credentials. 271 std::shared_ptr<CallCredentials> ExternalAccountCredentials( 272 const grpc::string& json_string, const std::vector<grpc::string>& scopes); 273 274 namespace experimental { 275 276 /// Options for creating STS Oauth Token Exchange credentials following the IETF 277 /// draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-16. 278 /// Optional fields may be set to empty string. It is the responsibility of the 279 /// caller to ensure that the subject and actor tokens are refreshed on disk at 280 /// the specified paths. 281 struct StsCredentialsOptions { 282 grpc::string token_exchange_service_uri; // Required. 283 grpc::string resource; // Optional. 284 grpc::string audience; // Optional. 285 grpc::string scope; // Optional. 286 grpc::string requested_token_type; // Optional. 287 grpc::string subject_token_path; // Required. 288 grpc::string subject_token_type; // Required. 289 grpc::string actor_token_path; // Optional. 290 grpc::string actor_token_type; // Optional. 291 }; 292 293 grpc::Status StsCredentialsOptionsFromJson(const std::string& json_string, 294 StsCredentialsOptions* options); 295 296 /// Creates STS credentials options from the $STS_CREDENTIALS environment 297 /// variable. This environment variable points to the path of a JSON file 298 /// comforming to the schema described above. 299 grpc::Status StsCredentialsOptionsFromEnv(StsCredentialsOptions* options); 300 301 std::shared_ptr<CallCredentials> StsCredentials( 302 const StsCredentialsOptions& options); 303 304 std::shared_ptr<CallCredentials> MetadataCredentialsFromPlugin( 305 std::unique_ptr<MetadataCredentialsPlugin> plugin, 306 grpc_security_level min_security_level); 307 308 /// Options used to build AltsCredentials. 309 struct AltsCredentialsOptions { 310 /// service accounts of target endpoint that will be acceptable 311 /// by the client. If service accounts are provided and none of them matches 312 /// that of the server, authentication will fail. 313 std::vector<grpc::string> target_service_accounts; 314 }; 315 316 /// Builds ALTS Credentials given ALTS specific options 317 std::shared_ptr<ChannelCredentials> AltsCredentials( 318 const AltsCredentialsOptions& options); 319 320 /// Builds Local Credentials. 321 std::shared_ptr<ChannelCredentials> LocalCredentials( 322 grpc_local_connect_type type); 323 324 /// Builds TLS Credentials given TLS options. 325 std::shared_ptr<ChannelCredentials> TlsCredentials( 326 const TlsChannelCredentialsOptions& options); 327 328 } // namespace experimental 329 } // namespace grpc 330 331 #endif // GRPCPP_SECURITY_CREDENTIALS_H 332