This article explains how to use Beyond Identity Secure DevOps to ensure Git commits are signed only by trusted devices, detailing the setup and configuration of the Beyond Identity Authorization API, GitHub Action, user enrollment, and the Authenticator for automatic commit signing.

The Beyond Identity Secure DevOps product provides an efficient and easy mechanism to ensure that all Git commits are sourced from trusted macOS, Windows, and Linux devices. The product is comprised of two components:

• The Beyond Identity Authorization API, when integrated to your CI/CD pipeline, can be used to enforce that only commits signed by the Beyond Identity Authenticator can be merged into your main branch. Beyond Identity has created a GitHub Action that integrates directly with the Beyond Identity Authorization API. We recommend that GitHub and GitLab administrators use the Beyond Identity GitHub Action overwriting custom code to work with the Authorization API.

• The Beyond Identity Authenticator signing the Git commits on each developer’s machine.

The following illustration shows the commit signature verification flow.

Beyond Identity Authorization API

The Authorization API will check to see that a provided GPG key ID is authorized to sign Git commits. Although you can integrate this API into your pipeline as you see fit, we highly recommend using the Beyond Identity GitHub Action instead. A Beyond Identity API token is required to authenticate to this API.

Example Request

GET /v0/gpg/key/authorization/git-commit-signing HTTP/1.1
Host: byndid.com
key_id=5E29D8B23BC9A721&committer_email=john@byndid.com

Example Response

{
   "authorized": true,
   "message": "gpg key is authorized for git commit signing",
   "gpg_key": {
       "id": "6afe71c1-388e-4ceb-9620-554607ab5957",
       "base64_key": "mFIEYSaHIBMIKoZIzj0DAQcCAwRRgi2p5rHAFTA9zYlfKuIBD9fmCBdcnk+811tJ9F2kuBz0EKnX4ZY7eWbo3ew/59H5Ho4n/At4quh0rZTN8xqBtENTdXJlc2ggQmhhbmRhcmthciAoR0tNIFRlc3QpIDxzdXJlc2guYmhhbmRhcmthckBiZXlvbmRpZGVudGl0eS5jb20+iJYEExMIAD4WIQSZ4jUQHiw3mVWJsYteKdiyO8mnIQUCYSaHIAIbAwULCQgHAgYVCgkICwIEFgIDAQIeAQIXgAUJAeEzgAAKCRBeKdiyO8mnIQv1AP4ibjPl6z2lUWqNPj8YsY+yHOBTKmPxlcMAdp7oZbHv8QEAmaHlcTYrG6+8WMOBrM/DR+V1qe9GKFktttAb5/G3rzE="
   }
}

Error Codes

The Beyond Identity Authorization API will return an error for any unauthorized signatures. The following table provides a list of possible errors and descriptions.

Beyond Identity GitHub Action

The Beyond Identity GitHub Action is for authorizing a Beyond Identity user to sign Git commits and verifying those Git commit signatures. The action enforces that all commits are signed by authorized users in your organization’s Beyond Identity directory. Because the Beyond Identity GitHub Action makes API calls to the Authorization API, you will need a Beyond Identity API Key.

Setting Up Integration with GitHub

The following information provides the necessary steps for a GitHub administrator to integrate the Beyond Identity GitHub action into their CI/CD pipeline.

Step 1 - Add Beyond Identity to your CI/CD pipeline (GitHub)

1. Access the Beyond Identity GitHub action at https://GitHub.com/byndid/auth-commit-sig.

2. We recommend installing the GitHub action at the beginning of your GitHub pipeline, as shown in the example below.

Example GitHub Pipeline configuration

In this example configuration, we specify that this pipeline should be run on every pull request.

name: Pull Request CI Pipeline

on:
# Run for all pull requests against the main branch.
pull_request:
branches: [ main ]

jobs:
verify-signature-with-Beyond-Identity:
runs-on: ubuntu-latest
steps:
- name: Check out pull request
uses: actions/checkout@v2
with:
# Critical: check out the head commit on the branch. By default,
# actions/checkout will check out a merge commit built for the pull
# request and signed by GitHub itself. Using the pull-request HEAD
# allows the action to check the latest commit on the pull request,
# which must be signed by an authorized user before it can be merged.
ref: ${{ GitHub.event.pull_request.head.sha }}

- name: Authorize with Beyond Identity
uses: byndid/auth-commit-sig@v0
env:
# Setting API_BASE_URL for configuration reference. It can be removed
# in production
# environment:
API_BASE_URL: "https://api.byndid.com/key-mgmt"
# TODO: remove this to switch to production, once the API is released.
with:
api_token: ${{ secrets.BYNDID_KEY_MGMT_API_TOKEN }}

lint-code:
needs: verify-signature-with-Beyond-Identity
runs-on: ubuntu-latest
steps:
- run: echo "Lint free"

build-code:
needs: lint-code
runs-on: ubuntu-latest
steps:
- run: echo "Build succeeded"

unit-tests:
needs: build-code
runs-on: ubuntu-latest
steps:
- run: echo "Unit tests passed"

integration-tests:
needs: build-code
runs-on: ubuntu-latest
steps:
- run: echo "Integration tests passed"

Create a new secret for your GitHub repository. The secret must be named BYNDID_KEY_MGMT_API_TOKEN. A Beyond Identity Sales Engineer will provide this token to you.

Step 2 - Configure branch protection rules

1. We recommend putting a branch protection rule on your main branch. For more information on branch protection rules, see: (https://docs.GitHub.com/en/GitHub/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches).

2. The following screen shows a sample branch protection rule on the main branch. The rule is configured to require that the Beyond Identity GitHub action must pass status checks (in this example, verify signatures with Beyond Identity) before a branch can be merged to the main branch. The rule also requires commits that are pushed to merging branches have verified signatures.
   

Once the GitHub action has been configured, you must enroll each user who will be signing Git commits.

Enrolling Users

Each user that will be signing Git commits must be added to a specific group within the Admin Console. To add users, you must first create the group and then add users to that group.

Note: To allow individual users to sign commits, you must have Git commit signing already enabled for your tenant. Contact a Beyond Identity team member if you do not already have it enabled.

1. From the Groups page, select Add Group:

2. In the Add Group dialog, provide:

   • The Group Name. The name must be BI_SDO_GPG_Key_Creation

   • An optional Description

3. Select Save Changes. The group is added to the Group list.

4. Locate and open the new-created group.

5. From the BI_SDO_GPG_Key_Creation group page, select Add Users.

6. From the Add User dialog, select each user you want to add from the drop-down menu.
   

7. As each user is added, the passkey associated with the user is displayed in the dialog.
   

8. Click Add users to group. The users are displayed under the Members section.
   

Setting Up the Beyond Identity Authenticator

The following information provides your company’s developers with the necessary steps to configure the Beyond Identity Authenticator to automatically sign Git commits. Before starting, each developer must have:

• The appropriate Platform Authenticator installed

• The passkey on their Authenticator

Step 1 - Generate a GPG Key

1. Update your Authenticator to the latest version.
   

2. Select the appropriate passkey and click GPG Keys to open the GPG key management screen. If there are no keys, + Create GPG Keys is displayed in place of GPG Keys in the passkey.
   

3. Click + Create GPG key.

   Note: The wording of the button may be slightly different depending on the platform you are using.

   

4. Provide a name and email address of the developer generating the key, and optionally, a key comment and expiration date for the key.

   Note: The email address must match your Beyond Identity User’s email address and should also match your GitHub/GitLab email address.

5. Click Create and view your GPG key on the GPG Keys screen.
   

6. Click the ... button and then and click View Details.
   
   

This screen provides the following details about your GPG key including the:

• Name of the developer who created the key (GPG Key info)

• Email address of the developer who created the key

• Key fingerprint

• Public Key

• Date created

• Expiration date if one was configured

1. Click the copy icon next to the Public Key.
   

2. Paste the copied key into your GitLab/GitHub profile and click Add GPG key.
   

3. You should now see your key in your GitLab/GitHub account.
   

Step 2 - Configure Git Client to Sign with the Generated GPG Key

1. Click the ... button and click Set Repository.
   

2. From the Set repository signing dialog, select the appropriate option:

   • To sign all repositories you own, click Sign all repositories.

     
     

   • To sign an individual repository, click Select one repository for signing, then click Browse and navigate to your repository.
     

3. Add a checkmark to Always sign commits in this repository.

4. Add a checkmark to Configure this repository to sign with this key’s email address.

5. Click Configure.

Any time you make a Git commit, the Authenticator will automatically sign it.

Keep the following points in mind when signing commits:

• If a key that was previously used to configure an individual repository is deleted from the platform authenticator, that particular repository must be re-configured individually with a new key. This is necessary because the repository's configuration still references the deleted key, which takes precedence over the global configuration.

• The global signing feature includes all repositories. This includes repositories (such as personal repositories) that are not configured to verify the signatures. The GitHub and GitLab web UI will simply indicate these signatures as unverified but there are no repercussions or issues with the signatures.