Prerequisites and step-by-step guide

Prerequisites

• Red Hat OpenShift cluster
• A GitHub.com account

Step-by-step guide

1. Set up RHSSO & RHTAS

First, we'll install Red Hat SSO (Keycloak), followed by the RHTAS operator. Log in to the OpenShift cluster, ensuring that you are logged in with administrative privileges. This is crucial as we will be installing the RHTAS operator.

1.1 Install Red Hat SSO

You can install Red Hat SSO by following the official guide here. Alternatively, use the following prepared script here to save a bit of time.

1.2 Install RHTAS

Follow these steps to install the TAS Operator.

• Log into the OpenShift web console with a user that has the cluster-admin role.
• From the Administrator perspective, expand the Operators navigation menu and click OperatorHub.
• In the search field, type trusted, and click the Red Hat Trusted Artifact Signer tile, as shown in Figure below.

• Click the Install button to show the operator details.
• Accept the default values, click Install on the Install Operator page, and wait for the installation to finish.

Select the project to deploy the TAS service

Once the installation finishes, you need to select a project to deploy the Trusted Artifact Signer service.

• Expand Home from the navigation menu, and click Projects.
• Select the trusted-artifact-signer project which is automatically created when you install the operator.

Deploy a TAS service

You have now created a new project to deploy your new service. Here's how to deploy it:

• Expand Operators from the navigation menu, click Installed Operators. See Figure 2.
• Select your new project name from the project drop-down box.
• Click Red Hat Trusted Artifact Signer.
• Click the Securesign tab, and then click Create Securesign.
• On the Create Securesign page, select YAML view.
• Under the spec.fulcio.config.OIDCIssuers section, replace the OIDCIssuers code with the following configuration which specifies Google OIDC provider URL:

You can also find it with the following command:

echo https://$(oc get route keycloak -n keycloak-system | tail -n 1 | awk '{print $2}')/auth/realms/trusted-artifact-signer

The spec.fulcio.config.OIDCIssuers section, should look like this:

 config:
      OIDCIssuers:
        - ClientID: trusted-artifact-signer
          Issuer: >-
            https://keycloak-keycloak-system.<openshift cluster>/auth/realms/trusted-artifact-signer
          IssuerURL: >-
            https://keycloak-keycloak-system.< openshift cluster>/auth/realms/trusted-artifact-signer
          Type: email

And, finally, now we can deploy securesign by pressing Create securesign.

Click the All instances tab to watch the deployment status until the CTlog, Fulcio, Rekor, Trillian, and TUF instances are ready.

2. Set up SSO Federation for GitHub

Now that we have TAS working with Red Hat SSO, we can move on to set up GitHub as an OIDC provider by following the guide here.

3. Signing setup and first signature

With GitHub set up as a federated identity, we can now set up our local environment for signing. Note that the commands below must be run on the same shell instance.

3.1 Project setup

First, we'll create a tiny Github project with a single text file in it, to keep the example as straightforward as possible. We'll then sign our commit and verify the signature, to confirm we have the necessary binaries installed and working. We can sign commits with a valid OpenID Connect identity using Gitsign.

Let's create an empty repository on GitHub.com with nothing but a README and license file. We'll call it tas-demo.

You can now make a copy of it by cloning it locally, for example:

git clone git@github.com:kahboom/tas-demo.git
cd tas-demo

3.2 Download the required binaries

Download the cosign and gitsign binaries from your OpenShift cluster to your workstation, ensuring they are available in your $PATH. See here for more information.

3.3 Configure your shell environment

Making sure that you are on the same namespace the TAS operator was installed to, configure your shell environment by running the following from the command line:

export TUF_URL=$(oc get tuf -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
export OIDC_ISSUER_URL=https://$(oc get route keycloak -n keycloak-system | tail -n 1 | awk '{print $2}')/auth/realms/trusted-artifact-signer
export COSIGN_FULCIO_URL=$(oc get fulcio -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
export COSIGN_REKOR_URL=$(oc get rekor -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
export COSIGN_MIRROR=$TUF_URL
export COSIGN_ROOT=$TUF_URL/root.json
export COSIGN_OIDC_CLIENT_ID="trusted-artifact-signer"
export COSIGN_OIDC_ISSUER=$OIDC_ISSUER_URL
export COSIGN_CERTIFICATE_OIDC_ISSUER=$OIDC_ISSUER_URL
export COSIGN_YES="true"
export SIGSTORE_FULCIO_URL=$COSIGN_FULCIO_URL
export SIGSTORE_OIDC_ISSUER=$COSIGN_OIDC_ISSUER
export SIGSTORE_REKOR_URL=$COSIGN_REKOR_URL
export REKOR_REKOR_SERVER=$COSIGN_REKOR_URL

3.4 Configure git for signing

From the root of your project, configure the repository to locally sign commits by using the RHTAS Service:

git config --local commit.gpgsign true
git config --local tag.gpgsign true
git config --local gpg.x509.program gitsign
git config --local gpg.format x509
git config --local gitsign.fulcio $SIGSTORE_FULCIO_URL
git config --local gitsign.rekor $SIGSTORE_REKOR_URL
git config --local gitsign.issuer $SIGSTORE_OIDC_ISSUER
git config --local gitsign.clientID trusted-artifact-signer

4. Sign and verify

In your terminal, run the following to sign your commit:

git add .
git commit -m -S "my signed commit" –-allow-empty

A new window should appear in your default browser, prompting you to select an OIDC provider, or to provide your email address in order to sign the commit. Select GitHub as the provider and follow the instructions.

4.1 Initialize the local The Update Framework (TUF) target directory

Run gitsign initialize to create a local TUF targets directory required for verification. The target directory will contain the Fulcio root certificate and the public keys for Rekor transparency log and Certificate transparency log.

gitsign initialize

With our OIDC provider now configured, we can now verify the commit, replacing certificate-identity with your Github email id:

gitsign verify --certificate-identity="ryordan@redhat.com" --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD

Summary

This learning exercise presented the steps for using GitHub identity with Red Hat Trusted Artifact Signer with GitHub Actions. We covered the setup process and how to sign and verify committed source code using your Github email as the identity for the keyless workflow. In the part 2 of this learning exercise you will learn how to use the Github identity to sign and verify container images in a typical build Github Action pipeline.