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 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.
Following this guide, it will be helpful to understand a few terms we'll be using throughout.
gitlab-com/business-ops/itops in your onboarding
issue or in #it-ops on slack. For all other access, create an
access request issue.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.
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.
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:
If you printed the PDF:
@gitlab.com emailAfter 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.
Read this section only if you could not follow the instructions in "Adding the GitLab Team to a 1Password app" section.
Because the Teams feature is not available in your current version of 1Password, we need to update the app to the latest version:
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.
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:
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.
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.
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):
pat
and add a field api. Insert the value of your PAT into the newly created field api.
.env file:## format is op://vault-name/item-name/[section-name/]field-name
echo "GITLAB_TOKEN=op://Private/GitLab/pat/api" > $HOME/.gitlab-pat.env
glab with the PATalias glab="op run --env-file=$HOME/.gitlab-pat.env -- glab"
glab api version. This should print
the version of gitlab.com if the configuration succeeded.glab api version
{"version":"15.4.0-pre","revision":"3e84f577d51"}
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.
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.
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:
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
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:
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.