[PATCH] Mention that password could be a personal access token.

[PATCH] Mention that password could be a personal access token.

[M Hickford via GitGitGadget]

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

These days, the 'password' for a software forge might be personal access
token or OAuth access token.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    Mention that password could be a personal access token.
    
    These days, the 'password' for a software forge might be personal access
    token or OAuth access token.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1396%2Fhickford%2Fmore-about-credentials-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1396/hickford/more-about-credentials-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1396

 Documentation/git-credential.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt
index f18673017f5..f3bf0bef54b 100644
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.txt
@@ -142,7 +142,9 @@ Git understands the following attributes:
 
 `password`::
 
-	The credential's password, if we are asking it to be stored.
+	The credential's password, if we are asking it to be stored. If the
+	host is a software forge, this could also be a personal access
+	token or OAuth access token.
 
 `url`::
 

base-commit: 1fc3c0ad407008c2f71dd9ae1241d8b75f8ef886
-- 
gitgitgadget

Re: [PATCH] Mention that password could be a personal access token.

[Junio C Hamano]

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

>  `password`::
>  
> -	The credential's password, if we are asking it to be stored.
> +	The credential's password, if we are asking it to be stored. If the
> +	host is a software forge, this could also be a personal access
> +	token or OAuth access token.

Is this limited to software forge hosts?

Also, I wonder if the specific "it can be access token and not
password" is something worth adding.  If there were a service styled
after the good-old "anonymous ftp", it would expect the constant
string 'anonymous' as the "username", and would expect to see your
identity (e.g. 'mirth.hickford@gmail.com') as the "password".  The
point is that it does not matter what it is called on the end-user's
side, be it a password or access token or whatever.  It is what the
other end that provides the service wants to see after you claimed
who you are by providing "username", usually (but not necessarily)
in order to prove your claim.

So, I dunno.

Re: [PATCH] Mention that password could be a personal access token.

[Jeff King]

On Thu, Oct 27, 2022 at 10:40:13AM -0700, Junio C Hamano wrote:

> "M Hickford via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> >  `password`::
> >  
> > -	The credential's password, if we are asking it to be stored.
> > +	The credential's password, if we are asking it to be stored. If the
> > +	host is a software forge, this could also be a personal access
> > +	token or OAuth access token.
> 
> Is this limited to software forge hosts?
> 
> Also, I wonder if the specific "it can be access token and not
> password" is something worth adding.  If there were a service styled
> after the good-old "anonymous ftp", it would expect the constant
> string 'anonymous' as the "username", and would expect to see your
> identity (e.g. 'mirth.hickford@gmail.com') as the "password".  The
> point is that it does not matter what it is called on the end-user's
> side, be it a password or access token or whatever.  It is what the
> other end that provides the service wants to see after you claimed
> who you are by providing "username", usually (but not necessarily)
> in order to prove your claim.
> 
> So, I dunno.

FWIW, I had the same reaction. From the client perspective for https,
this is going over basic-auth, and it might be nice to just say so. But
of course the whole credential system is abstract, so it gets awkward.
We could probably say something like:

  The credential's password, if we are asking it to be stored. Note that
  this may not strictly be a traditional password, but rather any secret
  string which is used for authentication. For instance, Git's HTTP
  protocol will generally pass this using an Authorization header;
  depending on what the server is expecting this may be a password typed
  by the user, a personal access token, or some other opaque value.

Maybe that is getting too into the weeds. OTOH, anybody reading this far
into git-credential(1) is probably pretty technical. There may be a
better way of wording it, too. Another way of thinking about it that
it's basically any secret that is a single string, and not part of a
challenge/response protocol. I couldn't find a way to word that which
didn't end up more confusing, though. ;)

-Peff

Re: [PATCH] Mention that password could be a personal access token.

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> FWIW, I had the same reaction. From the client perspective for https,
> this is going over basic-auth, and it might be nice to just say so. But
> of course the whole credential system is abstract, so it gets awkward.
> We could probably say something like:
>
>   The credential's password, if we are asking it to be stored. Note that
>   this may not strictly be a traditional password, but rather any secret
>   string which is used for authentication. For instance, Git's HTTP
>   protocol will generally pass this using an Authorization header;
>   depending on what the server is expecting this may be a password typed
>   by the user, a personal access token, or some other opaque value.

Thanks.  I have no problem with this replacement text.

> Maybe that is getting too into the weeds. OTOH, anybody reading this far
> into git-credential(1) is probably pretty technical.

True, too.

Re: [PATCH] Mention that password could be a personal access token.

[M Hickford]

On Thu, 27 Oct 2022 at 18:40, Junio C Hamano <gitster@pobox.com> wrote:

> Also, I wonder if the specific "it can be access token and not
> password" is something worth adding.

Personal access tokens are ubiquitous nowadays, maybe even more common
than passwords since GitHub disabled passwords last year. I wanted
to acknowledge this in the docs, even if Git's own behaviour hasn't
changed. Maybe the introduction to
https://git-scm.com/docs/gitcredentials would be a better place to do
that?

     Git will sometimes need credentials from the user in order to
perform operations; for example, it may need to ask for a username and
password in order to access a remote repository over HTTP. **The
server may accept or expect a personal access token instead of a
password.**

[1] https://github.blog/changelog/2021-08-12-git-password-authentication-is-shutting-down/

Re: [PATCH] Mention that password could be a personal access token.

[Ævar Arnfjörð Bjarmason]

On Tue, Nov 01 2022, M Hickford wrote:

> On Thu, 27 Oct 2022 at 18:40, Junio C Hamano <gitster@pobox.com> wrote:
>
>> Also, I wonder if the specific "it can be access token and not
>> password" is something worth adding.
>
> Personal access tokens are ubiquitous nowadays, maybe even more common
> than passwords since GitHub disabled passwords last year. I wanted
> to acknowledge this in the docs, even if Git's own behaviour hasn't
> changed. Maybe the introduction to
> https://git-scm.com/docs/gitcredentials would be a better place to do
> that?
>
>      Git will sometimes need credentials from the user in order to
> perform operations; for example, it may need to ask for a username and
> password in order to access a remote repository over HTTP. **The
> server may accept or expect a personal access token instead of a
> password.**
>
> [1] https://github.blog/changelog/2021-08-12-git-password-authentication-is-shutting-down/

A "personal access token" is just a password by another name. When you
enter such a token into your .git/config (or provide it via an auth
helper) we'll sent it over via HTTP Basic Auth, "which transmits
credentials as user-id/ password pairs, encoded using Base64"[2].

Even the blog post you linked to makes the distinction, by talking about
"account passwords". I.e. what's really going on here is that providers
have been moving to using N passwords instead of 1.

Now, I'm not just trying to be pedantic. I do think there's probably a
doc improvement to be made here. If popular providers are calling this a
"[personal] access token" perhaps we should mention it in passing.

But saying "this could also be" is the point at which this could create
its own confusion. This *is* a password. E.g. if you get such a "token"
and want to try it out with the "curl" utility (whose library we use for
http) it'll be e.g.:

	curl --user <user>:<password> <url>

Not:

	curl --user <user> --personal-access-token <token> <url>

Or whatever. I.e. the entire rest of the stack calls this a "password",
and that stack's a lot more likely to be what stays around in the long
term, rather than what amounts to a marketing term for a password.

1. https://www.rfc-editor.org/rfc/rfc7617

Re: [PATCH] Mention that password could be a personal access token.

[M Hickford]

On Tue, 1 Nov 2022 at 08:09, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>
> what's really going on here is that providers
> have been moving to using N passwords instead of 1.

I like that way of thinking about it.

[PATCH v2] Mention that password could be a personal access token.

[M Hickford via GitGitGadget]

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

These days, the 'password' for a software forge might be personal access
token or OAuth access token. These are popular, so worth clarifying that
Git treats them just the same.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    Mention that password could be a personal access token.
    
    These days, the 'password' for a software forge might be personal access
    token or OAuth access token.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1396%2Fhickford%2Fmore-about-credentials-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1396/hickford/more-about-credentials-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1396

Range-diff vs v1:

 1:  fef359f533a < -:  ----------- Mention that password could be a personal access token.
 -:  ----------- > 1:  0bb69988ad7 Mention that password could be a personal access token.


 Documentation/gitcredentials.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 80517b4eb2c..402e067a6ca 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -21,6 +21,9 @@ in order to access a remote repository over HTTP. This manual describes
 the mechanisms Git uses to request these credentials, as well as some
 features to avoid inputting these credentials repeatedly.
 
+Some repositories accept multiple passwords, including personal access
+tokens and OAuth access tokens. Git handles all of these the same.
+
 REQUESTING CREDENTIALS
 ----------------------
 

base-commit: c03801e19cb8ab36e9c0d17ff3d5e0c3b0f24193
-- 
gitgitgadget

Re: [PATCH v2] Mention that password could be a personal access token.

[Eric Sunshine]

On Wed, Nov 2, 2022 at 6:36 AM M Hickford via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> These days, the 'password' for a software forge might be personal access
> token or OAuth access token. These are popular, so worth clarifying that
> Git treats them just the same.
>
> Signed-off-by: M Hickford <mirth.hickford@gmail.com>
> ---
> diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
> @@ -21,6 +21,9 @@ in order to access a remote repository over HTTP. This manual describes
>  the mechanisms Git uses to request these credentials, as well as some
>  features to avoid inputting these credentials repeatedly.
>
> +Some repositories accept multiple passwords, including personal access
> +tokens and OAuth access tokens. Git handles all of these the same.

I easily understood Ævar's point about these types of secrets all
being different names for a password, but I find the above change
rather confusing when it mentions "multiple passwords". That makes me
think I may need to somehow configure multiple passwords for a site
(even though I know that's not what you meant).

How about a different approach, calling it a "secret" first, and then
defining "secret" as different names for "password". Perhaps something
like this:

    Git will sometimes need credentials from the user in order to
    perform operations; for example, it may need to ask for a username
    and secret in order to access a remote repository over HTTP.  The
    secret may be a password, passcode, personal access token, OAuth
    access token, etc.  This manual describes the mechanisms Git uses
    to request these credentials, as well as some features to avoid
    inputting these credentials repeatedly.

Re: [PATCH v2] Mention that password could be a personal access token.

[Junio C Hamano]

On Wed, Nov 2, 2022 at 3:55 AM Eric Sunshine <sunshine@sunshineco.com> wrote:
>
> How about a different approach, calling it a "secret" first, and then
> defining "secret" as different names for "password".

Or more directly, say "password" and parenthetically add that some hosting
sites may call it with different names like "personal tokens"?

Re: [PATCH v2] Mention that password could be a personal access token.

[Eric Sunshine]

On Wed, Nov 2, 2022 at 11:45 AM Junio C Hamano <gitster@pobox.com> wrote:
> On Wed, Nov 2, 2022 at 3:55 AM Eric Sunshine <sunshine@sunshineco.com> wrote:
> > How about a different approach, calling it a "secret" first, and then
> > defining "secret" as different names for "password".
>
> Or more directly, say "password" and parenthetically add that some hosting
> sites may call it with different names like "personal tokens"?

I tried the parenthetical approach first but the sentence structure
became too complex and more difficult to understand. Having a separate
sentence helped simplify. That said, perhap something like this?

    Git will sometimes need credentials from the user in order to
    perform operations; for example, it may need to ask for a username
    and password in order to access a remote repository over HTTP.  In
    place of a password, some sites may instead provide a passcode,
    personal access token, OAuth access token, etc.  This manual...

Re: [PATCH v2] Mention that password could be a personal access token.

[Philip Oakley]

On 02/11/2022 15:51, Eric Sunshine wrote:
> On Wed, Nov 2, 2022 at 11:45 AM Junio C Hamano <gitster@pobox.com> wrote:
>> On Wed, Nov 2, 2022 at 3:55 AM Eric Sunshine <sunshine@sunshineco.com> wrote:
>>> How about a different approach, calling it a "secret" first, and then
>>> defining "secret" as different names for "password".
>> Or more directly, say "password" and parenthetically add that some hosting
>> sites may call it with different names like "personal tokens"?
> I tried the parenthetical approach first but the sentence structure
> became too complex and more difficult to understand. Having a separate
> sentence helped simplify. That said, perhap something like this?
>
>     Git will sometimes need credentials from the user in order to
>     perform operations; for example, it may need to ask for a username
>     and password in order to access a remote repository over HTTP.  In

Perhaps s/password/secret 'password'/ here 9above0, and then talk about
the names for that "secret" in the follow up sentence below.
>     place of a password, some sites may instead provide a passcode,
>     personal access token, OAuth access token, etc.  This manual...
--
Philip

Re: [PATCH v2] Mention that password could be a personal access token.

[M Hickford]

On Wed, 2 Nov 2022 at 15:45, Junio C Hamano <gitster@pobox.com> wrote:
>
> Or more directly, say "password" and parenthetically add that some hosting
> sites may call it with different names like "personal tokens"?

Right, Git asks for a "password", but the user might enter a personal
access token instead.

[PATCH v3] Mention that password could be a personal access token.

[M Hickford via GitGitGadget]

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

Git asks for a "password", but the user might use a
personal access token or OAuth access token instead.

Example:

    Password for 'https://AzureDiamond@github.com':

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    Mention that password could be a personal access token.
    
    These days, the 'password' for a software forge might be personal access
    token or OAuth access token.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1396%2Fhickford%2Fmore-about-credentials-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1396/hickford/more-about-credentials-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1396

Range-diff vs v2:

 1:  0bb69988ad7 ! 1:  7be4a631aca Mention that password could be a personal access token.
     @@ Metadata
       ## Commit message ##
          Mention that password could be a personal access token.
      
     -    These days, the 'password' for a software forge might be personal access
     -    token or OAuth access token. These are popular, so worth clarifying that
     -    Git treats them just the same.
     +    Git asks for a "password", but the user might use a
     +    personal access token or OAuth access token instead.
     +
     +    Example:
     +
     +        Password for 'https://AzureDiamond@github.com':
      
          Signed-off-by: M Hickford <mirth.hickford@gmail.com>
      
       ## Documentation/gitcredentials.txt ##
     -@@ Documentation/gitcredentials.txt: in order to access a remote repository over HTTP. This manual describes
     - the mechanisms Git uses to request these credentials, as well as some
     - features to avoid inputting these credentials repeatedly.
     +@@ Documentation/gitcredentials.txt: DESCRIPTION
     + 
     + Git will sometimes need credentials from the user in order to perform
     + operations; for example, it may need to ask for a username and password
     +-in order to access a remote repository over HTTP. This manual describes
     +-the mechanisms Git uses to request these credentials, as well as some
     +-features to avoid inputting these credentials repeatedly.
     ++in order to access a remote repository over HTTP. Some remotes accept
     ++a personal access token or OAuth access token as a password. This
     ++manual describes the mechanisms Git uses to request these credentials,
     ++as well as some features to avoid inputting these credentials repeatedly.
       
     -+Some repositories accept multiple passwords, including personal access
     -+tokens and OAuth access tokens. Git handles all of these the same.
     -+
       REQUESTING CREDENTIALS
       ----------------------
     - 


 Documentation/gitcredentials.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 80517b4eb2c..6df50e8a144 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -17,9 +17,10 @@ DESCRIPTION
 
 Git will sometimes need credentials from the user in order to perform
 operations; for example, it may need to ask for a username and password
-in order to access a remote repository over HTTP. This manual describes
-the mechanisms Git uses to request these credentials, as well as some
-features to avoid inputting these credentials repeatedly.
+in order to access a remote repository over HTTP. Some remotes accept
+a personal access token or OAuth access token as a password. This
+manual describes the mechanisms Git uses to request these credentials,
+as well as some features to avoid inputting these credentials repeatedly.
 
 REQUESTING CREDENTIALS
 ----------------------

base-commit: 3b08839926fcc7cc48cf4c759737c1a71af430c1
-- 
gitgitgadget

Re: [PATCH v3] Mention that password could be a personal access token.

[Taylor Blau]

On Tue, Nov 08, 2022 at 01:01:27PM +0000, M Hickford via GitGitGadget wrote:
> From: M Hickford <mirth.hickford@gmail.com>
>
> Git asks for a "password", but the user might use a
> personal access token or OAuth access token instead.

Looks good to me. The only minor issue I noticed was that the commit
message should have been prefixed with an area but wasn't.

I changed it to the following when queueing:

    Documentation/gitcredentials.txt: mention password alternatives

Thank you for your work. Let's start merging this one down.

Thanks,
Taylor