This guide provides instructions on how to:

• Set up Beyond Identity [BI} Authenticator to sign and verify with GitLab
• Beyond Identity authenticator with GPG key entitlements can be used to sign and verify code based on typical Devops events like push, pull, etc. This is a powerful tool to ensure security of SDLC process.  The event triggers the signature validation process as part of CI/CD pipeline.
• A GPG key generated on BI Authenticator can be used to sign many repositories, but a repository can be signed with only one key. 
• The email used to sign must be enrolled in the Beyond Identity tenant.
• You can also require any commits to be verified with biometrics to prevent local malware from committing code or developers from bypassing hygiene and security controls.

Secure DevOps is an add-on for Secure Workforce. Contact your Account Representative to add this feature to your environment.

Contents

• Prerequisites
  • GitLab prerequisites
  • Beyond Identity prerequisites
• Configure Beyond Identity for GitLab
  • Generate a Key management token
  • Get an authenticator entitlement to generate GPG keys
  • Add groups and users (BI Admin console)
  • Generate a GPG Key and set a repository path (Authenticator)
• Configure GitLab
• Appendix: Get Started with GitLab
  • GitLab prerequisites
  • Create an account
  • Create a repository
  • Start using Git

Prerequisites

GitLab prerequisites

• A configured source code repository, project, and entitled users to pull, commit, and merge source code.
• (Optional) A configured CI/CD pipeline.

Beyond Identity prerequisites

• A Beyond Identity tenant configured for your organization and the ability to enroll users.
• An integration with your SSO provider. The instructions are different based on your SSO provider. Please refer to the integration guides available in the link below:
  https://support.beyondidentity.com/hc/en-us/sections/6746815209111-Integration-Guides
• Any users who will sign the code must
  • Have a copy of the Beyond Identity authenticator installed.
  • Have enrolled a passkey with the tenant using the same email that will be used to sign the code.

Note the following: 

• A Beyond Identity authenticator with GPG key entitlements can sign and verify code based on typical DevOps events like push, pull, etc. This is a powerful tool to ensure the security of the SDLC process. The event triggers the signature validation process as part of the CI/CD pipeline.
• A GPG key generated on the Beyond Identity Authenticator can be used to sign many repositories, but a repository can be signed with only one key. 

Configure Beyond Identity for GitLab

This section describes the tasks required to configure the Beyond Identity authenticator for users with SDO enabled. 

• Generate a Key management token
• Get an authenticator entitlement to generate GPG keys
• Add groups and users (BI Admin console)
• Generate a GPG Key and set a repository path (Authenticator)

Generate a Key management token

Your Beyond Identity Representative will provide you with a key management token. This token will be used in the CI/CD pipeline as the value of BYNDID_KEY_MGMT_API_TOKEN in later steps.

Get an authenticator entitlement to generate GPG keys

A Beyond Identity SME will enable the following entitlements for your tenant in the Support console so users can begin using their authenticator for commit signing. 

• Commit Signing - Enables users to generate GPG keys and configure repository paths. Signs and verifies the author of every commit using the authenticator to prevent unauthorized threats.
• Commit Signing with Biometrics (optional) - Requires users to provide biometrics as part of signing and verifying commit signing to prevent local malware from committing code or developers from bypassing hygiene and security controls.

Add groups and users (BI Admin console)

Once the entitlements are enabled, add groups using the names in this section to generate GPG keys, configure repository paths, and optionally require biometrics for commit signing.  

Important: You must use the exact group name provided below for SDO to work.

1. Open the Groups page in the Admin console and click Add Group. 
   1. Enter BI_SDO_GPG_Key_Creation for the group name.
      Important: You must use BI_SDO_GPG_Key_Creation as the exact name for Commit Signing to work. 
   2. Enter an optional description and click Save Changes. 
   3. Open the newly created group and then click Add Users to add any developers to this group.
2. Users added in the steps above will see a GPG Keys link in their authenticator as shown below.
3. Continue to the Generate a GPG Key and set a repository (Authenticator) section below for steps the development users will need to follow.

Generate a GPG Key and set a repository path (Authenticator)

1. On the Beyond Identity platform authenticator, click the GPG Keys link.
2. Click Create GPG key to create and configure GPG keys.
   
3. Ensure the email address matches the email configured to perform Git operations. You can ignore the expiration date.
4. Click Create. You should see the key in the Authenticator.
5. Set the repository path on the authenticator.
   1. In the authenticator, click the ellipses to the right of the GPG key and choose Set repository.
      
   2. Browse to the local path of the repository root and click Configure.
   3. Continue to Configure GitLab below.

Configure GitLab

1. Create a GitLab account.
2. Sign into Gitlab with the account with the same email that will be used to code sign/verify.
3. Set up a GitLab repository.
4. Navigate to Your Repository > Settings > CI/CD > Variables.
5. Click Add variable and add a Gitlab CI/CD variable for the BYNDID_KEY_MGMT_API_TOKEN with the value generated in Generate a Key management token.
6. Set up the CI/CD in your repository root.
   • setup.gitlab-ci.yml.

stages:

  - test

commit-signature-verification:

  stage: test

  variables:

    API_TOKEN: "$BYNDID_KEY_MGMT_API_TOKEN"

  image:

    name: byndid/auth-commit-sig:0.4.1-debian

    entrypoint: [""]

  script:

    - /bin/action -ref="HEAD"

  rules:

    - if: $CI_PIPELINE_SOURCE == "push" 🡪Event triggering BI auth commit/ sign verify

7. Clone the code to your local repository.
8. Change the code as required.
9. Commit with signing, similar to the following:
   git commit -v -S -m "Modified README commit with -S"
10. (Optional) If biometrics were enabled for signing, you will be prompted to provide biometric verification to complete the signing. 
11. Push the code to Origin.
12. Verify a successful pipeline run:
    • Sign into your Gitlab account.
    • Navigate to Your Repository > CI/CD > Pipelines. You should see the pipeline with status “passed”. Click on the pipleline ID.

Appendix: Get Started with GitLab

GitLab prerequisites

• Create an account.
  • Use the same email account that you will use to code sign/verify.
• Create a repository.
• Sign in with the same email account that you will use to code sign/verify.
• You should have privileges to clone, modify, and commit changes.  

Create an account

• GitLab: https://gitlab.com/users/sign_in#register-pane

Create a repository

• Gitlab: https://docs.gitlab.com/ee/user/project/repository/#create-a-repository

Start using Git

• Git Get Started: https://docs.gitlab.com/ee/tutorials/make_your_first_git_commit.html