No more passwords! No more personal access tokens! No more SSH keys!
git-credential-oauth is a Git credential helper that securely authenticates to GitHub, GitLab, BitBucket and Gerrit using OAuth.
The first time you authenticate, the helper opens a browser window to the host. Subsequent authentication within storage lifetime is non interactive.
This is a fork of the git-credential-oauth to make it work with ide's in our product Conveyor. We want to support the following git repositories:
- azure devops (created a custom implementation: we will contribute this back to the main project if they want it)
- gitlab
- github
- bitbucket
Additionally, we made a couple of changes to make it easier to work for us:
- We want the redirect URL's to go to our control plane API such that we can forward them to the correct ide.
- We want to support overwriting the config through environment variables instead of only git config (easier to manage with kubernetes pods)
Git assumes users can type a password from memory, but hosts such as GitHub no longer accept passwords without two-factor authentication. Personal access tokens are easy enough to copy and paste but awkward to store securely. git-credential-cache works well for passwords but not personal access tokens because the token is lost when the cache expires. All in all, the usability is so poor that the most popular advice on StackOverflow is to insecurely save credentials in plaintext!
OAuth has multiple advantages over personal access tokens or SSH:
| Advantage | OAuth | Personal access token | SSH |
|---|---|---|---|
| Clone public repo without setup | ✓ | ✓ | 🗙 |
| Authenticate to popular hosts without setup | ✓ | 🗙 | 🗙 |
| Server authenticity verified automatically | ✓ | ✓ | 🗙 |
| Protections against token theft1 | ✓ | 🗙 | only if key has passphrase |
Download binary from https://github.com/hickford/git-credential-oauth/releases.
Then test that Git can find the application:
git credential-oauth
If you have problems, make sure that the binary is located in the path and is executable.
Several Linux distributions include a git-credential-oauth package including Fedora, Debian and Ubuntu.
macOS users can install from Homebrew:
brew install git-credential-oauth
macOS users can alternatively install via MacPorts:
sudo port install git-credential-oauth
Go users can install the latest release to ~/go/bin with:
go install github.com/hickford/git-credential-oauth@latest
As a convenience, you can run:
git credential-oauth configureThis uses the recommended config below.
Git is cleverly designed to support multiple credential helpers. To fill credentials, Git calls each helper in turn until it has the information it needs. git-credential-oauth is a read-only credential-generating helper, designed to be configured in combination with a storage helper.
To configure together with git-credential-cache:
git config --global --unset-all credential.helper
git config --global --add credential.helper "cache --timeout 7200" # two hours
git config --global --add credential.helper oauthYou may choose a different storage helper such as osxkeychain, wincred or libsecret, but git-credential-oauth must be configured last. This ensures Git checks for stored credentials before generating new credentials.
Windows users must use storage helper wincred because git-credential-cache isn't available on Windows.
Edit your global git config ~/.gitconfig to include the following lines:
[credential]
helper = cache --timeout 7200 # two hours
helper = oauthEdit ~/.gitconfig manually, or run:
git config --global --unset-all credential.helper oauth
Register an Oauth application on the git repository: * specify name: conveyor ide * specify redirect url: https://app.conveyordata.com/api/v2/ide/callback (or another cp-tenant when working on stg) * Define the scopes: read, write permissions to git repo and potentially email address of the user
Go to the following urls to create these applications:
- https://dev.azure.com/datamindedbe/_usersSettings/authorizations
- Normally everyone has access to the azure devops organization
- https://github.com/settings/developers
- I will transfer the oauth application to the datamindedbe organisation, so only admins of the organisation will be able to edit this
Put the credentials in ssm as a secure string.
The git-credential oauth tool supports 2 way to overwrite default Oauth configuration, namely:
- git config (as described in next section)
- environment variables
To specify the Oauth config for ides, you can use the following env variables:
export GC_OAUTH_<gitRepoName>_CLIENT_ID=<some-client-id>
export GC_OAUTH_<gitRepoName>_CLIENT_SECRET=<some-client-id>
export GC_OAUTH_<gitRepoName>_CLIENT_AUTH_URL=/oauth/authorize
export GC_OAUTH_<gitRepoName>_CLIENT_TOKEN_URL=/oauth/token
export GC_OAUTH_<gitRepoName>_SCOPES=<1 or more scopes separated by spaces>where gitRepoName is one of: GITLAB, GITHUB, BITBUCKET, DEVOPS at the moment
Note:
For the cloud based git repositories gitlab, github, bitbucket, azure devops, we included the auth and token urls.
When specifying them as environment variables, you only need to add the suffix (e.g. oauth/authorize) as this will be appended after the base url in your git clone command.
Additionally, the tool relies on the CONVEYOR_IDE_URL and the CONVEYOR_API_URL env variables to detect it is running in an ide to construct the correct callback url.
This is important because the callback-/redirectUrl defined by the git-credential-oauth tool should match exactly with the url defined when creating your oauth application.
To use with a custom host, eg. gitlab.example.com:
- Register an OAuth application on the host. The GitLab instructions are typical.
- Specify name
git-credential-oauth - Specify redirect URI
http://127.0.0.1. - Select scopes for read and write Git operations.
- Specify name
- Adjust the config commands below with the generated client id and space-separated scopes.
- Share the config commands with colleagues so they can skip the registration step.
git config --global credential.https://gitlab.example.com.oauthClientId <CLIENTID>
git config --global credential.https://gitlab.example.com.oauthScopes read_repository write_repository
git config --global credential.https://gitlab.example.com.oauthAuthURL /oauth/authorize
git config --global credential.https://gitlab.example.com.oauthTokenURL /oauth/tokenWould you like to see universal GitLab support? *Vote for GitLab issue #374172.
- Do one thing well, namely OAuth authentication.
- Interoperate with other credential helpers.
- Contribute upstream to improve the ecosystem.
Git Credential Manager (GCM) is an excellent credential helper with broader functionality. However because it's developed in .NET, GCM is prohibitively difficult for Linux distributions to package.
| Git Credential Manager | git-credential-oauth | |
|---|---|---|
| Cross platform | ✓ | ✓ |
| Linux arm64 support | 🗙 | ✓ |
| Packaged in Linux distributions | 🗙 | ✓ Many |
| Installation size (Linux) | 82 MB | 5 MB |
| Installation size (Windows) | 4 MB | 5 MB |
| Ships with Git for Windows | ✓ | 🗙 |
| Credential storage | In built | Used together with any storage helper |
| Development | .NET | Go |
| Lines of code | 40,000 | 400 |
| Minimum HTTP requests | 1 | 0 |
| Authentication to Azure DevOps | ✓ | 🗙 |
| Hosts with default config | 4 | 12 |
The maintainer personally uses GCM on Windows and git-credential-oauth on Linux.
Install locally with go install ..
Use the -verbose flag to print more details:
git config --global --unset-all credential.helper oauth
git config --global --add credential.helper "oauth -verbose"You can also test git-credential-oauth in isolation:
echo host=gitlab.com\nprotocol=https | git-credential-oauth -verbose get
You can test configured helpers in combination with git credential fill, eg.
echo url=https://gitlab.com | git credential fill
To see which helpers Git calls, set export GIT_TRACE=1.
This is not an officially supported Google product.
Footnotes
-
Scenario: an old disk backup is leaked. ↩