You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Value Format: `<value>` (you can use empty command line switch to enable)
291
+
* Default Value: `false`
292
+
293
+
Authenticate to proxy specified in `--proxy-sauce` using Kerberos. Kerberos authentication must be enabled and configured for `sc`.
294
+
286
295
## DNS
287
296
288
297
### `--dns-round-robin` {#dns-round-robin}
@@ -466,6 +475,132 @@ The following example specifies that the API module logs errors, the proxy modul
466
475
467
476
Log level.
468
477
478
+
## Kerberos authentication
479
+
480
+
### Introduction
481
+
482
+
Sauce Connect 5 supports Kerberos authentication for both upstream proxy and tested applications.
483
+
484
+
The `sc` client process connects to your Kerberos KDC server, authenticates as the configured account ("principal name") and retrieves relevant Kerberos service tickets. Kerberos connection and authentication are local only to your `sc` client - Sauce Labs servers do not participate in it.
485
+
486
+
It is also fully transparent to your tests as `sc` injects relevant HTTP headers with Kerberos authentication tokens automatically for all needed requests forwarded through the tunnel.
487
+
488
+
Supported modes:
489
+
490
+
* Kerberos authentication to the upstream proxy defined in `--proxy-sauce` - using `Proxy-Authorization` HTTP header
491
+
* Kerberos authentication to the upstream proxy defined in `--proxy` - using `Proxy-Authorization` HTTP header
492
+
* Kerberos authentication to tested web applications by injecting `Authorization` header to forwarded HTTP requests
493
+
494
+
It is possible to have combination of settings - for example when both upstream proxy and tested application require Kerberos authentication
495
+
496
+
Sauce Connect 5 generates SPNEGO tokens from relevant Kerberos tickets to pass in HTTP headers which is the most popular and standardized way of handling Kerberos HTTP authentication.
497
+
498
+
Implemented method is called "opportunistic authentication", meaning that `sc` does not try to detect `401` or `407` HTTP error codes and negotiate Kerberos authentication - it uses predefined host names needing Kerberos authentication and it's up to the user to know those hosts in advance. This greatly improves performance and does not interfere with your tests which may require detection and custom handling of `401` and other error codes.
499
+
500
+
Current implementation uses HTTP request host (or configured proxy hostname) as SPN (Service Principal Name) to request tickets from Kerberos KDC server. For example `app.example.com` is converted to SPN `HTTP/app.example.com` and such SPN is expected to be present in Kerberos KDC server.
501
+
502
+
To use Kerberos authentication mechanism, you must have both a `krb5.conf` file, which points to proper realms and Kerberos servers and keytab file accessible to `sc` client. Those are standardized format files used in most Kerberos related software suites and are not specific to Sauce Connect 5 client.
503
+
504
+
### --kerberos-cfg-file {#kerberos-cfg-file}
505
+
506
+
* Environment variable: `SAUCE_KERBEROS_CFG_FILE`
507
+
* Value Format: `<path>`
508
+
509
+
Path to krb5.conf configuration file with kerberos connection settings.
Name of the account username (principal name using Kerberos nomenclature) as which `sc` will authenticate to a Kerberos KDC server. User and its password (hashed) must be present in keytab file specified in `--kerberos-keytab-file`
Kerberos realm of the user specified in `--kerberos-user-name`. It depends on Kerberos settings in organisation but in most cases it's the company domain name.
List of hosts for which Kerberos (SPNEGO) authorization tokens will be injected as `Authorization` header. If a forwarded HTTP request already has such header (or header is added by `sc` by means of other settings, like custom headers or credentials) - this header value will be overwritten by SPNEGO token.
547
+
548
+
Please note that this host list does not support wildcards.
* Value Format: `<value>` (you can use empty command-line switch to enable)
555
+
* Default Value: `false`
556
+
557
+
Authenticate to a configured upstream proxy with Kerberos (using `Proxy-Authorization` HTTP header). Please note that if `sc` configuration results in multiple proxies available (like PAC for example), `sc` will try to authenticate with Kerberos to each one of them.
558
+
559
+
To enable Kerberos authentication for `--proxy-sauce` specified proxy server, see: [--proxy-sauce-enable-kerberos-auth](#proxy-sauce-enable-kerberos-auth)
* Value Format: `<value>` (you can use empty commant switch to enable)
566
+
* Default Value: `false`
567
+
568
+
569
+
Running `sc` with `--kerberos-run-diagnostics` switch will run basic Kerberos diagnostics and exit the process.
570
+
571
+
Diagnostics will print debugging information about Kerberos connection or known configuration errors - for example an error when there are discrepancies between supported encryption types and keytab entry:
572
+
573
+
```
574
+
msg="fatal error exiting" error="kerberos configuration potential problems: default_tkt_enctypes specifies 17 but this enctype is not available in the client's keytab\ndefault_tkt_enctypes specifies 23 but this enctype is not available in the client's keytab\npreferred_preauth_types specifies 17 but this enctype is not available in the client's keytab\npreferred_preauth_types specifies 15 but this enctype is not available in the client's keytab\npreferred_preauth_types specifies 14 but this enctype is not available in the client's keytab"
575
+
```
576
+
577
+
Diagnostics printout will allow you to match enctype number to string:
578
+
579
+
```
580
+
"DefaultTGSEnctypes": [
581
+
"aes256-cts-hmac-sha1-96",
582
+
"aes128-cts-hmac-sha1-96",
583
+
"des3-cbc-sha1",
584
+
"arcfour-hmac-md5",
585
+
"camellia256-cts-cmac",
586
+
"camellia128-cts-cmac",
587
+
"des-cbc-crc",
588
+
"des-cbc-md5",
589
+
"des-cbc-md4"
590
+
],
591
+
"DefaultTGSEnctypeIDs": [
592
+
18,
593
+
17,
594
+
23
595
+
],
596
+
597
+
```
598
+
599
+
(17 is aes128-cts-hmac-sha1-96, etc)
600
+
601
+
Often having only one enctype in user configuration will work but can break at any time if hosts decide to negotiate something different than usual. For simplification you can restrict supported encryption types to 1-2 entries in krb5.conf file. The enctypes listed in diagnostics mode are sorted from most secure to least secure so in most cases first 1-2 positions are good enough to choose from and check if KDC server supports them. When in doubt - contact your Active Directory or Kerberos administrator.
602
+
603
+
469
604
## Formatting Domains
470
605
471
606
Here are some guidelines to follow when formatting domain regular expressions:
0 commit comments