[docs] Add authentication.md (#20990)

* [docs] Add docs/users/authentication.md

* edits

* Add link to README.md

* Address CR comments

* Fixup

Co-authored-by: Robert Schumacher <ras0219@outlook.com>

docs/README.md

@@ -17,6 +17,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Buildsystem Integration](users/integration.md)
 - [Triplet files](users/triplets.md)
 - [Configuration and Environment](users/config-environment.md)
+- [Authentication](users/authentication.md)
 - [Manifest Mode](users/manifests.md)
 - [Binary Caching](users/binarycaching.md)
 - [Asset Caching](users/assetcaching.md)

docs/users/authentication.md

@@ -0,0 +1,79 @@
+# Authentication for Source Code
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/authentication.md).**
+
+Registries and `vcpkg_from_git()` directly use the git command line tools to fetch remote resources. Some of these resources may be protected from anonymous access and need authentication or credentials.
+
+The strategies below all seek to achieve the same fundamental goal: `git clone https://....` should succeed without interaction. This enables vcpkg to be separated from the specifics of your authentication scheme, ensuring forwards compatibility with any additional security improvements in the future.
+
+## Pre-seed git credentials
+
+You can pre-seed git credentials via `git credential approve`:
+
+Powershell:
+```powershell
+"url=https://github.com`npath=Microsoft/vcpkg`nusername=unused`npassword=$MY_PAT`n" | git credential approve
+```
+Bash:
+```sh
+echo "url=https://github.com"$'\n'"path=Microsoft/vcpkg"$'\n'"username=unused"$'\n'"password=$MY_PAT"$'\n' | git credential approve
+```
+
+## Bearer auth
+
+For systems which need bearer auth, you can use `git config`:
+
+**Note: you must make these config changes with `--global`**
+```
+git config --global --unset-all http.<uri>.extraheader
+git config --global http.<uri>.extraheader "AUTHORIZATION: bearer <System_AccessToken>"
+```
+The `<uri>` can be filled in with a variety of options, documented in https://git-scm.com/docs/git-config#Documentation/git-config.txt-httplturlgt. For example, `https://dev.azure.com/MYORG/`.
+
+(Original Source: https://github.com/Microsoft/azure-pipelines-agent/issues/1601#issuecomment-394511048).
+
+**Note for Azure DevOps users:** You may need to enable access via Job authorization scope https://docs.microsoft.com/en-us/azure/devops/pipelines/process/access-tokens?view=azure-devops&tabs=yaml#job-authorization-scope. You may also need to "reference" the repo in your yaml via:
+
+```yaml
+resources: 
+  repositories:
+    - repository: <FRIENDLYNAME>
+      type: git
+      name: <ORG>/<REPO>
+      tag: tags/<TAG>
+
+...
+
+jobs:
+ - job: Build
+   uses:
+     repositories: [<FRIENDLYNAME>]
+```
+
+## Pass credentials in an environment variable (not recommended)
+
+Using `VCPKG_KEEP_ENV_VARS` or `VCPKG_ENV_PASSTHROUGH_UNTRACKED`, we can smuggle credential info via another var like `MY_TOKEN_VAR`.
+```sh
+export VCPKG_KEEP_ENV_VARS=MY_TOKEN_VAR
+export MY_TOKEN_VAR=abc123
+```
+This can then be used in your private ports:
+```cmake
+# some/private/portfile.cmake
+set(MY_TOKEN_VAR "")
+if(DEFINED ENV{MY_TOKEN_VAR})
+    set(MY_TOKEN_VAR "$ENV{MY_TOKEN_VAR}@")
+endif()
+vcpkg_from_git(
+    URLS "https://${MY_TOKEN_VAR}host.com/normal/url/path"
+    ...
+)
+```
+```cmake
+# some/other/private/portfile.cmake
+vcpkg_from_github(
+    AUTHORIZATION_TOKEN "$ENV{MY_TOKEN_VAR}"
+)
+```
+
+For private ports, we recommend using `vcpkg_from_git()` instead of `vcpkg_from_github()` and the pre-seeding method above.

docs/users/config-environment.md

@@ -66,6 +66,9 @@ This environment variable, if set, suppresses the downloading of CMake and Ninja
 This environment variable can be set to a list of environment variables, separated by `;`, which will be propagated to
 the build environment.
 
+The values of the kept variables will not be tracked in package ABIs and will not cause rebuilds when they change. To
+pass in environment variables that should cause rebuilds on change, see [`VCPKG_ENV_PASSTHROUGH`](triplets.md#VCPKG_ENV_PASSTHROUGH).
+
 Example: `FOO_SDK_DIR;BAR_SDK_DIR`
 
 #### VCPKG_MAX_CONCURRENCY

docs/users/triplets.md

@@ -124,6 +124,7 @@ When this option is set to (true|1|on), the compiler is ignored in the abi track
 
 ## Windows Variables
 
+<a name="VCPKG_ENV_PASSTHROUGH"></a>
 ### VCPKG_ENV_PASSTHROUGH
 Instructs vcpkg to allow additional environment variables into the build process.