GitLab Password Guidelines

Passwords at GitLab

Passwords are one of the primary mechanisms that protect GitLab information systems and other resources from unauthorized use. GitLab’s password standard is based, in part, on the recommendations by NIST 800-63B. The password standard sets the requirements for constructing secure passwords and ensuring proper password management. GitLab utlizes 1Password for password management.

1Password

1Password is a password manager that can be used in two different ways - as a standalone application (by purchasing a standalone license) or as a hosted service (by subscribing). GitLab uses 1Password for Teams which is a hosted service.

Ideally you memorize one strong password - hence the name - and let 1Password generate and manage strong, unique passwords for every site for which you have a login.

GitLab requires all team members to use Okta as a primary entry and access point for SaaS and other company applications while utilizing 1Password for password management. GitLab utilizes Okta for SAML/SSO and passwordless authentication for many applications, so the need to store passwords in a password manager will diminish over time.

If you want to use 1Password for your private passwords not related to your work at GitLab, there are a few options.

Please note our 1Password for Business license agreement includes the 1Password for Families feature, which you can share with up to 5 family members.

Terminology

Following this guide, it will be helpful to understand a few terms we’ll be using throughout.

• App: A native 1Password application (macOS, iOS, Windows, Android).
• Extension: A web browser extension/plugin that communicates with the App to provide access to your passwords securely without leaving the browser.
• Vault: What 1Password calls any grouping of secure data, such as logins or secure notes. Sometimes called a “keychain”.

1Password guidelines

1. If you install the macOS application, install 1Password via this link 1Password
2. If you have a YubiKey, it can be added as a 2-factor method to your 1Password account for convenience.
3. When traveling, consider using 1Password in “Travel Mode”, see more on that below.
4. Do not share credentials via email, issue comments, chat etc. This includes email addresses to login and API keys. Use 1Password vaults for this.
5. If you do not have access to a vault that is part of the baseline entitlements for your role and team, mention gitlab-com/business-ops/itops in your onboarding issue or in #it-ops on slack. For all other access, create an access request issue.
6. Use Watchtower to find passwords that need to be changed. Watchtower tells users about password breaches and other security problems on the websites they have saved in 1Password Teams, so users can take action. This is not something account administrators can review for team members, so it is up to you to enable! Enable Watchtower by going to your 1Password app and then to Preferences > Watchtower.
7. Use the “Security Audit” functionality of 1Password to meet the password standard. It will report reused passwords, weak passwords, accounts that are missing 2-factor authorization, and so forth that can then be fixed.
8. Do not copy passwords from inside a 1Password vault to a personal password vault or other password store. 1Password should be the only password vault used for teams. Team passwords should not be duplicated or placed in personal password vaults where they can potentially be exposed to compromise.
9. When asked security questions (what is your favorite pet, etc.) do not answer truthfully since that is easy to research. Make up an answer and write both the question and answer in 1Password. Consider using the Password Generator function in 1Password for this.
10. During offboarding, your 1Password account is deleted, which includes the Private vault in the GitLab team account. If you want to keep your personal passwords, please copy/move them to your Primary vault which you will have if you signed up for an individual account before joining the GitLab Team account.
11. Deprecated When documenting the location of shared credentials in the handbook refer to the items with NAME_OF_SITE credentials in VAULT_NAME. For example: “for access please see the AOL credentials in the Luddite vault”.
    • Deprecation note: This is for existing accounts only. New accounts should be created by creating an issue to add it to Okta.

1Password for teams

1Password for Teams stores all Vaults on the 1Password servers and allows for sharing between multiple people on the same team. Every GitLab team member who needs access to a shared vault should consult their departments for any shared vault information.

Each member of the team has a vault called Private which only you can see, and allows you to store personal credentials within the GitLab team’s account.

To really get the full benefit of 1Password, you’ll need to hook our Teams account up to one of the native apps.

Adding the GitLab team to a 1Password app

This guide will cover setting up the macOS app. It’s their lead platform and is the most up-to-date. These instructions may or may not work for the Windows version. If you use 1Password 6 without a 1Password.com account, make note of this.

1. Download and install the 1Password macOS app.
2. Launch the app.
3. Click “Sign in to your 1Password account” button. If there is no such button please follow the instructions for updating 1Password.

Now you’ll need the Emergency Kit PDF that 1Password told you to save when you registered your Teams account. Note: Store the Emergency Kit safely. Store a copy of the Emergency Kit on a USB flash drive or print a copy and store it in a vault at home or safe deposit box — somewhere not online or accessible by anyone other than yourself.

If you saved it as a digital PDF file:

1. Open the PDF file
2. Click Scan QR Code
3. Open the PDF file with the scanner by clicking on the camera icon

If you printed the PDF:

1. Click Sign In Manually
2. For Team URL enter gitlab.1password.com
3. For Account Key enter the Account Key from your Emergency Kit
4. For Email Address enter your @gitlab.com email
5. For Master Password enter the password to your Teams account (not the password you created above when you chose “I’m a new user”)

After the Team is added, you should see some notifications about vaults being added to 1Password. By default you’ll have the Private vault, but may have access to others.

Updating 1Password to support the Teams feature

Read this section only if you could not follow the instructions in “Adding the GitLab Team to a 1Password app” section.

1. At the prompt, choose “I’m a new user”. Note: This is one source of confusion. “I created my Teams account, I’m not new!” Just go with it.
2. Enter a master password, confirmation, and hint. This can (and should) be different from the password you used for our Teams account. This password gates access to your local, private Vault on your computer and/or phone.
3. Skip over the remaining dialogs (syncing, newsletter, etc.)
4. You should now have an empty vault called Primary.

Because the Teams feature is not available in your current version of 1Password, we need to update the app to the latest version:

1. Go to Preferences
2. Go to Updates
3. Click Check Now
4. Install the update and relaunch
5. After relaunch, go to Preferences again
6. Go to Accounts
7. Click the + icon

Vaults

Click the Vault Selector in the upper-left corner of the window:

GitLab team members have access to a Private vault by default, which is your hosted, private vault that is part of the GitLab 1Password for Teams account. Since the Private vault is part of the GitLab Teams account, it should be thought of as company property (like the @gitlab.com email account), however the vault can not be viewed by anyone else on the team, including admins. If you choose to store truly personal information in the Private vault, it opens up the possibility that you would be separated from this information if you offboard. Such truly personal information is therefore better to store in your Primary vault, which is associated with you instead of with the GitLab Teams account, assuming that you added an individual account.

People may request access to other vaults such as shared vaults that their teams/departments have created.

Browser extension

Go to Browser extensions and install the extension for whatever browser you’re using. You should not need a beta version here.

With the extension installed, you should be able to go to a site that you have credentials stored for in 1Password and log in:

If you don’t see the site listed in the results window, make sure you’re using the correct vault:

Saving logins

When 1Password detects a login form submission, it may ask if you want to save the login with a dialog like this:

If you do want to save it, make sure the appropriate Vault is selected first.

Managing SSH keys

Starting with version 8, 1Password can operate as the single source of truth for your SSH keys. This includes generating private keys, storing them securely, filling your public keys in to sites like GitLab.com, and unlocking the keys automatically when performing git operations.

More information is available in the official documentation.

CLI integration

1Password CLI integration supports secure handling of secrets used in command line tools, config files, and scripts executed on your laptop. To setup the CLI integration, follow the getting started guide.

It is recommended to store secrets such as personal access tokens in 1Password. Avoid storing secrets in unencrypted files.

Example for configuring glab with 1Password CLI (requires 1password version 8 or higher):

• Store your access token in 1Password. In the entry for your GitLab account, create a new section pat and add a field api. Insert the value of your PAT into the newly created field api.

• Store a secret reference to the access token in an .env file:

1
2

## format is op://vault-name/item-name/[section-name/]field-name
echo "GITLAB_TOKEN=op://Private/GitLab/pat/api" > $HOME/.gitlab-pat.env

• Define an alias in your shell profile to invoke glab with the PAT

1

alias glab="op run --env-file=$HOME/.gitlab-pat.env -- glab"

• To verify the configuration, run glab api version. This should print the version of gitlab.com if the configuration succeeded.

1
2

glab api version
{"version":"15.4.0-pre","revision":"3e84f577d51"}

Several accounts and unlocking the app

Please refer to 1Password FAQ.

If you are planning to use both the GitLab team account and a separate individual account you should first add your separate individual account to the app first (Preferences > Accounts). By doing this you will be able to unlock the 1Password app using the Master Password of the individual account.

If you were using 1Password before joining GitLab, and you receive a prompt titled Migrate To Account, choose I’ll move later. There is no harm in doing this, and it is easy to move items between vaults.

1Password for your private passwords

You are encouraged to use 1Password for your private passwords, not related to your work at GitLab. This makes it less likely for a security breach to occur. You can purchase a standalone license or start an individual subscription, or take advantage of the complimentary 1Password for Families feature, which you can share with up to 5 family members.

Two factor authentication and time-based one time passwords

As stated in the GitLab Password Standards, the usage of 2FA is mandatory for all GitLab team members.

Okta is configured such that it only supports the use of WebAuthn. 1Password TOTP should only be used when WebAuthn is unavailable.

1Password provides an alternative solution that does not require using your smartphone: 1Password Time-based One Time Passwords (TOTP). 2FA codes are displayed directly in the 1Password app running on your laptop (Note: this can not be set up via 1Password browser extension or 1Password web app).

To enable TOTP for a saved account:

1. Open 1Password app
2. Go to the item for which you want to set up TOTP
3. Click Edit in the bottom right corner
4. Add a new field by clicking on the field type dropdown (it offers a “Text field” by default)
5. Select One-Time Password

1. Click QR code icon that appeared

1. Scan QR code using the transparent window
2. Click Save
3. 2FA code should be displayed now

Please refer to demo video 1password TOTP setup

Please refer to the 1Password blog for more information on how TOTP works.

If scanning the QR code using the “transparent window” with the 1Password Mac app fails on a recent macOS, please consider using the 1Password iOS app instead. This mechanism works the same way, and supports Touch ID to login.

If unsure which mechanism to use, we require using WebAuthn (when possible) as a TOTP for 2FA.

Follow this guideline when getting a new mobile device, if you are using Google Authenticator as a TOTP mechanism.

There may be cases where TOTP might be used with a non-GitLab account. If you have any questions and need to speak with the Security Team, you can contact Security

Example usage

This is an example of how Robert, one of our developers, uses 1Password:

Once you fully commit to using 1Password to manage all of your security information, it really does make life easier.

I memorize one strong password and let the app generate everything else. Every site I use has a unique password that I can’t compromise because I don’t even know it, and a hacked site can’t compromise it because the password is never re-used on another site.

I store my shipping and credit card info in 1Password and use the browser extension to quickly fill out shipping and billing information on shopping sites.

I store my passport data, along with a digital scan, in 1Password; driver’s license info and scan; insurance info; software license keys; any important information that needs to be secure but still easily accessible when I need it, from anywhere. I sync my personal vault to my personal iCloud so it’s available on my phone, tablet, laptop, and desktop.

Even my 1Password for Teams account information is stored in my personal Primary vault, with the Emergency Kit PDF as a secure attachment. I have no idea what the password is. I’ve never actually typed it. And that’s the idea:

Traveling with 1Password

When traveling with a device that has access to the GitLab 1Password vaults, be sure to enable Travel Mode in 1Password. Travel Mode removes copies of any 1Password vaults that are not tagged as “safe for travel” from your mobile devices. None of the GitLab shared vaults are marked as safe for travel so you will need to either create a dedicated travel vault or mark your Private vault as safe for travel.

Once you have enabled Travel Mode open 1Password on each device you will be taking with you so that it can sync with 1Password.com and remove any vaults that cannot be used while traveling.

For more information on Travel Mode and how it works, see the AgileBits blog.

Securing Docker Registry User Credentials

Docker can store user credentials in an external credential store as a more secure alternative to storing credentials in the Docker configuration file.

Using osxkeychain (macOS)

To configure Docker to use osxkeychain for secure credential storage, follow these steps:

1. Install the docker-credential-osxkeychain helper via Homebrew:

   1	brew install docker-credential-helper

2. Configure ~/.docker/config.json to use osxkeychain as your Docker credstore:

   1 2 3

   { "credsStore": "osxkeychain" }

3. Log in using docker login registry.gitlab.com, and enter your email and password (PAT) when prompted.

4. Validate that the credentials were not saved as base64-encoded text in ~/.docker/config.json.

Using pass (Linux)

Prerequisites

1. Create a GPG key
2. Install pass

To configure Docker to use pass for secure credential storage, follow these steps:

1. Download the latest docker-credential-pass binary from the releases page.

2. Make the docker-credential-pass binary executable with chmod +x docker-credential-pass.

3. Move the docker-credential-pass binary to your $PATH (e.g., sudo mv docker-credential-pass-v0.8.0.linux-amd64 /usr/local/bin/docker-credential-pass).

4. Obtain and copy the GPG key ID that pass will use for encryption via gpg --list-secret-keys --keyid-format LONG.

5. Initialize pass with pass init <gpg-key-id>.

6. Configure ~/.docker/config.json to use pass as a credstore:

   1 2 3

   { "credsStore": "pass" }

7. Log in using docker login registry.gitlab.com, and enter your email and password (a valid token) when prompted.

8. Validate that the credentials were not saved as base64-encoded text in ~/.docker/config.json.