1. Table of Contents

 

 

2 Introduction 2

2.1 About 2

2.2 Prerequisites 2

3 Beyond Identity Tenant Configuration 3

4 BI configuration for Github 3

4.1 Generate key management token 3

4.2 Get authenticator entitlement to generate GPG keys 3

4.3 Set Repository Path on the authenticator 5

4.4 Github configuration 6

5 Appendix 8

5.1 Create an account 9

5.2 Create Repository 9

5.3 Starting with Git 9

Introduction

 

1. About

This guide provides instructions on how to:

• Set up Beyond Identity [BI} Authenticator to sign and verify with Github
• 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.

 

2. Prerequisites

Ensure that you have the following:

1. You have a tenant configured for your organization and able to enroll users.
   1. Integration with your SSO provider. The instructions are different based on your SSO provider. Please refer to the integration guides available in the below link

https://beyondidentity.atlassian.net/wiki/spaces/CS/pages/1063813121/SSO+Integration+Guides

No need to setup up BI admin console or BI user console

2. You have configured source code repository, project and entitled users to pull, commit, merge source code.
3. The users who will sign code must enroll with BI tenant and download BI authenticator.
4. You already have setup a CI/CD pipeline [optional]

3. Beyond Identity Tenant Configuration

Information to provide to the Beyond Identity Field Team to setup a tenant:

 

4. BI configuration for Github

• Generate Key management token
• Get authenticator entitlement to generate GPG keys
• Generate GPG Key
• Set repository path on the authenticator

1. Generate key management token

Beyond Identity Field Team: Please generate key management token through Beyond Identity Support Console for the tenant. This token will be used in the CI/CD pipeline as the value of BYNDID_KEY_MGMT_API_TOKEN in later steps.

2. Get authenticator entitlement to generate GPG keys

• Ensure “Commit-Signing” is enabled for the tenant. This can be done through the support console and BI SME can help with this. 
• After this is enabled, any members of the Super administrator group in Beyond identity admin console should create a group with the exact name of “BI_SDO_GPG_Key_Creation”
• Members of “BI_SDO_GPG_Key_Creation” group will be entitled to generate GPG keys and configure repository paths
• Using Beyond Identity admin console, add users to this group. These users will see “GPG keys” in their platform authenticator as shown below

 

On clicking “GPG Keys” link, you should see a screen with options to create GPG keys and configure

 

Click “Create” 

 

Ensure the email address matches the email configured to perform git operations. You can omit the expiration date

3. Set Repository Path on the authenticator

After creating the key, you should see the key in the Authenticator and “…” to the right. Click “…” and choose “Set repository”.

 

 

Browse to the local path of the repository root and click Configure. 

 

4. Github configuration

• Create a Github account
• Sign into Github account with the same email that will be used to code sign/verify
• Setup Github repository

 

 

• Configure in Github secrets the parameter BYNDID_KEY_MGMT_API_TOKEN with value generated in step 4.1
  • Your Repository🡪Settings🡪Secrets under repository secrets

 

 

• Create workflow file in the .github/workflows directory of your repository.
  • .github/workflow/auth-commit-sig.yml

name: Authorize Commit Signing

on: 🡪Condition that triggers pipeline job verify signature with Beyond identity

 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: gobeyondidentity/auth-commit-sig@v0

        with:

          api_token: ${{ secrets.BYNDID_KEY_MGMT_API_TOKEN }}

 

• Clone code to local repository
• Change code as required
• Commit with sign
  • git commit -S -v -m " Modified  README in signedcommit branch"
• Push
• Access Github repository using the browser create a pull request

 

 

• In the next screens click on “merge pull request” and “confirm merge”
• This would trigger the pipeline and signature verify job should complete successfully
• Verify successful completion
  • Access your repository🡪Pull requests🡪Closed. Click open the pipeline, you should see “verified” in Green

5. Appendix

Github 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, commit changes. 

1. Create an account

• GitHub: https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account

2. Create Repository

• GitHub: https://github.com/new

3. Starting with Git

• Git Tutorial: https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud