[PATCH] doc: gitcredentials: introduce OAuth helpers

Git Mailing List Archive mirror
 help / color / mirror / Atom feed

* [PATCH] doc: gitcredentials: introduce OAuth helpers
@ 2023-05-28 19:45 M Hickford via GitGitGadget
  2023-05-28 22:51 ` brian m. carlson
  2023-06-21  7:30 ` [PATCH v2] doc: gitcredentials: link to helper list M Hickford via GitGitGadget
  0 siblings, 2 replies; 7+ messages in thread
From: M Hickford via GitGitGadget @ 2023-05-28 19:45 UTC (permalink / raw)
  To: git
  Cc: peff, msuchanek, sandals, lessleydennington, me, mjcheetham,
	M Hickford, M Hickford

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

OAuth credential helpers are widely useful but work differently to other
credential helpers, so worth introducing in the docs.

Link to relevant projects.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    gitcredentials: describe OAuth credential helpers
    
    See also discussion
    https://lore.kernel.org/git/CAGJzqskaM80+8+79yUf435tP93Sk8sFu7marCvyimE=2gOKnog@mail.gmail.com/

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1538%2Fhickford%2Fhelpers-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1538/hickford/helpers-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1538

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

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 100f045bb1a..d2a7249d52b 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -105,6 +105,19 @@ $ git config --global credential.helper foo
 -------------------------------------------
 
 
+=== OAuth credential helpers
+
+An alternative to entering passwords or personal access tokens is to use an
+OAuth credential helper. Many popular Git hosts support OAuth. The first time
+you authenticate, the helper opens a browser window to the host.
+Subsequent authentication is non interactive.
+
+Two cross-platform open-source OAuth credential helpers are:
+
+* https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager]
+* https://github.com/hickford/git-credential-oauth[git-credential-oauth]
+
+
 CREDENTIAL CONTEXTS
 -------------------
 

base-commit: 79bdd48716a4c455bdc8ffd91d57a18d5cd55baa
-- 
gitgitgadget

^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH] doc: gitcredentials: introduce OAuth helpers
  2023-05-28 19:45 [PATCH] doc: gitcredentials: introduce OAuth helpers M Hickford via GitGitGadget
@ 2023-05-28 22:51 ` brian m. carlson
  2023-05-29  9:50   ` M Hickford
  2023-06-21  6:28   ` M Hickford
  2023-06-21  7:30 ` [PATCH v2] doc: gitcredentials: link to helper list M Hickford via GitGitGadget
  1 sibling, 2 replies; 7+ messages in thread
From: brian m. carlson @ 2023-05-28 22:51 UTC (permalink / raw)
  To: M Hickford via GitGitGadget
  Cc: git, peff, msuchanek, lessleydennington, me, mjcheetham,
	M Hickford

[-- Attachment #1: Type: text/plain, Size: 1143 bytes --]

On 2023-05-28 at 19:45:27, M Hickford via GitGitGadget wrote:
> From: M Hickford <mirth.hickford@gmail.com>
> 
> OAuth credential helpers are widely useful but work differently to other
> credential helpers, so worth introducing in the docs.
> 
> Link to relevant projects.

There are many possible implementations of credential helpers, and I'd
prefer we didn't specifically propose any of them here.  We ship with
some in contrib, and I think it would be better to fix them to be
functional for this use case rather than link to external projects.

I expect, however, that functionally, that will be difficult to do,
given the fact that OAuth typically requires registration with the
remote system, and thus we'd intrinsically be prioritizing some
well-known forges over less-known or personally-hosted forges, which
we've traditionally tried not to do.  For example, your
git-credential-oauth contains a hard-coded list of 11 forges (and also
proposes adding credentials for new ones into the config, which isn't
really a secure way to store secrets).
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] doc: gitcredentials: introduce OAuth helpers
  2023-05-28 22:51 ` brian m. carlson
@ 2023-05-29  9:50   ` M Hickford
  2023-06-21  6:28   ` M Hickford
  1 sibling, 0 replies; 7+ messages in thread
From: M Hickford @ 2023-05-29  9:50 UTC (permalink / raw)
  To: brian m. carlson, M Hickford via GitGitGadget, git, peff,
	msuchanek, lessleydennington, me, mjcheetham, M Hickford

On Sun, 28 May 2023 at 23:51, brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> On 2023-05-28 at 19:45:27, M Hickford via GitGitGadget wrote:
> > From: M Hickford <mirth.hickford@gmail.com>
> >
> > OAuth credential helpers are widely useful but work differently to other
> > credential helpers, so worth introducing in the docs.
> >
> > Link to relevant projects.
>
> There are many possible implementations of credential helpers, and I'd
> prefer we didn't specifically propose any of them here.  We ship with
> some in contrib, and I think it would be better to fix them to be
> functional for this use case rather than link to external projects.

Thanks Brian for your reply. I'd love to upstream OAuth functionality
in Git, but I think it'd be prohibitively difficult technically without
introducing extra dependencies. git-credential-oauth is little more
than 100 lines of Go, but it takes advantage of Go's broad standard
library and a library for OAuth. I expect that would require tens of
thousands of lines of challenging C.
https://github.com/hickford/git-credential-oauth/issues/8

I think OAuth is such a boon for usable security that it's worth
describing and linking to external projects. The text aims to inform
the user rather than tell them to use a particular project. An
alternative would be to link to a new 'credential helpers' page on
git-scm.com

>
> I expect, however, that functionally, that will be difficult to do,
> given the fact that OAuth typically requires registration with the
> remote system, and thus we'd intrinsically be prioritizing some
> well-known forges over less-known or personally-hosted forges, which
> we've traditionally tried not to do.  For example, your

In that spirit, the patch avoids naming "popular Git hosts".

> git-credential-oauth contains a hard-coded list of 11 forges (and also
> proposes adding credentials for new ones into the config, which isn't
> really a secure way to store secrets).

To clarify, it's expected that client credentials in OAuth native apps
(unlike web apps) are non-confidential. "It is assumed that any client
authentication credentials included in the application can be
extracted" https://datatracker.ietf.org/doc/html/rfc6749#section-2.1

> --
> brian m. carlson (he/him or they/them)
> Toronto, Ontario, CA

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] doc: gitcredentials: introduce OAuth helpers
  2023-05-28 22:51 ` brian m. carlson
  2023-05-29  9:50   ` M Hickford
@ 2023-06-21  6:28   ` M Hickford
  1 sibling, 0 replies; 7+ messages in thread
From: M Hickford @ 2023-06-21  6:28 UTC (permalink / raw)
  To: brian m. carlson, M Hickford via GitGitGadget, git, peff,
	msuchanek, lessleydennington, me, mjcheetham, M Hickford

> I expect, however, that functionally, that will be difficult to do,
> given the fact that OAuth typically requires registration with the
> remote system, and thus we'd intrinsically be prioritizing some
> well-known forges over less-known or personally-hosted forges, which
> we've traditionally tried not to do.  For example, your
> git-credential-oauth contains a hard-coded list of 11 forges

Forge diversity is my motivation! Consider the average Git user. They
contribute to several projects on GitHub. They are deterred from
contributing to worthy projects elsewhere by the setup cost of
configuring personal access tokens or SSH keys. To use five forges
from three machines, you have to generate 15 personal access tokens or
upload SSH keys 15 times. Whereas a git-credential-oauth user can
contribute to projects on many popular hosts without any setup. That's
progress surely.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v2] doc: gitcredentials: link to helper list
  2023-05-28 19:45 [PATCH] doc: gitcredentials: introduce OAuth helpers M Hickford via GitGitGadget
  2023-05-28 22:51 ` brian m. carlson
@ 2023-06-21  7:30 ` M Hickford via GitGitGadget
  2023-06-27  8:21   ` Jeff King
  2023-07-08 20:36   ` [PATCH v3] " M Hickford via GitGitGadget
  1 sibling, 2 replies; 7+ messages in thread
From: M Hickford via GitGitGadget @ 2023-06-21  7:30 UTC (permalink / raw)
  To: git
  Cc: peff, msuchanek, sandals, lessleydennington, me, mjcheetham,
	M Hickford, M Hickford

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

Link to community list of credential helpers. This is useful information
for users.

Describe how OAuth credential helpers work. OAuth is a user-friendly
alternative to personal access tokens and SSH keys. Reduced setup cost
makes it easier for users to contribute to projects across multiple
forges.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    gitcredentials: link to list of helpers
    
    Add link to list of helpers

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1538%2Fhickford%2Fhelpers-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1538/hickford/helpers-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1538

Range-diff vs v1:

 1:  49e2a6fc9f2 ! 1:  26818290468 doc: gitcredentials: introduce OAuth helpers
     @@ Metadata
      Author: M Hickford <mirth.hickford@gmail.com>
      
       ## Commit message ##
     -    doc: gitcredentials: introduce OAuth helpers
     +    doc: gitcredentials: link to helper list
      
     -    OAuth credential helpers are widely useful but work differently to other
     -    credential helpers, so worth introducing in the docs.
     +    Link to community list of credential helpers. This is useful information
     +    for users.
      
     -    Link to relevant projects.
     +    Describe how OAuth credential helpers work. OAuth is a user-friendly
     +    alternative to personal access tokens and SSH keys. Reduced setup cost
     +    makes it easier for users to contribute to projects across multiple
     +    forges.
      
          Signed-off-by: M Hickford <mirth.hickford@gmail.com>
      
       ## Documentation/gitcredentials.txt ##
     -@@ Documentation/gitcredentials.txt: $ git config --global credential.helper foo
     +@@ Documentation/gitcredentials.txt: $ git help credential-foo
     + $ git config --global credential.helper foo
       -------------------------------------------
       
     - 
     -+=== OAuth credential helpers
     -+
     -+An alternative to entering passwords or personal access tokens is to use an
     -+OAuth credential helper. Many popular Git hosts support OAuth. The first time
     -+you authenticate, the helper opens a browser window to the host.
     -+Subsequent authentication is non interactive.
     -+
     -+Two cross-platform open-source OAuth credential helpers are:
     ++=== Available helpers
      +
     -+* https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager]
     -+* https://github.com/hickford/git-credential-oauth[git-credential-oauth]
     ++The community maintains a comprehensive
     ++https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
     ++available.
      +
     ++=== OAuth
      +
     ++An alternative to inputting passwords or personal access tokens is to use an
     ++OAuth credential helper. Initial authentication opens a browser window to the
     ++host. Subsequent authentication happens in the background. Many popular Git
     ++hosts support OAuth.
     + 
       CREDENTIAL CONTEXTS
       -------------------
     - 


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

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 100f045bb1a..a266870a042 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -104,6 +104,18 @@ $ git help credential-foo
 $ git config --global credential.helper foo
 -------------------------------------------
 
+=== Available helpers
+
+The community maintains a comprehensive
+https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
+available.
+
+=== OAuth
+
+An alternative to inputting passwords or personal access tokens is to use an
+OAuth credential helper. Initial authentication opens a browser window to the
+host. Subsequent authentication happens in the background. Many popular Git
+hosts support OAuth.
 
 CREDENTIAL CONTEXTS
 -------------------

base-commit: 79bdd48716a4c455bdc8ffd91d57a18d5cd55baa
-- 
gitgitgadget

^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH v2] doc: gitcredentials: link to helper list
  2023-06-21  7:30 ` [PATCH v2] doc: gitcredentials: link to helper list M Hickford via GitGitGadget
@ 2023-06-27  8:21   ` Jeff King
  2023-07-08 20:36   ` [PATCH v3] " M Hickford via GitGitGadget
  1 sibling, 0 replies; 7+ messages in thread
From: Jeff King @ 2023-06-27  8:21 UTC (permalink / raw)
  To: M Hickford via GitGitGadget
  Cc: git, msuchanek, sandals, lessleydennington, me, mjcheetham,
	M Hickford

On Wed, Jun 21, 2023 at 07:30:24AM +0000, M Hickford via GitGitGadget wrote:

> From: M Hickford <mirth.hickford@gmail.com>
> 
> Link to community list of credential helpers. This is useful information
> for users.
> 
> Describe how OAuth credential helpers work. OAuth is a user-friendly
> alternative to personal access tokens and SSH keys. Reduced setup cost
> makes it easier for users to contribute to projects across multiple
> forges.

Kind of seems like two topics in one patch, but OK.

I don't have much of an opinion on either topic, but...

> diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
> index 100f045bb1a..a266870a042 100644
> --- a/Documentation/gitcredentials.txt
> +++ b/Documentation/gitcredentials.txt
> @@ -104,6 +104,18 @@ $ git help credential-foo
>  $ git config --global credential.helper foo
>  -------------------------------------------
>  
> +=== Available helpers
> +
> +The community maintains a comprehensive
> +https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
> +available.

I'd note that full hyperlinks like this are kind of lousy in the manpage
builds. You get:

     Available helpers
	The community maintains a comprehensive list of Git credential
	helpers[1] available.

in the text, and then way down at the bottom of the manpage:

  NOTES
	1. list of Git credential helpers
	   https://git-scm.com/doc/credential-helpers

Something like:

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index fd5ecede13..1c7d302f18 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -106,9 +106,8 @@ $ git config --global credential.helper foo
 
 === Available helpers
 
-The community maintains a comprehensive
-https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
-available.
+The community maintains a comprehensive list of Git credential helpers
+at https://git-scm.com/doc/credential-helpers.
 
 === OAuth
 

yields nicer text in the manpage, and asciidoc is smart enough to turn
it into a hyperlink in the html version.

-Peff

^ permalink raw reply related	[flat|nested] 7+ messages in thread

* [PATCH v3] doc: gitcredentials: link to helper list
  2023-06-21  7:30 ` [PATCH v2] doc: gitcredentials: link to helper list M Hickford via GitGitGadget
  2023-06-27  8:21   ` Jeff King
@ 2023-07-08 20:36   ` M Hickford via GitGitGadget
  1 sibling, 0 replies; 7+ messages in thread
From: M Hickford via GitGitGadget @ 2023-07-08 20:36 UTC (permalink / raw)
  To: git
  Cc: peff, msuchanek, sandals, lessleydennington, me, mjcheetham,
	M Hickford, M Hickford

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

Link to community list of credential helpers. This is useful information
for users.

Describe how OAuth credential helpers work. OAuth is a user-friendly
alternative to personal access tokens and SSH keys. Reduced setup cost
makes it easier for users to contribute to projects across multiple
forges.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    gitcredentials: link to list of helpers
    
    Add link to list of helpers

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1538%2Fhickford%2Fhelpers-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1538/hickford/helpers-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1538

Range-diff vs v2:

 1:  26818290468 ! 1:  a6265156eed doc: gitcredentials: link to helper list
     @@ Documentation/gitcredentials.txt: $ git help credential-foo
       
      +=== Available helpers
      +
     -+The community maintains a comprehensive
     -+https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
     -+available.
     ++The community maintains a comprehensive list of Git credential helpers at
     ++https://git-scm.com/doc/credential-helpers.
      +
      +=== OAuth
      +


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

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 65d652dc40e..71dd19731af 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -104,6 +104,17 @@ $ git help credential-foo
 $ git config --global credential.helper foo
 -------------------------------------------
 
+=== Available helpers
+
+The community maintains a comprehensive list of Git credential helpers at
+https://git-scm.com/doc/credential-helpers.
+
+=== OAuth
+
+An alternative to inputting passwords or personal access tokens is to use an
+OAuth credential helper. Initial authentication opens a browser window to the
+host. Subsequent authentication happens in the background. Many popular Git
+hosts support OAuth.
 
 CREDENTIAL CONTEXTS
 -------------------

base-commit: 061c58647eb4b3f0e2c898333577d4b2af115b1d
-- 
gitgitgadget

^ permalink raw reply related	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2023-07-08 20:37 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-05-28 19:45 [PATCH] doc: gitcredentials: introduce OAuth helpers M Hickford via GitGitGadget
2023-05-28 22:51 ` brian m. carlson
2023-05-29  9:50   ` M Hickford
2023-06-21  6:28   ` M Hickford
2023-06-21  7:30 ` [PATCH v2] doc: gitcredentials: link to helper list M Hickford via GitGitGadget
2023-06-27  8:21   ` Jeff King
2023-07-08 20:36   ` [PATCH v3] " M Hickford via GitGitGadget

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).