Skip to main content

Administrator guide

This page will provide guidance for administrators to help add configurations and settings to your source control tools to prevent unwanted access, and require the use of commit signing.

Overview​

The administrator refers to any person/organization responsible for overseeing and owning the source control tools where your code is managed. This can range from a single developer looking to protect their personal repository, or large enterprises with a team dedicated to managing developer tools.

This page will provide guidance on how to enable MFA and commit signing on GitHub and GitLab.

While the guidance on this page isn’t specific to YubiKeys, it will lay the foundations to allow your developers to leverage their security keys for seamless authentication and commit signing.

Account protection​

We will start by enabling account protection in your source control tool. The main idea is to not allow your users to use traditional forms of authentication that are prone to phishing attacks. You will want to require the use of two-factor or multi-factor authentication to access accounts

Enforce 2FA on your administrator account​

Security keys vs passkeys

GitHub allows you to leverage authentication through either a passkey or security key as 2FA. YubiKeys do support passkeys in the form of a device-bound discoverable credential. It's up to your security policy to decide which preference you have for your users, as YubiKeys will support both options.

Yubico generally recommends to generate a passkey on a YubiKey as it enables passwordless login, and removes the need to utilize a passkey

Once the security key is added, you'll be prompted when you attempt to access your account depending on the option selected above.

Signing in with a passkey

Using a security key

Enforce 2FA in your organization​

Requiring two-factor authentication in your organization

Ensure you understand the effects of changing this setting

Before you require the use of 2FA in your source control tool, ensure that you understand how this will affect you and your users. For instance, your tool may remove all members in your organization who do not have a 2FA factor enabled.

Communicate your organization’s preference for Security Keys​

Both of the tools listed above allow for the user to select a variety of different traditional 2FA methods, such as an authenticator app, or SMS OTP. Ensure that you clearly articulate to developers in your organization that they should be enrolling their YubiKey as their 2FA method.

Some tools may allow you to view event/audit logs to see 2FA enrollment events. This will allow you to ensure that users are enrolling security keys vs enrolling other 2FA types.

Commit signing​

Next let’s dive into steps that administrators can take to ensure that users are required to submit commits that have been cryptographically signed by a trusted source. This will be done by enforcing branch protection rules on a specific repository.

We are focused on enforcing branch protection rules that require commit signing, but you should also take the opportunity to add other requirements such as requiring pull requests and approvals for your main branch.

tip

Requiring commit signing is a tactic that works well for developers in a contained ecosystem, such as an organization. In these cases, a security team, or admin, is able to communicate and enforce commit signing based on internal mandates or requirements. The keys are also correlated to trusted internal accounts that are owned, and managed by the organization.

Commit signing may not work well in an open ecosystem, such as an open-source project being built by an anonymous population. Open-source contributors will be utilizing accounts not part of your organization, therefore the signed commit doesn't provide the assurance that the code came from a trustworthy source. In this case you should focus on requiring high assurance MFA of your administrators who are able to merge the pull requests from anonymous accounts into the main branch.

Enforce branch protection rules​

Create a branch protection rule

Note that signing commits will require that your developers generate either SSH or GPG keys using their YubiKeys. The next page, Developer guide, will cover the steps needed to add signing keys to a developers account in more detail. It’s also important for administrators to ensure that developer machines have the tools needed to help in the generation of signing keys.