Proxies
BETAField-level reference for the proxy endpoint a company web proxy chains registry traffic to, the requests it accepts, and the Connections capture.
A proxy is the endpoint your company's web proxy hands registry traffic to. This page covers what that endpoint accepts, answers, and records. Setup: Connect a web proxy. How it works: Web proxy chaining.
Creating and managing proxies, the proxy object, and a proxy's routing table: API. What each operation requires: Permissions.
Requests the endpoint accepts
The endpoint accepts, on one port:
CONNECT <host>:443, followed by TLS for that host inside the tunnel- TLS directly, for a registry host, as if the endpoint were the registry
CONNECTover TLS to the endpoint's own hostname, when the deployment has one (an HTTPS proxy)- An absolute-form request for a plain
http://URL, such asGET http://registry.npmjs.org/lodash. HTTPS always arrives throughCONNECTor direct TLS, above
Credential
| Carrier | Where | Accepted |
|---|---|---|
X-Bytesafe-Proxy-Token: <credential> | The CONNECT, or each request | In every mode |
Proxy-Authorization: Basic <base64(user:credential)> | The CONNECT, or each request | The password is the credential; with an empty password, the user name is |
Proxy-Authorization: Bearer <credential> | The CONNECT, or each request |
When both are present, the header wins. A credential on the CONNECT applies to every request in the tunnel; a request may repeat it, but a different proxy's credential is refused. X-Bytesafe-Proxy-Token is removed before the request reaches the firewall.
Responses from the endpoint
These come from the endpoint itself, before a firewall sees the request. Once a request is routed, the firewall answers it as it would any client.
| Code | When |
|---|---|
407 | A CONNECT with a credential that matches no proxy, a CONNECT without one when no proxy can answer the TLS inside, or a plain-HTTP request without a credential. The response carries Proxy-Authenticate: Basic |
403 | The host is not routed by the proxy, the request carries no credential or one that matches no proxy, the credential belongs to a different proxy than the connection, or a proxy using its own CA sent a request on a connection the shared root answered |
400 | A request that is neither CONNECT nor absolute-form, on a connection that expects one |
A refused TLS handshake has no status code; it appears on the Connections tab as TLS refused.
User identity header
For a proxy whose userHeader is plain or base64, the header named by userHeaderName is read on each request and recorded as proxyUser on log entries and firewall webhook events. The value is ignored when it is empty, Unknown (any case), not valid base64 for base64, contains non-printable characters, or is longer than 256 bytes. The header is removed before the request reaches the firewall, whether or not it was read.
X-Forwarded-For, when present, is recorded as the entry's remoteAddress.
Connection events
The Connections capture holds the latest 200 events for each proxy, newest first, from every Bytesafe server. A proxy's capture is dropped after seven days without new events, and when the proxy is deleted. An event that cannot be attributed to a proxy, such as a CONNECT with an unknown credential, is not recorded unless the endpoint has a default proxy.
| Field | Type | Description |
|---|---|---|
time | string | When the event happened |
mode | string | connect (a tunnel opened or was refused; recorded when the tunnel opens), tunnelled (a request inside a tunnel), origin (a request on a direct TLS connection), forward (a plain-HTTP request), handshake (a TLS handshake was refused or failed) |
remoteAddress | string | The web proxy's address and port |
listenerTls | boolean | The web proxy spoke TLS to the endpoint's own hostname |
serverName | string | The TLS server name the web proxy asked for |
authority | string | The CONNECT target, or the host a request was for |
method, path | string | The request's method and path. No path for connect |
credentialCarrier | string | token-header, proxy-authorization-basic, proxy-authorization-bearer, tunnel (inherited from the CONNECT), or none |
credentialValid | boolean | A credential was found and matched a proxy |
headerNames | string[] | The request's header names, sorted. Values are not recorded |
authenticatedUser | string | The raw value of the user identity header, whether or not the proxy trusts it |
userHeaderName | string | The header authenticatedUser was read from |
forwardedFor | string | The raw X-Forwarded-For value |
status | number | The response status. 0 for a refused handshake |
detail | string | Why a handshake failed |
instance | string | The Bytesafe server that saw the event |
Audit actions
proxy.create, proxy.update, proxy.delete, and proxy.secret.rotate are recorded in the audit log, successes and failures alike.
Related
- How-to: Connect a web proxy
- Concept: Web proxy chaining
- Reference: API, Logs, Webhooks, Permissions, Audit log