Adding & Updating GitHub Access Token on Mac

add-update-github-access-token-on-mac.md

As outlined here, there are a couple of situations where you may want/need to authenticate with GitHub by using an Access Token:-

1. If you have Two-Factor Authentication (2FA) enabled.
2. You are accessing an organisations protected content using SAML Single-Sign On (SSO).

Using an Access Token for the first time

Create an Access Token

In your GitHub account, go to Settings / Developer settings / Personal access tokens and select Generate New Token. Make a note of the token somewhere safe since this is the only chance you get to see it.

Add the token to your OSX Key Chain

When you next clone a private repository on the command line Github should challenge you for your credentials. Even though it will prompt you for your Password for 'https://username@github.com': this is actually where you should supply your new access token.

$ git clone https://github.com/username/repo.git

Cloning into 'repo'...
Username for 'https://github.com': your_github_username
Password for 'https://username@github.com': your_access_token

Using the token on your Mac the first time should automatically add it to your OSX Key Chain so that you do not need to enter it every time you are interracting with the Github API. If you check your local git configuration you should see that there is a credential.helper key pointing to the OSX Key Chain.

$ git config -l

credential.helper=osxkeychain
user.email=joe.bloggs@gmail.com
user.name=Joe Bloggs

Updating to a new Access Token

April 2021 - notice on possible future updates on token length Authentication token format updates are generally available.

If you need to regenerate the Access Token then log into your Github dashboard and navigate to Settings / Developer settings / Personal access tokens and choose to either Generate new token or replace your existing token, either by choosing Delete and Generate new token, or viewing your current token and choosing Regenerate token.

Remove existing token from your Keychain

The general approach described in the Github documentation is to use the following git command to erase your local credentials. Note, it is worth reading the rest of this section before running this.

$ git credential-osxkeychain erase

The above would appear to be increasingly ineffective and, as many report in the comments below, often just hangs. An alternative approach to delete is to try the following.

$ security delete-internet-password -l github.com

keychain: "/Users/jblogs/Library/Keychains/login.keychain-db"
version: 512
class: "inet"
attributes:
    0x00000007 <blob>="github.com"
    0x00000008 <blob>=<NULL>
    "acct"<blob>="joebloggs"
    "atyp"<blob>="dflt"
    "cdat"<timedate>=0x32303230303932383233343630395A00  "20200928234609Z\000"
    "crtr"<uint32>="aapl"
    ... (truncated)
password has been deleted.

Now, the next time you attempt a clone/pull/push etc on a private repo, the Github API should prompt you for your Password on the command line and entering the new access token should also add it to your local Key Chain which you can check as below.

To check if your access token exists in your keychain

To check if the token still exists you can try this.

$ security find-internet-password -l github.com

Which should report something like this if it exists.

keychain: "/Users/jbloggs/Library/Keychains/login.keychain-db"
version: 512
class: "inet"
attributes:
    0x00000007 <blob>="github.com"
    0x00000008 <blob>=<NULL>
    "acct"<blob>="joebloggs"
    "atyp"<blob>="dflt"
    "cdat"<timedate>=0x32303730303933373333343635395A00  "20200938235909Z\000"
    ...(truncated)

Or else if it does not exist then you should see something like this.

security: SecKeychainSearchCopyNext: The specified item could not be found in the keychain.