doc: gitcredentials: introduce OAuth helpers
PATCH 1/1 doc: gitcredentials: introduce OAuth helpers
From: M Hickford <[email protected]>
OAuth credential helpers are widely useful but work differently to other credential helpers, so worth introducing in the docs.
Link to relevant projects.
---
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(+)
Documentation/gitcredentials.txt +13 -0
@@ -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
Signature · 1 line
gitgitgadget
Quoted 6 lines · M Hickford via GitGitGadget
From: M Hickford <[email protected]>
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).
Signature · 2 lines
brian m. carlson (he/him or they/them) Toronto, Ontario, CA
Quoted 7 lines · brian m. carlson
Quoted 5 lines · M Hickford via GitGitGadget
From: M Hickford <[email protected]>
OAuth credential helpers are widely useful but work differently to other credential helpers, so worth introducing in the docs.
Quoted 6 lines
Quoted 1 line
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
Quoted 6 lines
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".
Quoted 3 lines
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
Quoted 3 lines
--
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA
Quoted 6 lines
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.
PATCH v2 1/1 doc: gitcredentials: link to helper list
In reply to M Hickford via GitGitGadgetFrom: M Hickford <[email protected]>
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.
---
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 <[email protected]>
## 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.
## 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(+)
Documentation/gitcredentials.txt +12 -0
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH v2] doc: gitcredentials: link to helper list
Quoted 9 lines · M Hickford via GitGitGadget
From: M Hickford <[email protected]>
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...
Documentation/gitcredentials.txt $ git help credential-foo · line 111
Quoted 13 lines
Documentation/gitcredentials.txt +5
-0@@ -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:
Documentation/gitcredentials.txt +2 -3
@@ -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
PATCH v3 1/1 doc: gitcredentials: link to helper list
In reply to M Hickford via GitGitGadgetFrom: M Hickford <[email protected]>
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.
---
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(+)
Documentation/gitcredentials.txt +11 -0
@@ -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
Signature · 1 line
gitgitgadget