[PATCH] docs: discuss caching personal access tokens

[PATCH] docs: discuss caching personal access tokens

[M Hickford via GitGitGadget]

From: M Hickford <mirth.hickford@gmail.com>

Describe problems storing personal access tokens in git-credential-cache
and suggest alternatives.

Research suggests that many users are confused about this:

> the point of passwords is that (ideally) you memorise them [so]
> they're never stored anywhere in plain text. Yet GitHub's personal
> access token system seems to basically force you to store the token in
> plain text?

https://stackoverflow.com/questions/46645843/where-to-store-my-git-personal-access-token#comment89963004_46645843
Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    docs: discuss caching personal access tokens

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1851%2Fhickford%2Fcache-pat-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1851/hickford/cache-pat-docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1851

 Documentation/git-credential-cache.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt
index 487cc557a87..18e9933674a 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.txt
@@ -78,6 +78,23 @@ variable (this example increases the cache time to 1 hour):
 $ git config credential.helper 'cache --timeout=3600'
 -------------------------------------------------------
 
+PERSONAL ACCESS TOKENS
+----------------------
+
+Some remotes accept personal access tokens, which are randomly
+generated and hard to memorise. They typically have a lifetime of weeks
+or months.
+
+git-credential-cache is inherently unsuitable for persistent storage of
+personal access tokens. The credential will be forgotten after the cache
+timeout. Even if you configure a long timeout, credentials will be
+forgotten if the daemon dies.
+
+To avoid frequently regenerating personal access tokens, configure a
+credential helper with persistent storage. Alternatively, configure an
+OAuth credential helper to generate credentials automatically. See
+linkgit:gitcredentials[7].
+
 GIT
 ---
 Part of the linkgit:git[1] suite

base-commit: 14650065b76b28d3cfa9453356ac5669b19e706e
-- 
gitgitgadget

Re: [PATCH] docs: discuss caching personal access tokens

[Junio C Hamano]

"M Hickford via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: M Hickford <mirth.hickford@gmail.com>
>
> Describe problems storing personal access tokens in git-credential-cache
> and suggest alternatives.

> +PERSONAL ACCESS TOKENS
> +----------------------
> +
> +Some remotes accept personal access tokens, which are randomly
> +generated and hard to memorise. They typically have a lifetime of weeks
> +or months.
> +
> +git-credential-cache is inherently unsuitable for persistent storage of
> +personal access tokens. The credential will be forgotten after the cache
> +timeout. Even if you configure a long timeout, credentials will be
> +forgotten if the daemon dies.

Very true.

> +To avoid frequently regenerating personal access tokens, configure a
> +credential helper with persistent storage.

Like libsecret and osxkeychain, you mean?  I am wondering if we want
to be a bit more helpful by being explicit.  I think there is a
section in a maual page that has a list of known and often-used
credential backends, so referring the readers to that section may be
helpful.

> Alternatively, configure an
> +OAuth credential helper to generate credentials automatically. See
> +linkgit:gitcredentials[7].

Indeed.

RE: [PATCH] docs: discuss caching personal access tokens

[rsbecker]

On January 10, 2025 1:17 PM, Junio C Hamano wrote:
>Subject: Re: [PATCH] docs: discuss caching personal access tokens
>
>"M Hickford via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: M Hickford <mirth.hickford@gmail.com>
>>
>> Describe problems storing personal access tokens in
>> git-credential-cache and suggest alternatives.
>
>> +PERSONAL ACCESS TOKENS
>> +----------------------
>> +
>> +Some remotes accept personal access tokens, which are randomly
>> +generated and hard to memorise. They typically have a lifetime of
>> +weeks or months.
>> +
>> +git-credential-cache is inherently unsuitable for persistent storage
>> +of personal access tokens. The credential will be forgotten after the
>> +cache timeout. Even if you configure a long timeout, credentials will
>> +be forgotten if the daemon dies.
>
>Very true.
>
>> +To avoid frequently regenerating personal access tokens, configure a
>> +credential helper with persistent storage.
>
>Like libsecret and osxkeychain, you mean?  I am wondering if we want to be
a bit
>more helpful by being explicit.  I think there is a section in a maual page
that has a
>list of known and often-used credential backends, so referring the readers
to that
>section may be helpful.
>
>> Alternatively, configure an
>> +OAuth credential helper to generate credentials automatically. See
>> +linkgit:gitcredentials[7].
>
>Indeed.

My solution for this is to write a custom credential manager that is PAT
aware. The one I built
does not support OAuth or OAuth2. This is non-trivial when dealing with a
CLI. Integrating
with something like MS Authenticator might be a reasonable option for some.

Re: [PATCH] docs: discuss caching personal access tokens

[M Hickford]

On Fri, 10 Jan 2025 at 18:16, Junio C Hamano <gitster@pobox.com> wrote:
>
> "M Hickford via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: M Hickford <mirth.hickford@gmail.com>
> >
> > Describe problems storing personal access tokens in git-credential-cache
> > and suggest alternatives.
>
> > +PERSONAL ACCESS TOKENS
> > +----------------------
> > +
> > +Some remotes accept personal access tokens, which are randomly
> > +generated and hard to memorise. They typically have a lifetime of weeks
> > +or months.
> > +
> > +git-credential-cache is inherently unsuitable for persistent storage of
> > +personal access tokens. The credential will be forgotten after the cache
> > +timeout. Even if you configure a long timeout, credentials will be
> > +forgotten if the daemon dies.
>
> Very true.
>
> > +To avoid frequently regenerating personal access tokens, configure a
> > +credential helper with persistent storage.
>
> Like libsecret and osxkeychain, you mean?  I am wondering if we want
> to be a bit more helpful by being explicit.  I think there is a
> section in a maual page that has a list of known and often-used
> credential backends, so referring the readers to that section may be
> helpful.

I agree, explicit is more helpful. I shall expand that
gitcredentials.txt section in patch v2.

>
> > Alternatively, configure an
> > +OAuth credential helper to generate credentials automatically. See
> > +linkgit:gitcredentials[7].
>
> Indeed.

[PATCH v2 0/2] docs: discuss caching personal access tokens

[M Hickford via GitGitGadget]

CC: sandals@crustytoothpaste.net CC: derrickstolee@github.com CC:
stolee@gmail.com CC: Johannes.Schindelin@gmx.de CC: peff@peff.net cc:
rsbecker@nexbridge.com

Patch v2 adds a list of popular credential helpers.

M Hickford (2):
  docs: list popular credential helpers
  docs: discuss caching personal access tokens

 Documentation/git-credential-cache.txt | 17 +++++++++++
 Documentation/gitcredentials.txt       | 41 ++++++++++++++++++--------
 2 files changed, 46 insertions(+), 12 deletions(-)


base-commit: 14650065b76b28d3cfa9453356ac5669b19e706e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1851%2Fhickford%2Fcache-pat-docs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1851/hickford/cache-pat-docs-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1851

Range-diff vs v1:

 -:  ----------- > 1:  097eb0e8776 docs: list popular credential helpers
 1:  1980f6a5aa7 ! 2:  ac8c5e1b552 docs: discuss caching personal access tokens
     @@ Documentation/git-credential-cache.txt: variable (this example increases the cac
      +To avoid frequently regenerating personal access tokens, configure a
      +credential helper with persistent storage. Alternatively, configure an
      +OAuth credential helper to generate credentials automatically. See
     -+linkgit:gitcredentials[7].
     ++linkgit:gitcredentials[7], sections "Available helpers" and "OAuth".
      +
       GIT
       ---

-- 
gitgitgadget

[PATCH v2 1/2] docs: list popular credential helpers

[M Hickford via GitGitGadget]

From: M Hickford <mirth.hickford@gmail.com>

git-credential-store saves credentials unencrypted on disk. It is the
least secure choice of credential helper. Nevertheless, it appears
several times more popular than any other credential helper [1].

Inform users about more secure alternatives.

[1] https://stackoverflow.com/questions/35942754/how-can-i-save-username-and-password-in-git

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
 Documentation/gitcredentials.txt | 41 ++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 35a7452c8fe..3337bb475de 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -66,18 +66,7 @@ storage provided by the OS or other programs. Alternatively, a
 credential-generating helper might generate credentials for certain servers via
 some API.
 
-To use a helper, you must first select one to use. Git currently
-includes the following helpers:
-
-cache::
-
-	Cache credentials in memory for a short period of time. See
-	linkgit:git-credential-cache[1] for details.
-
-store::
-
-	Store credentials indefinitely on disk. See
-	linkgit:git-credential-store[1] for details.
+To use a helper, you must first select one to use (see below for a list).
 
 You may also have third-party helpers installed; search for
 `credential-*` in the output of `git help -a`, and consult the
@@ -106,6 +95,28 @@ $ git config --global credential.helper foo
 
 === Available helpers
 
+Git currently includes the following helpers:
+
+cache::
+
+    Cache credentials in memory for a short period of time. See
+    linkgit:git-credential-cache[1] for details.
+
+store::
+
+    Store credentials indefinitely on disk. See
+    linkgit:git-credential-store[1] for details.
+
+Popular helpers with secure persistent storage include:
+
+    - git-credential-libsecret (Linux)
+
+    - git-credential-osxkeychain (macOS)
+
+    - git-credential-wincred (Windows)
+
+    - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows)
+
 The community maintains a comprehensive list of Git credential helpers at
 https://git-scm.com/doc/credential-helpers.
 
@@ -116,6 +127,12 @@ OAuth credential helper. Initial authentication opens a browser window to the
 host. Subsequent authentication happens in the background. Many popular Git
 hosts support OAuth.
 
+Popular helpers with OAuth support include:
+
+    - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows)
+
+    - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
+
 CREDENTIAL CONTEXTS
 -------------------
 
-- 
gitgitgadget

[PATCH v2 2/2] docs: discuss caching personal access tokens

[M Hickford via GitGitGadget]

From: M Hickford <mirth.hickford@gmail.com>

Describe problems storing personal access tokens in git-credential-cache
and suggest alternatives.

Research suggests that many users are confused about this:

> the point of passwords is that (ideally) you memorise them [so]
> they're never stored anywhere in plain text. Yet GitHub's personal
> access token system seems to basically force you to store the token in
> plain text?

https://stackoverflow.com/questions/46645843/where-to-store-my-git-personal-access-token#comment89963004_46645843
Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
 Documentation/git-credential-cache.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt
index 487cc557a87..54fa7a27e19 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.txt
@@ -78,6 +78,23 @@ variable (this example increases the cache time to 1 hour):
 $ git config credential.helper 'cache --timeout=3600'
 -------------------------------------------------------
 
+PERSONAL ACCESS TOKENS
+----------------------
+
+Some remotes accept personal access tokens, which are randomly
+generated and hard to memorise. They typically have a lifetime of weeks
+or months.
+
+git-credential-cache is inherently unsuitable for persistent storage of
+personal access tokens. The credential will be forgotten after the cache
+timeout. Even if you configure a long timeout, credentials will be
+forgotten if the daemon dies.
+
+To avoid frequently regenerating personal access tokens, configure a
+credential helper with persistent storage. Alternatively, configure an
+OAuth credential helper to generate credentials automatically. See
+linkgit:gitcredentials[7], sections "Available helpers" and "OAuth".
+
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
gitgitgadget