Authentication, TLS, and Proxy¶

Contents | Previous: Handling Responses | Next: Streaming

After reading this chapter

This chapter distinguishes credentials, certificates, and proxy builder options. The Basic authentication example comes from each language's HttpClient tutorial.

Authentication and transport security are selected while creating a client. TLS encrypts transport to an HTTPS target and validates its server certificate. mTLS also validates a client certificate. A proxy relays the client's HTTP requests to the target API. A request-specific authentication header overrides client configuration when credentials differ for one request.

This tutorial uses plain HTTP

TLS, mTLS, and proxy options belong to the deployed endpoint. The tutorial code omits them.

↗ 크게 보기

Target credentials attach to the request header, while proxy credentials attach only to the proxy leg. Certificate validation and mTLS apply to the TLS leg for both a direct connection and a CONNECT tunnel.

1. Basic and Bearer Authentication¶

basic_auth creates an Authorization: Basic header from a user and password. bearer_token creates an Authorization: Bearer header from a token. A request-specific Authorization header takes precedence over this client configuration.

// The admin endpoint uses a separate base URL, so two clients show the 401 and 200 paths.
auto unauthenticated_admin = hc::client_t::create ("http://127.0.0.1:5181").build ();
const auto without_auth = co_await unauthenticated_admin
                            .post ("/admin/channels/profile/weight")
                            .query ("value", "2")
                            .async_raw ();
auto authenticated_admin = hc::client_t::create ("http://127.0.0.1:5181")
                             .basic_auth ("ops", "tutorial-admin")
                             .build ();
const auto with_auth = co_await authenticated_admin.post ("/admin/channels/profile/weight")
                         .query ("value", "2")
                         .async_raw ();
std::cout << "basic auth: without " << without_auth.status << " with " << with_auth.status
          << std::endl;

The example contrasts a 401 response without credentials with a 200 response from the same path using Basic authentication.

2. Trusted Certificates¶

trust_certificate_file adds a PEM certificate to the system trust store. It validates a private CA or self-signed server without replacing system roots. No option disables hostname validation.

3. An mTLS Client Certificate¶

client_certificate_file configures a PEM client certificate and a PKCS#8 key. It applies to an HTTPS endpoint that requires client authentication.

4. An HTTP Proxy¶

proxy accepts an http:// proxy URL only. For an HTTPS target, the client opens a CONNECT tunnel through the proxy and performs TLS inside it, so the proxy cannot read the target request content. proxy_basic_auth sends Basic credentials only to the proxy, never to the target server.

5. Next Chapter¶

Streaming covers paths that send or receive a large body without accumulating it.