How to authenticate git

How to authenticate git

Check your version of git by running

SYNOPSIS

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.

REQUESTING CREDENTIALS

Without any credential helpers defined, Git will try the following strategies to ask the user for usernames and passwords:

If the GIT_ASKPASS environment variable is set, the program specified by the variable is invoked. A suitable prompt is provided to the program on the command line, and the user’s input is read from its standard output.

Otherwise, if the core.askPass configuration variable is set, its value is used as above.

Otherwise, if the SSH_ASKPASS environment variable is set, its value is used as above.

Otherwise, the user is prompted on the terminal.

AVOIDING REPETITION

It can be cumbersome to input the same credentials over and over. Git provides two methods to reduce this annoyance:

Static configuration of usernames for a given authentication context.

Credential helpers to cache or store passwords, or to interact with a system password wallet or keychain.

The first is simple and appropriate if you do not have secure storage available for a password. It is generally configured by adding this to your config:

Credential helpers, on the other hand, are external programs from which Git can request both usernames and passwords; they typically interface with secure storage provided by the OS or other programs.

To use a helper, you must first select one to use. Git currently includes the following helpers:

Cache credentials in memory for a short period of time. See git-credential-cache[1] for details.

Store credentials indefinitely on disk. See git-credential-store[1] for details.

Read its description.

Tell Git to use it.

CREDENTIAL CONTEXTS

Git considers each credential to have a context defined by a URL. This context is used to look up context-specific configuration, and is passed to any helpers, which may use it as an index into secure storage.

then we will match: both protocols are the same, both hosts are the same, and the «pattern» URL does not care about the path component at all. However, this context would not match:

CONFIGURATION OPTIONS

The following options are available in either location:

If there are multiple instances of the credential.helper configuration variable, each helper will be tried in turn, and may provide a username, password, or nothing. Once Git has acquired both a username and a password, no more helpers will be tried.

If credential.helper is configured to the empty string, this resets the helper list to empty (so you may override a helper set by a lower-priority config file by configuring the empty-string helper, followed by whatever set of helpers you would like).

A default username, if one is not provided in the URL.

CUSTOM HELPERS

You can write your own custom helpers to interface with any system in which you keep credentials.

Credential helpers are programs executed by Git to fetch or save credentials from and to long-term storage (where «long-term» is simply longer than a single Git process; e.g., credentials may be stored in-memory for a few minutes, or indefinitely on disk).

Each helper is specified by a single string in the configuration variable credential.helper (and others, see git-config[1]). The string is transformed by Git into a command to be executed using these rules:

If the helper string begins with «!», it is considered a shell snippet, and everything after the «!» becomes the command.

Otherwise, if the helper string begins with an absolute path, the verbatim helper string becomes the command.

Otherwise, the string «git credential-» is prepended to the helper string, and the result becomes the command.

The resulting command then has an «operation» argument appended to it (see below for details), and the result is executed by the shell.

Here are some example specifications:

When a helper is executed, it will have one «operation» argument appended to its command line, which is one of:

Return a matching credential, if any exists.

Store the credential, if applicable to the helper.

Remove a matching credential, if any, from the helper’s storage.

The details of the credential will be provided on the helper’s stdin stream. The exact format is the same as the input/output format of the git credential plumbing command (see the section INPUT/OUTPUT FORMAT in git-credential[1] for a detailed specification).

For a get operation, the helper should produce a list of attributes on stdout in the same format (see git-credential[1] for common attributes). A helper is free to produce a subset, or even no values at all if it has nothing useful to provide. Any provided attributes will overwrite those already known about by Git’s credential subsystem.

While it is possible to override all attributes, well behaving helpers should refrain from doing so for any attribute other than username and password.

Similarly, no more helpers will be consulted once both username and password had been provided.

For a store or erase operation, the helper’s output is ignored.

If a helper fails to perform the requested operation or needs to notify the user of a potential issue, it may write to stderr.

If it does not support the requested operation (e.g., a read-only store), it should silently ignore the request.

If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older helpers will just ignore the new requests).

Accessing GitHub using two-factor authentication

In this article

With 2FA enabled, you’ll be asked to provide your 2FA authentication code, as well as your password, when you sign in to GitHub.

With two-factor authentication enabled, you’ll need to provide an authentication code when accessing GitHub through your browser. If you access GitHub using other methods, such as the API or the command line, you’ll need to use an alternative form of authentication. For more information, see «About authentication to GitHub.»

Providing a 2FA code when signing in to the website

After you sign in to GitHub using your password, you’ll be prompted to provide an authentication code from a text message or your TOTP app.

GitHub will only ask you to provide your 2FA authentication code again if you’ve logged out, are using a new device, or your session expires.

Generating a code through a TOTP application

If you chose to set up two-factor authentication using a TOTP application on your smartphone, you can generate an authentication code for GitHub at any time. In most cases, just launching the application will generate a new code. You should refer to your application’s documentation for specific instructions.

If you delete the mobile application after configuring two-factor authentication, you’ll need to provide your recovery code to get access to your account. For more information, see «Recovering your account if you lose your two-factor authentication credentials»

Receiving a text message

If you set up two-factor authentication via text messages, GitHub will send you a text message with your authentication code.

Verifying with GitHub Mobile

If you have installed and signed in to GitHub Mobile, you may choose to authenticate with GitHub Mobile for two-factor authentication.

Sign in to GitHub with your browser, using your username and password.

If you have added a security key to your account, you’ll first be prompted to insert and use a security key. To skip using a security key, click Authenticate with GitHub Mobile.

GitHub will send you a push notification to verify your sign in attempt. Opening the push notification or opening the GitHub Mobile app will display a prompt, asking you to approve or reject this sign in attempt.

Note: This prompt may require you to enter a two-digit number displayed within the browser you are signing in to.

Using two-factor authentication with the command line

After you’ve enabled 2FA, you will no longer use your password to access GitHub on the command line. Instead, use Git Credential Manager, a personal access token, or an SSH key.

Authenticating on the command line using Git Credential Manager

Git Credential Manager is a secure Git credential helper that runs on Windows, macOS, and Linux. For more information about Git credential helpers, see Avoiding repetition in the Pro Git book.

Setup instructions vary based on your computer’s operating system. For more information, see Download and install in the GitCredentialManager/git-credential-manager repository.

Authenticating on the command line using HTTPS

After you’ve enabled 2FA, you must create a personal access token to use as a password when authenticating to GitHub on the command line using HTTPS URLs.

When prompted for a username and password on the command line, use your GitHub username and personal access token. The command line prompt won’t specify that you should enter your personal access token when it asks for your password.

Authenticating on the command line using SSH

Enabling 2FA doesn’t change how you authenticate to GitHub on the command line using SSH URLs. For more information about setting up and using an SSH key, see «Connecting to GitHub with SSH.»

Using two-factor authentication to access a repository using Subversion

When you access a repository via Subversion, you must provide a personal access token instead of entering your password. For more information, see «Creating a personal access token.»

If you lose access to your two-factor authentication credentials, you can use your recovery codes or another recovery method (if you’ve set one up) to regain access to your account. For more information, see «Recovering your account if you lose your 2FA credentials.»

If your authentication fails several times, you may wish to synchronize your phone’s clock with your mobile provider. Often, this involves checking the «Set automatically» option on your phone’s clock, rather than providing your own time zone.

Set up Git

In this article

At the heart of GitHub is an open source version control system (VCS) called Git. Git is responsible for everything GitHub-related that happens locally on your computer.

To use Git on the command line, you will need to download, install, and configure Git on your computer. You can also install GitHub CLI to use GitHub from the command line. For more information, see «About GitHub CLI.»

If you want to work with Git locally, but do not want to use the command line, you can instead download and install the GitHub Desktop client. For more information, see «Installing and configuring GitHub Desktop.»

If you do not need to work with files locally, GitHub lets you complete many Git-related actions directly in the browser, including:

Note: If you are using a Chrome OS device, additional set up is required:

Authenticating with GitHub from Git

When you connect to a GitHub repository from Git, you will need to authenticate with GitHub using either HTTPS or SSH.

Connecting over HTTPS (recommended)

If you clone with HTTPS, you can cache your GitHub credentials in Git using a credential helper. For more information, see «Cloning with HTTPS urls» and «Caching your GitHub credentials in Git.»

Connecting over SSH

If you clone with SSH, you must generate SSH keys on each computer you use to push or pull from GitHub. For more information, see «Cloning with SSH urls» and «Generating a new SSH key.»

You now have Git and GitHub all set up. You may now choose to create a repository where you can put your projects. Saving your code in a repository allows you to back up your code and share it around the world.

Creating a repository for your project allows you to store code in GitHub. This provides a backup of your work that you can choose to share with other developers. For more information, see “Create a repository.».

Forking a repository will allow you to make changes to another repository without affecting the original. For more information, see «Fork a repository.»

Each repository on GitHub is owned by a person or an organization. You can interact with the people, repositories, and organizations by connecting and following them on GitHub. For more information, see «Be social.»

GitHub has a great support community where you can ask for help and talk to people from around the world. Join the conversation on GitHub Community.

Help us make these docs great!

All GitHub docs are open source. See something that’s wrong or unclear? Submit a pull request.

Authentication overview

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

Choose a method to securely access the code in Azure Repos, Azure DevOps Server 2019, or Team Foundation Server (TFS) Git repositories. Use these credentials with Git at a command prompt. These credentials also work with any Git client that supports HTTPS or SSH authentication. Limit the scope of access and revoke these credentials when they’re no longer needed.

Azure DevOps no longer supports Alternate Credentials authentication since the beginning of March 2, 2020. If you’re still using Alternate Credentials, we strongly encourage you to switch to a more secure authentication method (for example, personal access tokens). Learn more.

Azure DevOps Server was formerly named Visual Studio Team Foundation Server.

Using Visual Studio? Team Explorer handles authentication with Azure Repos for you.

Visual Studio 2019 version 16.8 and later versions provide a new Git menu for managing the Git workflow with less context switching than Team Explorer. Procedures provided in this article under the Visual Studio 2019 tab provide information for using the Git experience as well as Team Explorer. To learn more, see Side-by-side comparison of Git and Team Explorer.

Authentication comparison

Personal access tokens

Personal access tokens (PATs) give you access to Azure DevOps and Team Foundation Server (TFS), without using your username and password directly. These tokens have an expiration date from when they’re created. You can restrict the scope of the data they can access. Use PATs to authenticate if you don’t already have SSH keys set up on your system or if you need to restrict the permissions that are granted by the credential.

Use Git Credential Manager to generate tokens

The Git Credential Manager is an optional tool that makes it easy to create PATs when you’re working with Azure Repos. Sign in to the web portal, generate a token, and then use the token as your password when you’re connecting to Azure Repos.

PATs are generated on demand when you have the credential manager installed. The credential manager creates the token in Azure DevOps and saves it locally for use with the Git command line or other client.

Current versions of Git for Windows include the Git credential manager as an optional feature during installation.

SSH key authentication

Key authentication with SSH works through a public and private key pair that you create on your computer. You associate the public key with your username from the web. Azure DevOps will encrypt the data sent to you with that key when you work with Git. You decrypt the data on your computer with the private key, which is never shared or sent over the network.

OAuth

Use OAuth to generate tokens for accessing REST APIs. The Accounts and Profiles APIs support only OAuth.

Basics of authentication

In this article

Learn about the different ways to authenticate with some examples.

In this section, we’re going to focus on the basics of authentication. Specifically, we’re going to create a Ruby server (using Sinatra) that implements the web flow of an application in several different ways.

You can download the complete source code for this project from the platform-samples repo.

Registering your app

First, you’ll need to register your application. Every registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared! That includes checking the string into your repository.

You can fill out every piece of information however you like, except the Authorization callback URL. This is easily the most important piece to setting up your application. It’s the callback URL that GitHub returns the user to after successful authentication.

Accepting user authorization

Deprecation Notice: GitHub will discontinue authentication to the API using query parameters. Authenticating to the API should be done with HTTP basic authentication. Using query parameters to authenticate to the API will no longer work on May 5, 2021. For more information, including scheduled brownouts, see the blog post.

Now, let’s start filling out our simple server. Create a file called server.rb and paste this into it:

Your client ID and client secret keys come from your application’s configuration page. You should never, ever store these values in GitHub—or any other public place, for that matter. We recommend storing them as environment variables—which is exactly what we’ve done here.

Next, in views/index.erb, paste this content:

(If you’re unfamiliar with how Sinatra works, we recommend reading the Sinatra guide.)

Also, notice that the URL uses the scope query parameter to define the scopes requested by the application. For our application, we’re requesting user:email scope for reading private email addresses.

If you trust yourself, click Authorize App. Wuh-oh! Sinatra spits out a 404 error. What gives?!

Providing a callback

In server.rb, add a route to specify what the callback should do:

Checking granted scopes

Users can edit the scopes you requested by directly changing the URL. This can grant your application less access than you originally asked for. Before making any requests with the token, check the scopes that were granted for the token by the user. For more information about requested and granted scopes, see «Scopes for OAuth Apps.»

The scopes that were granted are returned as a part of the response from exchanging a token.

In our application, we’re using scopes.include? to check if we were granted the user:email scope needed for fetching the authenticated user’s private email addresses. Had the application asked for other scopes, we would have checked for those as well.

Also, since there’s a hierarchical relationship between scopes, you should check that you were granted the lowest level of required scopes. For example, if the application had asked for user scope, it might have been granted only user:email scope. In that case, the application wouldn’t have been granted what it asked for, but the granted scopes would have still been sufficient.

Checking for scopes only before making requests is not enough since it’s possible that users will change the scopes in between your check and the actual request. In case that happens, API calls you expected to succeed might fail with a 404 or 401 status, or return a different subset of information.

To help you gracefully handle these situations, all API responses for requests made with valid tokens also contain an X-OAuth-Scopes header. This header contains the list of scopes of the token that was used to make the request. In addition to that, the OAuth Applications API provides an endpoint to check a token for validity. Use this information to detect changes in token scopes, and inform your users of changes in available application functionality.

Making authenticated requests

At last, with this access token, you’ll be able to make authenticated requests as the logged in user:

We can do whatever we want with our results. In this case, we’ll just dump them straight into basic.erb:

Implementing «persistent» authentication

What if we could circumvent the entire «click here» process, and just remember that, as long as the user’s logged into GitHub, they should be able to access this application? Hold on to your hat, because that’s exactly what we’re going to do.

Our little server above is rather simple. In order to wedge in some intelligent authentication, we’re going to switch over to using sessions for storing tokens. This will make authentication transparent to the user.

Also, since we’re persisting scopes within the session, we’ll need to handle cases when the user updates the scopes after we checked them, or revokes the token. To do that, we’ll use a rescue block and check that the first API call succeeded, which verifies that the token is still valid. After that, we’ll check the X-OAuth-Scopes response header to verify that the user hasn’t revoked the user:email scope.

Create a file called advanced_server.rb, and paste these lines into it:

Much of the code should look familiar. For example, we’re still using RestClient.get to call out to the GitHub API, and we’re still passing our results to be rendered in an ERB template (this time, it’s called advanced.erb ).

Also, we now have the authenticated? method which checks if the user is already authenticated. If not, the authenticate! method is called, which performs the OAuth flow and updates the session with the granted token and scopes.

Next, create a file in views called advanced.erb, and paste this markup into it:

Also, if we had never authorized this application to access our GitHub data, we would’ve seen the same confirmation dialog from earlier pop-up and warn us.