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 the following command.

$ 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 deleting the existing token is to try the following command.

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

If you had a token previously stored then running the above should output something like the following.

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 Username/Password. Note that you enter your new token when prompted for Password.

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

The new token should get added to your local Key Chain so you should not need to specify it again until the next time you decide/need to regenerate a new one.

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.