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.
Error Message | Description |
Commit not signed | The commit was not signed. |
Signed with non-BI Key | The commit was signed but not with a GPG key generated by the Beyond Identity Authenticator. |
User not active | The Beyond Identity user who signed the git commit is in a suspended state. |
Device passkey not active | The Beyond Identity user’s device is deleted. |
GPG key not active | The GPG Key used to sign the commit has been suspended. |
GPG key expired | The GPG key used to sign the commit has expired. |
BI unavailable | The GitHub action was unable to establish a connection to the Beyond Identity Cloud. |
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)
-
Access the Beyond Identity GitHub action at https://GitHub.com/byndid/auth-commit-sig.
-
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
-
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).
-
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.
- From the Groups page, select Add Group:
- In the Add Group dialog, provide:
- The Group Name. The name must be BI_SDO_GPG_Key_Creation
- An optional Description
- Select Save Changes. The group is added to the Group list.
- Locate and open the new-created group.
- From the BI_SDO_GPG_Key_Creation group page, select Add Users.
- From the Add User dialog, select each user you want to add from the drop-down menu.
- As each user is added, the passkey associated with the user is displayed in the dialog.
- 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
-
Update your Authenticator to the latest version.
- 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.
- Click + Create GPG key. Note: The wording of the button may be slightly different depending on the platform you are using.
-
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.
-
Click Create and view your GPG key on the GPG Keys screen.
- 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
-
Click the copy icon next to the Public Key.
- Paste the copied key into your GitLab/GitHub profile and click Add GPG key.
- You should now see your key in your GitLab/GitHub account.
Step 2 - Configure Git Client to Sign with the Generated GPG Key
-
Click the ... button and click Set Repository.
-
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.
-
-
Add a checkmark to Always sign commits in this repository.
-
Add a checkmark to Configure this repository to sign with this key’s email address.
-
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.
Comments
0 comments
Please sign in to leave a comment.