Repository: saucelabs/sauce-docs
Pull request #3179: SC-5308: extract upstream auth guide
Author: login: budziam
Created: 2025-05-14T10:22:11Z | Merged: 2025-05-15T12:45:36Z

### Description
Extract the upstream authentication configuration instructions into a separate guide.


Diff:
diff --git a/docs/secure-connections/sauce-connect-5/advanced/security-authentication.md b/docs/secure-connections/sauce-connect-5/advanced/security-authentication.md
index ddb9411864..20ed8f7786 100644
--- a/docs/secure-connections/sauce-connect-5/advanced/security-authentication.md
+++ b/docs/secure-connections/sauce-connect-5/advanced/security-authentication.md
@@ -83,32 +83,6 @@ Having our own cloud enables us to provide our services faster, and with higher
 
 For an overview of the services offered by Sauce Labs, our methods for securing the transmission of test data and results, and our security policies and procedures, see our white paper, [Overview of Sauce Labs Security Processes](https://saucelabs.com/resources/white-papers/overview-of-sauce-labs-security-processes).
 
-## Authentication Using `--auth`
-
-This approach to authentication works by configuring Sauce Connect Proxy to send authentication details to any URL requesting them. It works for all requests, even those where you're asked for credentials in response to a click or form submission.
-
-For each URL where you need to bypass HTTP authentication, add this to your Sauce Connect Proxy startup command:
-
-```bash
---auth host:port:username:password
-```
-
-If your website doesn't need a port, you can use the default port, `port 80`. Let's say that your website under test is `mysite.com`, your username is `awesometester`, and your password is `supersekrit`. Here's how you'd write your Sauce Connect Proxy startup command:
-
-```bash
---auth mysite.com:80:awesometester:supersekrit
-```
-
-You can use this option multiple times in a row:
-
-```bash
---auth mysite.com:80:awesometester:supersekrit \
---auth myothersite.com:443:awesometester:supersekrit \
---auth mythirdsite.com:80:awesometester:supersekrit
-```
-
-For more information, see [Using Environment Variables for Authentication Credentials](/basics/environment-variables).
-
 ## Certificate Handling
 
 The security of Sauce Connect Proxy communication to both the Sauce Labs API and the virtual machine hosting your tests in the Sauce Labs cloud is managed through [public key certificates](https://en.wikipedia.org/wiki/Public_key_certificate).
diff --git a/docs/secure-connections/sauce-connect-5/guides/upstream-auth.md b/docs/secure-connections/sauce-connect-5/guides/upstream-auth.md
new file mode 100644
index 0000000000..df7f94f894
--- /dev/null
+++ b/docs/secure-connections/sauce-connect-5/guides/upstream-auth.md
@@ -0,0 +1,61 @@
+---
+id: upstream-auth
+title: Sauce Connect Upstream Authentication
+sidebar_label: Upstream Authentication
+---
+
+Sauce Connect supports upstream HTTP authentication via the [`--auth`](/dev/cli/sauce-connect-5/run/#auth) flag.
+This flag allows the proxy to automatically send credentials to specified hosts.
+It is necessary when your site under test is protected by basic authentication, and you want Sauce Connect to handle authentication transparently for you.
+
+## Overview
+
+By using the [`--auth`](/dev/cli/sauce-connect-5/run/#auth) flag, you can instruct Sauce Connect to send authentication credentials automatically whenever a request matches a specific host and port. This works for:
+
+- Standard HTTP basic authentication prompts.
+- Authentication challenges triggered by clicks or form submissions.
+
+:::note
+All domains specified via the [`--auth`](/dev/cli/sauce-connect-5/run/#auth) flag are automatically [resigned](https://docs.saucelabs.com/secure-connections/sauce-connect-5/advanced/security-authentication/#ssl-certificate-bumping), as if they were passed using the [`--tls-resign-domains`](/dev/cli/sauce-connect-5/run/#tls-resign-domains) flag.
+:::
+
+## Usage
+
+To configure Sauce Connect to send credentials to an upstream server, use the following format:
+
+```bash
+--auth <username[:password]@host:port,...>
+```
+
+### Example
+
+If your application is hosted at `mysite.com` and uses basic authentication with the username `awesometester` and password `supersekrit`, your command would look like this:
+
+```bash
+--auth awesometester:supersekrit@mysite.com:80
+```
+You can also use HTTPS (port `443`) or any other port that your upstream server is listening on.
+
+### Multiple Hosts
+
+You can provide the `--auth` flag multiple times to support multiple upstream hosts:
+
+```bash
+--auth awesometester:supersekrit@mysite.com:80 \
+--auth awesometester:supersekrit@myothersite.com:443 \
+--auth awesometester:supersekrit@mythirdsite.com:80
+```
+
+### Wildcard Matching
+
+You can use asterisks (*) to match any host and/or any port:
+
+```bash
+--auth awesometester:supersekrit@*:*
+``` 
+
+This instructs Sauce Connect to send the credentials to all hosts and all ports it connects to.
+
+## Security Tip
+
+If you're concerned about exposing credentials in the command line (where they can be viewed in process lists), consider using environment variables instead. For more details, see [Using Environment Variables](/secure-connections/sauce-connect-5/guides/configuration/#environment-variables)
diff --git a/sidebars.js b/sidebars.js
index a9b5ab4403..0119c19c8a 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -1039,6 +1039,7 @@ module.exports = {
                                 'secure-connections/sauce-connect-5/guides/ci-cd-integration',
                                 'secure-connections/sauce-connect-5/guides/tunnel-pool',
                                 'secure-connections/sauce-connect-5/guides/sharing-tunnel',
+                                'secure-connections/sauce-connect-5/guides/upstream-auth',
                             ],
                         },
                         {


Reviews:
user: login: Choraden
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-15T08:05:27Z
user: login: Choraden
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-15T08:06:04Z
user: login: Choraden
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-15T08:07:47Z
user: login: Choraden
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-15T12:20:58Z

Review comments:
diff_hunk: @@ -0,0 +1,47 @@
+---
+id: upstream-auth
+title: Sauce Connect Proxy Upstream Authentication
path: docs/secure-connections/sauce-connect-5/guides/upstream-auth.md
user: login: Choraden
body: We agreed to use just Sauce Connect? ~Proxy~
created_at: 2025-05-15T08:05:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,47 @@
+---
+id: upstream-auth
+title: Sauce Connect Proxy Upstream Authentication
path: docs/secure-connections/sauce-connect-5/guides/upstream-auth.md
user: login: Choraden
body: Applies to all the content below
created_at: 2025-05-15T08:06:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,47 @@
+---
+id: upstream-auth
+title: Sauce Connect Proxy Upstream Authentication
+sidebar_label: Upstream Authentication
+---
+
+Sauce Connect Proxy supports upstream HTTP authentication via the [`--auth`](/dev/cli/sauce-connect-5/run/#auth) flag.
+This flag allows the proxy to automatically send credentials to specified hosts.
+It is necessary when your site under test is protected by basic authentication, and you want Sauce Connect Proxy to handle authentication transparently for you.
+
+## Overview
+
+By using the [`--auth`](/dev/cli/sauce-connect-5/run/#auth) flag, you can instruct Sauce Connect Proxy to send authentication credentials automatically whenever a request matches a specific host and port. This works for:
+
+- Standard HTTP basic authentication prompts.
+- Authentication challenges triggered by clicks or form submissions.
+
+## Usage
+
+To configure Sauce Connect Proxy to send credentials to an upstream server, use the following format:
+
+```bash
+--auth host:port:username:password
+```
+
+### Example
+
+If your application is hosted at `mysite.com` and uses basic authentication with the username `awesometester` and password `supersekrit`, your command would look like this:
+
+```bash
+--auth mysite.com:80:awesometester:supersekrit
path: docs/secure-connections/sauce-connect-5/guides/upstream-auth.md
user: login: Choraden
body: The format is wrong `<username[:password]@host:port,...>`
created_at: 2025-05-15T08:07:46Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-05-14T10:25:59Z
body: Deploy preview ready for 3179!
https://docs.dev.saucelabs.net/pr-preview/pr-3179

author_association: NONE
user: login: github-actions[bot]
created_at: 2025-05-14T10:29:58Z
body: Deploy preview ready for 3179!
https://docs.dev.saucelabs.net/pr-preview/pr-3179

author_association: NONE
user: login: github-actions[bot]
created_at: 2025-05-14T10:33:47Z
body: Deploy preview ready for 3179!
https://docs.dev.saucelabs.net/pr-preview/pr-3179

author_association: NONE
user: login: Choraden
created_at: 2025-05-15T08:10:06Z
body: How about adding an example with `*`?

Maybe it's worth commenting that all hosts from auth are automatically resigned - otherwise it's not possible to inject them with auth headers.  
From CLI description:
```
Note that all the hosts are automatically resigned as if they were passed to --tls-resign-domains flag.
```
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-05-15T09:20:12Z
body: Deploy preview ready for 3179!
https://docs.dev.saucelabs.net/pr-preview/pr-3179

author_association: NONE
user: login: github-actions[bot]
created_at: 2025-05-15T09:24:13Z
body: Deploy preview ready for 3179!
https://docs.dev.saucelabs.net/pr-preview/pr-3179

author_association: NONE
user: login: github-actions[bot]
created_at: 2025-05-15T12:45:28Z
body: Deploy preview ready for 3179!
https://docs.dev.saucelabs.net/pr-preview/pr-3179

author_association: NONE