chore: explain GIT_ASKPASS behavior in docs (#12784)

* chore: docs explaining GIT_ASKPASS behavior

- VSCode configuration requirements

cli/externalauth.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"encoding/json"
+	"fmt"
 
 	"golang.org/x/xerrors"
 
@@ -9,6 +10,7 @@ import (
 
 	"github.com/coder/coder/v2/cli/cliui"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/pretty"
 	"github.com/coder/serpent"
 )
 
@@ -68,6 +70,11 @@ fi
 			ctx, stop := inv.SignalNotifyContext(ctx, StopSignals...)
 			defer stop()
 
+			if r.agentToken == "" {
+				_, _ = fmt.Fprint(inv.Stderr, pretty.Sprintf(headLineStyle(), "No agent token found, this command must be run from inside a running workspace.\n"))
+				return xerrors.Errorf("agent token not found")
+			}
+
 			client, err := r.createAgentClient()
 			if err != nil {
 				return xerrors.Errorf("create agent client: %w", err)

cli/externalauth_test.go

@@ -24,7 +24,7 @@ func TestExternalAuth(t *testing.T) {
 		}))
 		t.Cleanup(srv.Close)
 		url := srv.URL
-		inv, _ := clitest.New(t, "--agent-url", url, "external-auth", "access-token", "github")
+		inv, _ := clitest.New(t, "--agent-url", url, "--agent-token", "foo", "external-auth", "access-token", "github")
 		pty := ptytest.New(t)
 		inv.Stdout = pty.Output()
 		waiter := clitest.StartWithWaiter(t, inv)
@@ -40,7 +40,7 @@ func TestExternalAuth(t *testing.T) {
 		}))
 		t.Cleanup(srv.Close)
 		url := srv.URL
-		inv, _ := clitest.New(t, "--agent-url", url, "external-auth", "access-token", "github")
+		inv, _ := clitest.New(t, "--agent-url", url, "--agent-token", "foo", "external-auth", "access-token", "github")
 		pty := ptytest.New(t)
 		inv.Stdout = pty.Output()
 		clitest.Start(t, inv)
@@ -55,7 +55,7 @@ func TestExternalAuth(t *testing.T) {
 		}))
 		t.Cleanup(srv.Close)
 		url := srv.URL
-		inv, _ := clitest.New(t, "--agent-url", url, "external-auth", "access-token")
+		inv, _ := clitest.New(t, "--agent-url", url, "--agent-token", "foo", "external-auth", "access-token")
 		watier := clitest.StartWithWaiter(t, inv)
 		watier.RequireContains("wanted 1 args but got 0")
 	})
@@ -71,7 +71,7 @@ func TestExternalAuth(t *testing.T) {
 		}))
 		t.Cleanup(srv.Close)
 		url := srv.URL
-		inv, _ := clitest.New(t, "--agent-url", url, "external-auth", "access-token", "github", "--extra", "hey")
+		inv, _ := clitest.New(t, "--agent-url", url, "--agent-token", "foo", "external-auth", "access-token", "github", "--extra", "hey")
 		pty := ptytest.New(t)
 		inv.Stdout = pty.Output()
 		clitest.Start(t, inv)

docs/admin/external-auth.md

@@ -212,8 +212,46 @@ you can require users authenticate via git prior to creating a workspace:
 
 ![Git authentication in template](../images/admin/git-auth-template.png)
 
-The following example will require users authenticate via GitHub and auto-clone
-a repo into the `~/coder` directory.
+### Native git authentication will auto-refresh tokens
+
+<blockquote class="info">
+  <p>
+  This is the preferred authentication method.
+  </p>
+</blockquote>
+
+By default, the coder agent will configure native `git` authentication via the
+`GIT_ASKPASS` environment variable. Meaning, with no additional configuration,
+external authentication will work with native `git` commands.
+
+To check the auth token being used **from inside a running workspace**, run:
+
+```shell
+# If the exit code is non-zero, then the user is not authenticated with the
+# external provider.
+coder external-auth access-token <external-auth-id>
+```
+
+Note: Some IDE's override the `GIT_ASKPASS` environment variable and need to be
+configured.
+
+**VSCode**
+
+Use the
+[Coder](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
+extension to automatically configure these settings for you!
+
+Otherwise, you can manually configure the following settings:
+
+- Set `git.terminalAuthentication` to `false`
+- Set `git.useIntegratedAskPass` to `false`
+
+### Hard coded tokens do not auto-refresh
+
+If the token is required to be inserted into the workspace, for example
+[GitHub cli](https://cli.github.com/), the auth token can be inserted from the
+template. This token will not auto-refresh. The following example will
+authenticate via GitHub and auto-clone a repo into the `~/coder` directory.
 
 ```hcl
 data "coder_external_auth" "github" {