[TOC] # Person Access Token (PAT) Authentication for Git ::: info TL;DR A PAT is a password that you generate for your computer on GitHub or GitLab. You use it in place of your normal password on the command line and **git will remember it**. There are four (generalized) steps for generating a token (steps done on the GitHub website are denoted with :female-technologist:, steps on the command line are denoted with :computer:) 1. :female-technologist: Give a description of the token (e.g. My Computer) 2. :female-technologist: Set the scope of the token (e.g. repo, workflow, gist) 3. :female-technologist: Copy the token 4. :computer: Paste the token into your command line when prompted by Git. It takes no new commands to set it up and it only needs to be used once. **The git credential helper will store your token securely on your computer.** ::: [Personal Access Tokens](https://en.wikipedia.org/wiki/Personal_access_token) are text-based keys generated by a service like GitHub or GitLab that you can give to your computer instead of your password so that you can access those services via the command line. A good analogy for these is [A Hotel Keycard](https://developer.okta.com/blog/2019/06/05/seven-ways-an-oauth-access-token-is-like-a-hotel-key-card). You can also think of these as passwords you give to your computer. You have your username and password to access GitHub on the website, and you can do _anything_ to your account there, including changing or deleting your information and who has access to your repositories. Giving your password to your computer would give it access to all of the same things, but if you give it a PAT, you can restrict it to ONLY operations for repositories (e.g. push/pull). Note: I am getting most of the material here from <https://happygitwithr.com/https-pat.html#store-credentials-through-organic-git-use>. ## How do I use a PAT? The PAT is a drop-in replacement for a password on your system. You can generate your PAT in the following steps: 1. Go to https://github.com/settings/tokens/ 2. Click on "Generate New Token" 3. Describe what you are using the token for (e.g. SWC Workshop) 4. Choose the scope of the token (suggested: repo, workflows, user, gist) 5. Copy the token to your clipboard 6. Go back to your command line, navigate to a git repository and type "git push" 7. when prompted for your password, enter your token (on Git for Windows, it will ask you for your token). That's it. You will not be asked for your token again because git will store it in its cache. :::info The token scope and name can be entered in a URL, so you can give your learners a link they can click on like so: https://github.com/settings/tokens/new?scopes=repo,user,gist,workflow&description=SWC%20Workshop This way, you can start at step 5, above. ::: ## How do I reset my PAT? The PAT can be confusing because it's automatically cached by git, but you can reset your PAT by going to https://github.com/settings/tokens, deleting it, and followign the steps above to generate a new token and register it with git. When you do, you will get an error, but try again and it will give you a prompt: ```bash git push # remote: Invalid username or password. # fatal: Authentication failed for 'https://github.com/USER/REPO.git/' git push # Username for 'https://github.com': <USER> # Password for 'https://USER@github.com': <PAT> ``` ## I used a password to log in already, how do I clear my password cache? The following command will reset your credentials on GitHub: ```bash printf "protocol=https\nhost=github.com\n" | git credential reject ``` ::: info This will work for any host! If you are on GitLab, you would do the following: ```bash printf "protocol=https\nhost=gitlab.com\n" | git credential reject ``` The documentation for `git credential` is a bit weird and it's utterly confusing, but the basic gist of it is the following: `git credential` expects a list of _at least_ protocol and host keys in the form of stdin OR manually typing afterwards. This is _the most confusing aspect of this program_. It does not give you any instructions on _how_ to do this, you are just supposed to know. This is why I have `printf "protocol=<https/ssh>\nhost=<HOST>\n"` with a pipe (` | `) to `git credential reject`. If you didn't want to use a pipe, you would do the following: 1. type `git credential reject` 2. when you get a blank prompt, type `protocol=https` and hit enter 3. type `host=github.com` and hit enter 4. hit enter again On your command line, it would look like this: ```bash git credential reject protocol=https host=github.com ``` ::: If you didn't want to use the command line above because it's weird and scary (which I don't blame you), these are the locations of the keys on your system: - On Mac: go to your KeyChain, find github, and remove it. - On Windows, you can go to the Windows Credential Manager and remove it. - On Linux, it's honestly easier to use the command above. ## Common misconceptions Because PATs are a newer technology, there are a few misconceptions floating around about them: ### 1. You don't have to store your PAT in a password manager A lot of tutorials will tell you that you should store your PAT in a password manager, but the git credential manager will take care of that for you in a secure manner. Remember that PATs are a lot like hotel key cards. If you lose yours, you can go to the front desk and tell them that you lost it and they will do two things: 1. invalidate the old keycard and 2. issue you a brand new one. In terms of restoring your PAT, you would delete the old PAT from the service (e.g. delete it from GitHub) and then generate a new PAT for your computer. ### 2. PAT are not proprietary to GitHub A common misconception about PATs is that they are proprietary technology from GitHub/Microsoft. This is not entirely true. [Access Tokens](https://en.wikipedia.org/wiki/Access_token) are an open-source concept. PATs are available for several services that use authentication over HTTPS including [GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). ### 3. You don't have to enter your PAT every time you use your password Modern versions of Git on Windows and MacOS will have a credential manager pre-configured to use the native credential managers of the system so you can enter your credentials once and they will be stored until you reset or invalidate them.