Deployment Guide

Red Hat Trusted Artifact Signer 1

Installing and configuring the Trusted Artifact Signer service for Red Hat platforms

Red Hat Trusted Documentation Team

Abstract

This Deployment Guide gives you guidance on installing the Trusted Artifact Signer service on Red Hat platforms, and verifying that installation was successful.

Preface

Welcome to the Red Hat Trusted Artifact Signer Deployment Guide.

These procedures can help guide you on deploying the full Trusted Artifact Signer (RHTAS) software stack, and verifying that deployment. Content organized by your installation platform:

You can view the official RHTAS Release Notes here.

Chapter 1. Red Hat OpenShift Container Platform

1.1. Resource recommendations for deploying on OpenShift

Understanding how to size the infrastructure resources before deploying Red Hat Trusted Artifact Signer (RHTAS) on Red Hat OpenShift is important for optimizing your workloads. The key infrastructure piece for consideration is the number of CPUs and the memory available for the Trillian database. As the number of signing and verifying requests increases, this adds more load to the CPU, and increases the memory usage of the Trillian database.

You have two options for implementing the Trillian database used with RHTAS: a dedicated database, or a managed database. Red Hat recommends a dedicated database for production workloads, and a managed database for non-production workloads. Here are the baseline CPU and memory resources you can start with.

Dedicated
  • 2 CPU cores
  • 1 GB of RAM
  • 5 GB of storage
Managed
  • 4 CPU cores
  • 2 GB of RAM
  • 10 GB of storage

Additional resources

1.2. Installing Trusted Artifact Signer using the Operator Lifecycle Manager

You can install the Red Hat Trusted Artifact Signer (RHTAS) Operator, and deploy the RHTAS service by using OpenShift’s Operator Lifecycle Manager (OLM). This deployment gives you a basic signing framework with your choice of an OpenID Connect (OIDC) provider. You must configure at least one of the following OIDC providers: Red Hat Single Sign-on (SSO), Google, Amazon Secure Token Service (STS), or GitHub. You can also optionally customize your database solution, if you do not want to use the default.

Prerequisites

  • Red Hat OpenShift Container Platform 4.16 or later.
  • Access to the OpenShift web console with the cluster-admin role.
  • An OIDC provider configured for signing artifacts.
  • A workstation with the oc binary installed.

Procedure

  1. Log in to the OpenShift web console with a user that has the cluster-admin role.
  2. From the Administrator perspective, expand the Operators navigation menu, and click OperatorHub.
  3. In the search field, type trusted, and click the Red Hat Trusted Artifact Signer tile.
  4. Click the Install button to show the operator details.

  5. Accept the default values, click Install on the Install Operator page, and wait for the installation to finish.

    Important

    Once the installation finishes, a new project is automatically created for you. The new project name is trusted-artifact-signer.

    Note

    The Trusted Artifact Signer operator installs into the openshift-operators namespace, and all dependencies are automatically installed.

  6. Optional. Instead of the default database, you can use an alternative database provider for the Trusted Artifact Signer service. If you want to use Amazon’s Relational Database Service (RDS), or a self-managed database on OpenShift, then follow one of those procedures first before continuing on with this installation. Once done configuring one of these other database providers, you can continue onto the next step of this procedure.

  7. To deploy the Trusted Artifact Signer service.

    1. Within the OpenShift web console, expand Operators from the navigation menu, click Installed Operators.
    2. Select trusted-artifact-signer from the project drop-down box.
    3. Click Red Hat Trusted Artifact Signer.
    4. Click the Securesign tab, and click the Create Securesign button.
    5. On the Create Securesign page, select YAML view.

    6. You can configure different OIDC providers, such as, Red Hat build of Keycloak, Google OAuth, Amazon STS, Microsoft’s Entra ID or GitHub OAuth as the initial OIDC provider for this deployment. Under the spec.fulcio.config.OIDCIssuers section, edit the following three lines with the OIDC provider URL, and set the ClientID appropriately. 

      ...
OIDCIssuers:
  - Issuer: 'OIDC_ISSUER_URL':
    ClientID: CLIENT_ID
    IssuerURL: 'OIDC_ISSUER_URL'
    Type: email
...

      For example, if you are using Red Hat SSO, the OIDCIssuers section looks similar to this: 

      ...
OIDCIssuers:
  - Issuer: 'https://keycloak-keycloak-system.apps.example.com/auth/realms/trusted-artifact-signer':
    ClientID: trusted-artifact-signer
    IssuerURL: 'https://keycloak-keycloak-system.apps.example.com/auth/realms/trusted-artifact-signer'
    Type: email
...
      Important

      You can define several different OIDC providers in the same configuration.

    7. Optional. If you chosen to use a different database other than the default, then under the spec.trillian section, set create to false, and give the name of the database secret object. 

      ...
trillian:
  database:
    create: false
    databaseSecretRef:
      name: trillian-mysql
...
    8. Click the Create button.

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

    Note

    The Securesign instance does not give a status.

  9. You can check on the health of the new Trusted Artifact Signer service by using Prometheus in the OpenShift console. From the navigation menu, expand Observe, and click Dashboards.
  10. Verify the installation by signing a container image, or a Git commit.

Additional resources

1.3. Verify the Trusted Artifact Signer installation

As as systems administrator, you can verify if the deployment of Red Hat Trusted Artifact Signer (RHTAS) running on Red Hat OpenShift Container Platform was successful.

You can sign a test container image, and verify the authenticity of that signature to validate the deployment of RHTAS in your environment.

There are two ways to sign and three ways to verify build artifacts from your code pipeline. You can sign and verify with cosign and gitsign, but can only verify with Enterprise Contract.

1.3.1. Signing and verifying containers by using Cosign from the command-line interface

The cosign tool gives you the capability to sign and verify Open Container Initiative (OCI) container images, along with other build artifacts by using Red Hat’s Trusted Artifact Signer (RHTAS) service.

Important

For RHTAS, you must use cosign version 2.2 or later.

Prerequisites

  • Installation of RHTAS running on Red Hat OpenShift Container Platform 4.16 or later.
  • Access to the OpenShift web console.
  • A workstation with the oc, and podman binaries installed.

Procedure

  1. Download the cosign binary from the OpenShift cluster to your workstation.

    1. Login to the OpenShift web console. From the home page, click the ? icon, click Command line tools, go to the cosign download section, and click the link for your platform.

    2. Open a terminal on your workstation, decompress the binary .gz file, and set the execution bit: 

      $ gunzip cosign-amd64.gz
$ chmod +x cosign-amd64

    3. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv cosign-amd64 /usr/local/bin/cosign

  2. Log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  3. Switch to the RHTAS project: 

    oc project PROJECT_NAME
    $ oc project trusted-artifact-signer
    Note

    Use the project name for the RHTAS installation.

  4. Configure your shell environment for doing container image signing and verifying. 

    $ export BASE_HOSTNAME=_BASE_HOSTNAME_OF_RHTAS_SERVICE_
$ export TUF_URL="https://tuf-${BASE_HOSTNAME}"
$ 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

    Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of your Red Hat OpenShift domain name. An example value might look similar to this, apps.example.e8fwq-pfhxv-dvg.ex2r.p1.openshiftapps.com.

    Note

    If you are using the Ingress Operator to auto-generate route names, then you must update the oc get route …​ command by replacing keycloak with the auto-generated route name.

  5. Initialize The Update Framework (TUF) system: 

    $ cosign initialize

  6. Sign a test container image.

    1. Create an empty container image: 

      $ echo "FROM scratch" > ./tmp.Dockerfile
$ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

    2. Push the empty container image to the ttl.sh ephemeral registry: 

      $ podman push ttl.sh/rhtas/test-image:1h

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      $ cosign sign -y ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile

  7. Verify a signed container image by using a certificate identity and issuer: 

    cosign verify --certificate-identity=SIGNING_EMAIL_ADDR IMAGE_NAME:TAG
    $ cosign verify --certificate-identity=jdoe@redhat.com ttl.sh/rhtas/test-image:1h
    Note

    You can also use regular expressions for the certificate identity and issuer by using the following options to the cosign command, --certificate-identity-regexp and --certificate-oidc-issuer-regexp.

  8. Download the rekor-cli binary from the OpenShift cluster to your workstation.

    1. Login to the OpenShift web console. From the home page, click the ? icon, click Command line tools, go to the rekor-cli download section, and click the link for your platform.

    2. Open a terminal on your workstation, decompress the binary .gz file, and set the execution bit: 

      $ gunzip rekor-cli-amd64.gz
$ chmod +x rekor-cli-amd64

    3. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv rekor-cli-amd64 /usr/local/bin/rekor-cli

  9. Query the transparency log by using the Rekor command-line interface.

    1. Search based on the log index: 

      $ rekor-cli get --log-index 0 --rekor_server $COSIGN_REKOR_URL --format json | jq

    2. Search for an email address to get the universal unique identifier (UUID): 

      rekor-cli search --email SIGNING_EMAIL_ADDR --rekor_server $COSIGN_REKOR_URL --format json | jq
      $ rekor-cli search --email jdoe@redhat.com --rekor_server $COSIGN_REKOR_URL --format json | jq

      This command returns the UUID for use with the next step.

    3. Use the UUID to get the transaction details: 

      rekor-cli get --uuid UUID --rekor_server $COSIGN_REKOR_URL --format json | jq
      $ rekor-cli get --uuid 24296fb24b8ad77a71b9c1374e207537bafdd75b4f591dcee10f3f697f150d7cc5d0b725eea641e7 --rekor_server $COSIGN_REKOR_URL --format json | jq

Additional resources

1.3.2. Signing and verifying commits by using Gitsign from the command-line interface

The gitsign tool gives you the ability to sign and verify Git repository commits by using Red Hat’s Trusted Artifact Signer (RHTAS) service.

Prerequisites

  • A RHTAS installation on Red Hat OpenShift Container Platform 4.16 or later.
  • Access to the OpenShift web console.

  • A workstation with the oc, git, and cosign binaries installed.

    • You must use cosign version 2.2 or later.
  • A locally cloned Git repository.

Procedure

  1. Download the gitsign binary from the OpenShift cluster to your workstation.

    1. Login to the OpenShift web console. From the home page, click the ? icon, click Command line tools, go to the gitsign download section, and click the link for your platform.

    2. Open a terminal on your workstation, decompress the .gz file, and set the execution bit: 

      $ gunzip gitsign-amd64.gz
$ chmod +x gitsign-amd64

    3. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv gitsign-amd64 /usr/local/bin/gitsign

  2. Log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  3. Switch to the RHTAS project: 

    oc project PROJECT_NAME
    $ oc project trusted-artifact-signer
    Note

    Use the project name for the RHTAS installation.

  4. Configure your shell environment for doing commit signing and verifying: 

    $ 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
  5. Change directory (cd) to the local Git repository directory.

  6. Configure the local repository configuration to sign your 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

  7. Make a commit to the local repository: 

    $ git commit --allow-empty -S -m "Test of a signed commit"

    A web browser opens allowing you to sign the commit with an email address.

  8. Initialize The Update Framework (TUF) system: 

    $ cosign initialize

  9. Verify the commit: 

    gitsign verify --certificate-identity=SIGNING_EMAIL --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD
    $ gitsign verify --certificate-identity=jdoe@redhat.com --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD

Additional resources

1.3.3. Verifying signatures on container images with Conforma

Conforma, formally known as Enterprise Contract (EC), is a tool for maintaining the security of software supply chains, and you can use it to define and enforce policies for container images. You can use the ec binary to verify the attestation and signature of container images that use Red Hat’s Trusted Artifact Signer (RHTAS) signing framework.

Prerequisites

  • A RHTAS installation on Red Hat OpenShift Container Platform 4.16 or later.
  • Access to the OpenShift web console.

  • A workstation with the oc, cosign, and podman binaries installed.

    • You must use cosign version 2.2 or later.

Procedure

  1. Download the ec binary from the OpenShift cluster.

    1. Log in to the OpenShift web console. From the home page, click the ? icon, click Command line tools, go to the ec download section, then click the link for your platform.

    2. Open a terminal on your workstation, decompress the binary .gz file, and set the execution bit: 

      $ gunzip ec-amd64.gz
$ chmod +x ec-amd64

    3. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv ec-amd64 /usr/local/bin/ec

  2. Log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  3. Switch to the RHTAS project: 

    oc project PROJECT_NAME
    $ oc project trusted-artifact-signer
    Note

    Use the project name for the RHTAS installation.

  4. Configure your shell environment for doing container image signing and verifying. 

    $ 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

  5. Initialize The Update Framework (TUF) system: 

    $ cosign initialize

  6. Sign a test container image.

    1. Create an empty container image: 

      $ echo "FROM scratch" > ./tmp.Dockerfile
$ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

    2. Push the empty container image to the ttl.sh ephemeral registry: 

      $ podman push ttl.sh/rhtas/test-image:1h

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      $ cosign sign -y ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile

  7. Create a predicate.json file: 

    {
  "builder": {
    "id": "https://localhost/dummy-id"
  },
  "buildType": "https://example.com/tekton-pipeline",
  "invocation": {},
  "buildConfig": {},
  "metadata": {
    "completeness": {
      "parameters": false,
      "environment": false,
      "materials": false
    },
    "reproducible": false
  },
  "materials": []
}

    Refer to the Content from slsa.dev is not included.SLSA provenance predicate specifications for more information about the schema layout.

  8. Associate the predicate.json file with the container image: 

    cosign attest -y --predicate ./predicate.json --type slsaprovenance IMAGE_NAME:TAG
    $ cosign attest -y --predicate ./predicate.json --type slsaprovenance ttl.sh/rhtas/test-image:1h

  9. Verify that the container image has at least one attestation and signature: 

    cosign tree IMAGE_NAME:TAG
    $ cosign tree ttl.sh/rhtas/test-image:1h

📦 Supply Chain Security Related artifacts for an image: ttl.sh/rhtas/test-image@sha256:7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35
└── 💾 Attestations for an image tag: ttl.sh/rhtas/test-image:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.att
   └── 🍒 sha256:40d94d96a6d3ab3d94b429881e1b470ae9a3cac55a3ec874051bdecd9da06c2e
└── 🔐 Signatures for an image tag: ttl.sh/rhtas/test-image:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.sig
   └── 🍒 sha256:f32171250715d4538aec33adc40fac2343f5092631d4fc2457e2116a489387b7

  10. Verify the container image by using Conforma: 

    ec validate image --image IMAGE_NAME:TAG --certificate-identity-regexp 'SIGNER_EMAIL_ADDR' --certificate-oidc-issuer-regexp 'keycloak-system' --output yaml --show-successes
    $ ec validate image --image ttl.sh/rhtas/test-image:1h --certificate-identity-regexp 'jdoe@example.com' --certificate-oidc-issuer-regexp 'keycloak-system' --output yaml --show-successes

success: true
successes:
  - metadata:
      code: builtin.attestation.signature_check
    msg: Pass
  - metadata:
      code: builtin.attestation.syntax_check
    msg: Pass
  - metadata:
      code: builtin.image.signature_check
    msg: Pass
ec-version: v0.1.2427-499ef12
effective-time: "2024-01-21T19:57:51.338191Z"
key: ""
policy: {}
success: true

    Enterprise Contract generates a pass-fail report with details on any security violations. When you add the --info flag, the report includes more details and possible solutions for any violations found.

Additional resources

1.4. Configure additional OpenID Connect providers

As as systems administrator, you can configure many different OpenID Connect (OIDC) providers for use with Red Hat’s Trusted Artifact Signer service. You can configure the following OIDC providers for authenticating users:

  • Red Hat build of Keycloak
  • Red Hat Single Sign-on (SSO)
  • Google
  • Amazon Security Token Service (STS)
  • Microsoft Entra ID
  • GitHub

1.4.1. Configuring Google as an OpenID Connect provider for Trusted Artifact Signer

You can use Google OAuth 2.0 as your OpenID Connect (OIDC) provider for Red Hat’s Trusted Artifact Signer (RHTAS) service. You can decide to configure Google OAuth during the deployment of RHTAS, or at a later time.

Important

You can define several different OIDC providers in the same configuration.

Prerequisites

Procedure

  1. Open a terminal on your workstation, and log in to OpenShift: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL for use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  2. Update the RHTAS configuration.

    1. Open for editing the Securesign resource: 

      oc edit Securesign NAME -n NAMESPACE
      $ oc edit Securesign securesign-sample -n trusted-artifact-signer
      Note

      You must use the project name created for the RHTAS installation as the namespace.

    2. Under the OIDCIssuers section, add a new subsection with your Google client identifier, issuer’s URL, and set the Type value to email: 

      ...
OIDCIssuers:
  - Issuer: "https://accounts.google.com"
    IssuerURL: "https://accounts.google.com"
    ClientID: "CLIENT_ID"
    Type: email
...

      Add you Google client identifier to the ClientID field.

    3. Save your changes, and quit the editor. After a few seconds the operator automatically reconfigures the RHTAS software stack.

  3. Change the OIDC issuer, and client id environment variables to use Google: 

    $ export OIDC_ISSUER_URL=https://accounts.google.com
$ export COSIGN_OIDC_CLIENT_ID="314919563931-35zke44ouf2oiztjg7v8o8c2ge9usnd1.apps.googleexample.com"

  4. Copy and paste your secret from the Google Console to a plain text file: 

    echo SECRET > my-google-client-secret

  5. If you already have the RHTAS service running, you can verify the updated configuration by signing a test container image.

    1. Create an empty container image: 

      $ echo "FROM scratch" > ./tmp.Dockerfile
$ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

    2. Push the empty container image to the ttl.sh ephemeral registry: 

      $ podman push ttl.sh/rhtas/test-image:1h

    3. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile

    4. Sign the container image: 

      cosign sign -y --oidc-client-secret-file=SECRET_FILE IMAGE_NAME:TAG
      $ cosign sign -y --oidc-client-secret-file=my-google-client-secret ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

Additional resources

1.4.2. Configuring Red Hat SSO as an OpenID Connect provider for Trusted Artifact Signer

You can use Red Hat Single Sign-On (SSO) as your OpenID Connect provider for Red Hat’s Trusted Artifact Signer (RHTAS) service. This gives you a Keycloak authentication environment for applications and secure services.

Prerequisites

  • Red Hat OpenShift Container Platform 4.16 or later.
  • Access to the OpenShift web console with the cluster-admin role.
  • Have 1 GB of container storage available for the Keycloak PostgreSQL database.
  • A workstation with the oc binary installed.

Procedure

  1. Log in to the OpenShift web console with a user that has the cluster-admin role.

  2. Create a new project to deploy the Keycloak service.

    1. From the Administrator perspective, expand Home from the navigation menu, and click Projects.
    2. Click the Create Project button.
    3. The new project name is keycloak-system, and click the Create button.
  3. Expand Operators from the navigation menu, and click OperatorHub.
  4. In the search field, type sso, and click the Red Hat Single Sign-on tile.
  5. Click the Install button to show the operator details.
  6. If not already set, select keycloak-system from the Installed Namespace drop-down menu.
  7. Click Install on the Install Operator page, and wait for the installation to finish.
  8. After the installation finishes, click View Operator.

  9. From your workstation terminal, log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  10. Switch to the Keycloak project: 

    $ oc project keycloak-system

  11. Create a Keycloak instance: 

    $ cat <<EOF | oc apply -f -
apiVersion: keycloak.org/v1alpha1
kind: Keycloak
metadata:
  labels:
    app: sso
  name: keycloak
spec:
  externalAccess:
    enabled: true
  instances: 1
  keycloakDeploymentSpec:
    imagePullPolicy: Always
  postgresDeploymentSpec:
    imagePullPolicy: Always
EOF

  12. Create a Keycloak realm: 

    $ cat <<EOF | oc apply -f -
apiVersion: keycloak.org/v1alpha1
kind: KeycloakRealm
metadata:
  labels:
    app: sso
  name: trusted-artifact-signer
spec:
  instanceSelector:
    matchLabels:
      app: sso
  realm:
    displayName: Red-Hat-Trusted-Artifact-Signer
    enabled: true
    id: trusted-artifact-signer
    realm: trusted-artifact-signer
    sslRequired: none
EOF

  13. Create a Keycloak client: 

    $ cat <<EOF | oc apply -f -
apiVersion: keycloak.org/v1alpha1
kind: KeycloakClient
metadata:
  labels:
    app: sso
  name: trusted-artifact-signer
spec:
  client:
    attributes:
      request.object.signature.alg: RS256
      user.info.response.signature.alg: RS256
    clientAuthenticatorType: client-secret
    clientId: trusted-artifact-signer
    defaultClientScopes:
    - profile
    - email
    description: Client for Red Hat Trusted Artifact Signer authentication
    directAccessGrantsEnabled: true
    implicitFlowEnabled: false
    name: trusted-artifact-signer
    protocol: openid-connect
    protocolMappers:
    - config:
        claim.name: email
        id.token.claim: "true"
        jsonType.label: String
        user.attribute: email
        userinfo.token.claim: "true"
      name: email
      protocol: openid-connect
      protocolMapper: oidc-usermodel-property-mapper
    - config:
        claim.name: email-verified
        id.token.claim: "true"
        user.attribute: emailVerified
        userinfo.token.claim: "true"
      name: email-verified
      protocol: openid-connect
      protocolMapper: oidc-usermodel-property-mapper
    - config:
        claim.name: aud
        claim.value: trusted-artifact-signer
        id.token.claim: "true"
        access.token.claim: "true"
        userinfo.token.claim: "true"
      name: audience
      protocol: openid-connect
      protocolMapper: oidc-hardcoded-claim-mapper
    publicClient: true
    standardFlowEnabled: true
    redirectUris:
    - "*"
  realmSelector:
    matchLabels:
      app: sso
EOF

  14. Create a Keycloak user: 

    $ cat <<EOF | oc apply -f -
apiVersion: keycloak.org/v1alpha1
kind: KeycloakUser
metadata:
  labels:
    app: sso
  name: jdoe
spec:
  realmSelector:
    matchLabels:
      app: sso
  user:
    email: jdoe@redhat.com
    enabled: true
    emailVerified: true
    credentials:
      - type: "password"
        value: "secure"
    firstName: Jane
    lastName: Doe
    username: jdoe
EOF

    Set a user name, the user’s email address, and a password or reference a secret object.

  15. Go back to the OpenShift web console, click the All instances tab to watch and wait until the Keycloak system initializes successfully.

Additional resources

1.4.3. Configuring Red Hat build of Keycloak as an OpenID Connect provider for Trusted Artifact Signer

You can configure Red Hat’s build of Keycloak (RHBK) as an OpenID Connect (OIDC) provider for Red Hat’s Trusted Artifact Signer (RHTAS) service. This procedure guides you on integrating RHBK with RHTAS.

Important

You can define several different OIDC providers for Fulcio in the same SecureSign configuration.

Prerequisites

  • A RHTAS installation on OpenShift Container Platform 4.16 or later.
  • Access to the OpenShift web console with the cluster-admin role.
  • A workstation with the oc binary installed.
  • Have 1 GB of persistent storage available for the Keycloak PostgreSQL database.
  • A TLS certificate and key.

Procedure

  1. Log in to the OpenShift web console with a user that has the cluster-admin role.

  2. Create a new project to deploy the Keycloak service.

    1. From the Administrator perspective, expand Home from the navigation menu, and click Projects.
    2. Click the Create Project button.
    3. The new project name is keycloak-system, and click the Create button.

  3. Deploy an instance of PostgreSQL for use by Keycloak to store persistent data.

    Important

    If a database already exists for use by Keycloak, replace the username, password and database name values for the Secret resource that corresponds with your database instance. You can skip the creation of the PostgreSQL Service and StatefulSet steps, and move ahead to the next step.

    1. Create a Secret resource to store the database information.

      1. Expand Workloads from the navigation menu, and click Secrets.
      2. Select the keycloak-system from the Project drop-down menu.
      3. Click the Create drop-down menu, and select Key/Value secret.
      4. Enter postgresql-db in the Secret name field.
      5. Enter username in the Key field.
      6. Enter keycloak in the free-form field for the Value. This is the user name Keycloak uses to authenticate to the PostgreSQL database instance.
      7. Click the Add key/value link to add another key-value pair.
      8. Enter password in the Key field.
      9. Enter a password of your choice in the free-form field for the Value. This is the password Keycloak uses to authenticate to the PostgreSQL database instance.
      10. Click the Add key/value link to add another key-value pair.
      11. Enter database in the Key field.
      12. Enter keycloak in the free-form field for the Value. This is the name of the database for storing Keycloak data within the PostgreSQL database instance.
      13. Click the Create button.

    2. Create the PostgreSQL Service and StatefulSet.

      1. Click the + icon.
      2. Copy the Service and StatefulSet YAML configuration text, and on the Import YAML page, paste the text into the text editor box.
      3. Click the Create button to add the Service and StatefulSet to the keycloak-system project.
  4. Expand Operators from the navigation menu, and click OperatorHub.
  5. In the search field, type keycloak, and click the Red Hat build of Keycloak Operator tile from the certified Red Hat catalog.
  6. Click the Install button to show the operator details.
  7. On the Install Operator page, select keycloak-system from the Installed Namespace drop-down menu, and click the Install button. Wait for the installation to finish.

  8. Open a terminal from your workstation, and log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  9. Create a new Secret resource to contain the Transport Layer Security (TLS) certificate and the corresponding private key: 

    oc create secret tls SECRET_NAME -n NAMESPACE --cert CERTIFICATE_FILE_NAME --key PRIVATE_KEY_FILE_NAME
    $ oc create secret tls keycloak-tls -n keycloak-system --cert certificate.pem --key key.pem
    Note

    The OpenShift’s service serving certificate can automate the generation and management of a TLS certificates for use by Keycloak. See Configuring OpenShift service serving certificates to generate TLS certificates for Keycloak for more information.

  10. In OpenShift web console, after the installation finishes, click the View Operator button.
  11. Click Create instance on the Keycloak tile.

  12. On the Create Keycloak page, select YAML view.

    1. On the name line, replace example-keycloak with your custom name, for example, keycloak.

    2. The hostname can either be explicitly specified within the hostname property or automatically generated similar to other routes. On the hostname line, replace example.org with your custom hostname.

      Note

      See Generating Keycloak host names automatically for the steps necessary to have OpenShift generate the hostname for the Keycloak instance.

    3. Under the spec section, add your database details: 

      spec:
...
  db:
    vendor: postgres
    host: postgresql-db
    usernameSecret:
      name: postgresql-db
      key: username
    passwordSecret:
      name: postgresql-db
      key: password
...

    4. Also, under the spec section, for the http property, specify the name of the Secret resource containing the TLS certificates. 

      spec:
...
  http:
    tlsSecret: keycloak-tls
...
    5. Click the Create button.
  13. Expand the Networking navigation menu, and click Routes.
  14. To open the Keycloak Administration Console, click the link to the route associated with the Keycloak instance.
  15. The default credentials for the admin user are stored in a Secret called keycloak-initial-admin. To locate the password, expand the Workloads navigation menu, and click Secrets.
  16. Select the keycloak-initial-admin Secret.
  17. Under the Data section, locate the password key, and click the copy icon.
  18. On the Keycloak Administration Console log in page, enter temp-admin as the username, and paste the contents of the previous step as the password.

  19. Create a new realm called trusted-artifact-signer.

    1. On the navigation menu, select the Red Hat Build of Keycloak drop-down menu.
    2. Select Create Realm.
    3. Enter trusted-artifact-signer as the Resource name.
    4. Click Create to create the new realm.

  20. Create a new client.

    1. On the navigation menu, under the Manage section, and select Clients.
    2. Click the Create Client button
    3. In the Client Id field, enter trusted-artifact-signer.
    4. Optionally, you can enter a Name and Description into the corresponding fields.
    5. Click Next.
    6. Accept the default options for the Capability Config step of the new client creation process.
    7. Click Next.
    8. In the Valid redirect URIs field, enter *.
    9. Click Save to create the client.
  21. On the navigation menu, under the Configure section, select Realm Settings to locate the Issuer URL for the trusted-artifact-signer realm.
  22. Next to Endpoints, click the OpenID Endpoint Configuration link.
  23. Copy the URL from the issuer property.

  24. Under the .spec.fulcio.config.OIDCIssuers section of the SecureSign resource for RHTAS, replace CLIENT_ID with trusted-artifact-signer, and paste the URL content to replace RHBK_REALM_ISSUER_URL: 

    spec:
...
  fulcio:
    config:
      OIDCIssuers:
        - ClientID: CLIENT_ID
          Issuer: 'RHBK_REALM_ISSUER_URL'
          IssuerURL: 'RHBK_REALM_ISSUER_URL'
          Type: email
...
    spec:
...
  fulcio:
    config:
      OIDCIssuers:
        - ClientID: trusted-artifact-signer
          Issuer: 'https://keycloak-ingress-keycloak-system.apps.openshift.example.com/realms/trusted-artifact-signer'
          IssuerURL: 'https://keycloak-ingress-keycloak-system.apps.openshift.example.com/realms/trusted-artifact-signer'
          Type: email
...

Additional resources

1.4.4. Configuring Amazon STS as an OpenID Connect provider for Trusted Artifact Signer

You can use Amazon’s Security Token Service (STS) as your OpenID Connect (OIDC) provider for Red Hat’s Trusted Artifact Signer (RHTAS) service. You can decide to configure Amazon STS during the deployment of RHTAS, or at a later time.

Important

You can define several different OIDC providers in the same configuration.

Prerequisites

Procedure

  1. Open a terminal on your workstation, and log in to OpenShift: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL for use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  2. Find the AWS OIDC provider URL: 

    $ oc get authentication cluster -o jsonpath='{.spec.serviceAccountIssuer}'

  3. Update RHTAS the configuration.

    1. Open for editing the Securesign resource: 

      oc edit Securesign NAME -n NAMESPACE
      $ oc edit Securesign securesign-sample -n trusted-artifact-signer
      Note

      You must use the project name created for the RHTAS installation as the namespace.

    2. Under the OIDCIssuers section, add a new subsection with your AWS STS client identifier, issuer’s URL, and set the Type value to kubernetes: 

      ...
OIDCIssuers:
  - Issuer: "https://example.s3.us-east-1.aws.com/47bd6cg0vs5nn01mue83fbof94dj4m9c"
    IssuerURL: "https://example.s3.us-east-1.aws.com/47bd6cg0vs5nn01mue83fbof94dj4m9c"
    ClientID: "trusted-artifact-signer"
    Type: kubernetes
...
    3. Save your changes, and quit the editor. After a few seconds the operator automatically reconfigures the RHTAS software stack.

  4. Configure the AWS command-line tool by entering your access key, secret key, default region, and output format: 

    $ aws configure

  5. Set the following environment variables: 

    $ export account_id=$(aws sts get-caller-identity --query "Account" --output text)
$ export oidc_provider="$(oc get authentication cluster -o jsonpath='{.spec.serviceAccountIssuer}' | cut -d '/' -f3-)"
$ export role_name=rhtas-sts
$ export namespace=rhtas-sts
$ export service_account=cosign-sts

  6. Create a Trust Policy that gets associated with newly created IAM roles: 

    $ cat >trust-relationship.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::${account_id}:oidc-provider/${oidc_provider}"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "${oidc_provider}:aud": "trusted-artifact-signer"
        }
      }
    }
  ]
}
EOF

  7. Create a new IAM role for the RHTAS service by using the trust policy: 

    $ aws iam create-role --role-name rhtas-sts --assume-role-policy-document file://trust-relationship.json --description "Red Hat Trusted Artifact Signer STS Role"

  8. On the OpenShift cluster with STS enabled, create a new project namespace: 

    oc new-project NAMESPACE
    $ oc new-project rhtas-sts

  9. Create a service account for assuming an IAM role, and running a workload within the OpenShift project namespace.

    1. Create the service account manifest: 

      $ cat >service_account.yaml <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: $service_account
  namespace: $namespace
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::${account_id}:role/${role_name}"
    # optional: Defaults to "sts.amazonaws.com" if not set
    eks.amazonaws.com/audience: "trusted-artifact-signer"
    # optional: When "true", adds AWS_STS_REGIONAL_ENDPOINTS env var to containers
    eks.amazonaws.com/sts-regional-endpoints: "true"
    # optional: Defaults to 86400 for expirationSeconds if not set
    eks.amazonaws.com/token-expiration: "86400"
EOF

    2. Apply the service account manifest to OpenShift: 

      $ oc apply -f service_account.yaml

  10. Create a new deployment workload for signing container images within a image registry.

    1. Create the deployment manifest: 

      $ cat >deployment.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cosign-sts
  namespace: ${namespace}
spec:
  selector:
    matchLabels:
      app: cosign-sts
  template:
    metadata:
      labels:
        app: cosign-sts
    spec:
      securityContext:
        runAsNonRoot: true
      serviceAccountName: cosign-sts
      containers:
      - args:
        - -c
        - env; cosign initialize --mirror=\$COSIGN_MIRROR --root=\$COSIGN_ROOT; while true; do sleep 86400; done
        command:
        - /bin/sh
        name: cosign
        image: registry.redhat.io/rhtas-tech-preview/cosign-rhel9@sha256:f4c2cec3fc1e24bbe094b511f6fe2fe3c6fa972da0edacaf6ac5672f06253a3e
        pullPolicy: IfNotPresent
        env:
        - name: AWS_ROLE_SESSION_NAME
          value: signer-identity-session
        - name: AWS_REGION
          value: us-east-1
        - name: OPENSHIFT_APPS_SUBDOMAIN
          value: $(oc get cm -n openshift-config-managed  console-public -o go-template="{{ .data.consoleURL }}" | sed 's@https://@@; s/^[^.]*\.//')
        - name: OIDC_AUTHENTICATION_REALM
          value: "trusted-artifact-signer"
        - name: COSIGN_FULCIO_URL
          value: $(oc get fulcio -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
        - name: COSIGN_OIDC_ISSUER
          value: $(oc get authentication cluster -o jsonpath='{.spec.serviceAccountIssuer}')
        - name: COSIGN_CERTIFICATE_OIDC_ISSUER
          value: $(oc get authentication cluster -o jsonpath='{.spec.serviceAccountIssuer}')
        - name: COSIGN_REKOR_URL
          value: $(oc get rekor -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
        - name: COSIGN_MIRROR
          value: $(oc get tuf -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
        - name: COSIGN_ROOT
          value: "$(oc get tuf -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)/root.json"
        - name: COSIGN_YES
          value: "true"
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext:
        runAsNonRoot: true
      serviceAccount: ${service_account}
      serviceAccountName: ${service_account}
      terminationGracePeriodSeconds: 30
EOF

    2. Apply the deployment manifest to OpenShift: 

      $ oc apply -f deployment.yaml

  11. Create a test container image to sign.

    1. Create an empty container image: 

      $ echo "FROM scratch" > ./tmp.Dockerfile
$ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

    2. Push the empty container image to the ttl.sh ephemeral registry: 

      $ podman push ttl.sh/rhtas/test-image:1h

    3. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile

  12. Validate the configuration by signing and verifying the test container image.

    1. Open a remote shell session within a running pod: 

      oc rsh -n NAMESPACE deployment/cosign-sts env IMAGE=IMAGE_NAME:TAG /bin/sh
      $ oc rsh -n rhtas-sts deployment/cosign-sts env IMAGE=ttl.sh/rhtas/test-image:1h /bin/sh

    2. Sign the container image: 

      $ cosign sign -y --identity-token=$(cat $AWS_WEB_IDENTITY_TOKEN_FILE) ttl.sh/rhtas/test-image:1h

    3. Verify the signed container image: 

      $ cosign verify --certificate-identity=https://kubernetes.io/namespaces/$(cat /var/run/secrets/kubernetes.io/serviceaccount/namespace)/serviceaccounts/cosign-sts --certificate-oidc-issuer=$COSIGN_CERTIFICATE_OIDC_ISSUER ttl.sh/rhtas/test-image:1h

1.4.5. Configuring GitHub as an OpenID Connect provider for Trusted Artifact Signer

You can use GitHub OAuth 2.0 when federating it with Red Hat’s Single Sign-On (SSO) service as an OpenID Connect (OIDC) provider for the Red Hat Trusted Artifact Signer (RHTAS) service. This procedure guides you on integrating GitHub OAuth with an existing Red Hat SSO deployment on OpenShift.

Important

You can define several different OIDC providers in the same configuration.

Prerequisites

Procedure

  1. Open a terminal on your workstation, and log in to OpenShift: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL for use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  2. Log in to the Red Hat SSO console.

    1. Find the Red Hat SSO console URL from the command line: 

      $ oc get routes -n keycloak-system keycloak -o jsonpath='https://{.spec.host}'
    2. Copy and paste the Red Hat SSO console URL into your web browser.
    3. Click Administration Console.

    4. Retrieve the admin password from the command line: 

      $ oc get secret/credential-keycloak -n keycloak-system -o jsonpath='{ .data.ADMIN_PASSWORD }' | base64 -d

      Copy the output from this command.

    5. From your web browser, log in as the admin user, and paste the password in the corresponding field. Click the Sign In button.
  3. Select your realm from the dropdown on the navigation menu.

  4. Add the GitHub identity provider.

    1. From the navigational menu, click Identity Providers.
    2. From the Add provider… drop-down menu, select GitHub.
    3. Add your GitHub OAuth client identifier to the Client ID field.
    4. Add your GitHub OAuth client secret to the Client Secret field.
    5. Turn on the Trust Email option.
    6. Click the Save button.

  5. Add the identity provider mapper to the newly created identity provider.

    1. Click the Mapper tab.
    2. Click the Create button.
    3. Give a Name to the new mapper.
    4. Change the Mapper Type to Hardcoded Attribute.
    5. Set the User Attribute field to emailVerified.
    6. Set the User Attribute Value field to true.
    7. Click the Save button.
  6. From the GitHub Identity Provider Settings page, copy the Redirect URI value and paste it to your GitHub OAuth app Authorization Callback URL field. Also, paste this same value into the Homepage URL field, but remove the broker/github/endpoint part of the URL string.
  7. Click Update Application. You can now sign commits, and containers by using GitHub as your OIDC provider.
  8. When signing artifacts, a web browser opens and prompts you to sign in to your Red Hat SSO account. Click the GitHub button to sign in with your credentials.
  9. Click the Authorize button to enable GitHub user details to be accessible by Red Hat SSO.

Additional resources

1.4.6. Configuring Microsoft Entra ID as an OpenID Connect provider for Trusted Artifact Signer

You can use Microsoft Entra ID as your OpenID Connect (OIDC) provider for Red Hat’s Trusted Artifact Signer (RHTAS) service. You can decide to configure Microsoft Entra ID during the deployment of RHTAS, or at a later time.

Note

Integrating Microsoft Entra ID into RHTAS requires no subscriptions.

Important

You can define several different OIDC providers in the same configuration.

Prerequisites

  • Red Hat OpenShift Container Platform 4.16 or later.
  • A Microsoft Azure account with permissions to create resources.
  • An Azure verified email address for users signing artifacts.
  • Access to the Microsoft Azure command-line interface.
  • A workstation with the oc, cosign, podman, and az binaries installed.

Procedure

  1. Open a terminal on your workstation.

  2. Create an App Registration within Microsoft Entra ID representing a client: 

    $ export RHTAS_APP_REGISTRATION=$(az ad app create --display-name=rhtas --web-redirect-uris=http://localhost:0/auth/callback --enable-id-token-issuance --query appId -o tsv)

  3. Create a new client secret that allows user to use the App Registration to get a ID token: 

    $ export RHTAS_APP_REGISTRATION_CLIENT_SECRET=$(az ad app credential reset --id=$RHTAS_APP_REGISTRATION --display-name="RHTAS Client Secret" -o tsv --query 'password')
    Note

    By default, client secrets are only valid for one year. You can customize this value by using the --years or --end-date flags.

  4. Create a new Claim Mapping Policy to define a new JWT claim called email_verified, use a static value of true: 

    $ az rest -m post --headers Content-Type=application/json --uri https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies --body '{"definition": ["{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\", \"ClaimsSchema\":[{\"value\":\"true\",\"JwtClaimType\":\"email_verified\"}]}}"],"displayName": "EmailVerified"}'

  5. Get the App Registration object identifier: 

    $ export RHTAS_APP_REGISTRATION_OBJ_ID=$(az ad app show --id $RHTAS_APP_REGISTRATION --output tsv --query id)

  6. Update the App Registration manifest: 

    $ az rest --method PATCH --uri https://graph.microsoft.com/v1.0/applications/${RHTAS_APP_REGISTRATION_OBJ_ID} --headers 'Content-Type=application/json' --body "{\"api\":{\"acceptMappedClaims\":true}}"

  7. Create a new Service Principal and associate it with the App Registration: 

    $ export SERVICE_PRINCIPAL_ID=$(az ad sp create --id=${RHTAS_APP_REGISTRATION} -o tsv --query 'id')

  8. Get the Claim Mapping Policy identifier: 

    $ export CLAIM_MAPPING_POLICY_ID=$(az rest --uri https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies -o tsv --query "value[?displayName=='EmailVerified'] | [0].id")

  9. Associate the Claim Mapping Policy with the Service Principal: 

    $ az rest -m post --headers Content-Type=application/json --uri "https://graph.microsoft.com/v1.0/servicePrincipals/${SERVICE_PRINCIPAL_ID}/claimsMappingPolicies/\$ref" --body "{\"@odata.id\": \"https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/${CLAIM_MAPPING_POLICY_ID}\"}"

  10. Get the tenant identifier: 

    $ export TENANT_ID=$(az account show -o tsv --query tenantId)

  11. Get OIDC endpoint: 

    $ export ENTRA_ID_OIDC_ENDPOINT=$(echo https://login.microsoftonline.com/${TENANT_ID}/v2.0)

  12. Update the RHTAS configuration.

    1. Open for editing the Securesign resource: 

      oc edit Securesign NAME -n NAMESPACE
      $ oc edit Securesign securesign-sample -n trusted-artifact-signer
      Note

      You must use the project name created for the RHTAS installation as the namespace.

    2. Under the OIDCIssuers section, add a new subsection with the client identifier, issuer’s URL, and set the Type value to email: 

      ...
OIDCIssuers:
  - Issuer: "${ENTRA_ID_OIDC_ENDPOINT}"
    IssuerURL: "${ENTRA_ID_OIDC_ENDPOINT}"
    ClientID: "${RHTAS_APP_REGISTRATION}"
    Type: email
...
    3. Save your changes, and quit the editor. After a few seconds the operator automatically reconfigures the RHTAS software stack.

  13. Create a local client secret file: 

    $ echo $RHTAS_APP_REGISTRATION_CLIENT_SECRET > rhtas-entra-id-client-secret

  14. Configure your shell environment for signing artifacts: 

    $ export TUF_URL=$(oc get tuf -n trusted-artifact-signer -o jsonpath='{.items[0].status.url}')
$ export OIDC_ISSUER_URL=$(oc get securesign -n trusted-artifact-signer rhtas -o jsonpath='{ .spec.fulcio.config.OIDCIssuers[0].Issuer }')
$ 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=$RHTAS_APP_REGISTRATION
$ export SIGSTORE_OIDC_CLIENT_ID=$COSIGN_OIDC_CLIENT_ID
$ export COSIGN_OIDC_ISSUER=$OIDC_ISSUER_URL
$ export COSIGN_CERTIFICATE_OIDC_ISSUER=$OIDC_ISSUER_URL
$ export COSIGN_YES="true"
$ export COSIGN_FULCIO_URL=$(oc get fulcio -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
$ export SIGSTORE_FULCIO_URL=$COSIGN_FULCIO_URL
$ export SIGSTORE_OIDC_ISSUER=$COSIGN_OIDC_ISSUER
$ export SIGSTORE_REKOR_URL=$COSIGN_REKOR_URL
$ export COSIGN_OIDC_CLIENT_SECRET_FILE=$(pwd)/rhtas-entra-id-client-secret

  15. Initialize the local machine for signing: 

    $ cosign initialize

  16. Verify the updated configuration by signing a test container image.

    1. Create an empty container image: 

      $ echo "FROM scratch" > ./tmp.Dockerfile
$ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

    2. Push the empty container image to the ttl.sh ephemeral registry: 

      $ podman push ttl.sh/rhtas/test-image:1h

    3. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile

    4. Sign the container image: 

      cosign sign -y --oidc-client-secret-file=SECRET_FILE IMAGE_NAME:TAG
      $ cosign sign -y --oidc-client-secret-file=rhtas-entra-id-client-secret ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

Additional resources

1.5. Configure an alternative database for Trusted Artifact Signer

You can replace the Red Hat Trusted Artifact Signer (RHTAS) default database for Trillian with an externally managed MariaDB database instance. The database instance can be a cloud-hosted database provider, such as Amazon’s Relational Database Service (RDS), or your own database deployment in OpenShift.

1.5.1. Prerequisites

  • Red Hat OpenShift Container Platform version 4.16 or later.

1.5.2. Configuring Amazon RDS for Trusted Artifact Signer

With this procedure, you can replace Red Hat’s Trusted Artifact Signer (RHTAS) default database for Trillian with a MariaDB instance managed by Amazon’s Relational Database Service (RDS).

Important

Red Hat recommends using a highly available MariaDB database for production workloads.

Prerequisites

  • An Amazon Web Service (AWS) account with access to the Amazon RDS console.
  • Access to the OpenShift web console with the cluster-admin role.
  • A workstation with the oc, curl, and the mysql binaries installed.
  • Command-line access with privileges to create a database and populate the MariaDB instance.

Procedure

  1. Open the Content from console.aws.amazon.com is not included.Amazon RDS console, and Content from docs.aws.amazon.com is not included.create a new MariaDB instance.

    1. Wait for the MariaDB instance to be deployed, and is available.

  2. From your workstation, log in to the new database by providing the regional endpoint, the port, and the user credentials: 

    mysql -h REGIONAL_ENDPOINT -P 3306 -u USER_NAME -p
    $ mysql -h exampledb.1234.us-east-1.rds.amazonaws.com -P 3306 -u admin -p

  3. Create a new database named trillian: 

    create database trillian;

  4. Switch to the newly created database: 

    use trillian;

  5. Create a new database user named trillian, and set a PASSWORD for the newly created user: 

    CREATE USER trillian@'%' IDENTIFIED BY 'PASSWORD';
GRANT ALL PRIVILEGES ON trillian.* TO 'trillian'@'%';
FLUSH PRIVILEGES;

  6. Disconnect from the database: 

    EXIT

  7. Download the database configuration file: 

    $ curl -o dbconfig.sql https://raw.githubusercontent.com/securesign/trillian/main/storage/mysql/schema/storage.sql

  8. Apply the database configuration to the new database: 

    mysql -h FQDN_or_SERVICE_ADDR -P 3306 -u USER_NAME -p PASSWORD -D DB_NAME < PATH_TO_CONFIG_FILE
    $ mysql -h rhtasdb.example.com -P 3306 -u trillian -p mypassword123 -D trillian < dbconfig.sql

  9. Open a terminal on your workstation, and log in to OpenShift: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL for use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  10. Create a new Secret containing the credentials for the Trillian database within the MariaDB instance which was created previously: 

    oc create secret generic OBJECT_NAME \
--from-literal=mysql-database=trillian \
--from-literal=mysql-host=FQDN_or_SERVICE_ADDR \
--from-literal=mysql-password=PASSWORD \
--from-literal=mysql-port=3306 \
--from-literal=mysql-root-password=PASSWORD \
--from-literal=mysql-user=USER_NAME
    $ oc create secret generic trillian-mysql \
--from-literal=mysql-database=trillian \
--from-literal=mysql-host=mariadb.trusted-artifact-signer.svc.cluster.local \
--from-literal=mysql-password=mypassword123 \
--from-literal=mysql-port=3306 \
--from-literal=mysql-root-password=myrootpassword123 \
--from-literal=mysql-user=trillian

    You can use an OpenShift internal service name for the MariaDB instance.

  11. You can now deploy the Trusted Artifact Signer service to use this database. If you were following the Trusted Artifact Signer installation procedure, then you can proceed to the next step.

Additional resources

1.5.3. Configuring a database in OpenShift for Trusted Artifact Signer

With this procedure, you can replace Red Hat’s Trusted Artifact Signer (RHTAS) default database for Trillian with a MariaDB instance managed by Amazon’s Relational Database Service (RDS).

Important

Red Hat recommends using a highly available MariaDB database for production workloads.

Prerequisites

  • Permissions to create an OpenShift project, and deploy a database instance from the OpenShift samples catalog.
  • Access to the OpenShift web console with the cluster-admin role.
  • A workstation with the oc, curl, and the mysql binaries installed.
  • Command-line access with privileges to create a database and populate the MariaDB instance.

Procedure

  1. Log in to the OpenShift web console where you are deploying the RHTAS service:
  2. Change to the Developer perspective.

  3. Select the trusted-artifact-signer project, if the project already exists, else create a new project for the database:

    1. To create a new project, click the drop-down project menu, and click the Create Project button.
    2. Name the new project trusted-artifact-signer, and click the Create button.
  4. On the Developer Catalog card, click Database.

  5. Select MariaDB, and click the Instantiate Template button.

    Important

    Do not select MariaDB (Ephemeral).

  6. On the Instantiate Template page, configure the following fields:

    1. In the MariaDB Database Name field, enter trillian.
    2. In the Volume Capacity field, enter 5Gi.
    3. Click the Create button.

  7. Begin a remote shell session:

    1. On the Topology page, selecting the MariaDB pod brings up a side panel, click the Resources tab.
    2. Under the Pods section, click on the MariaDB pod name.
    3. Click the Terminal tab to start a remote shell session to the MariaDB pod.

  8. In the remote shell session, verify that you can connect to the Trillian database: 

    $ mysql -u $MYSQL_USER -p$MYSQL_PASSWORD -D$MYSQL_DATABASE
    Note

    Credentials are stored in a secret object with the service name (mariadb), and contains the name of the database, and user name, along with the database root password. Make a note of these credentials as they will be used later on when creating the database secret object.

  9. Disconnect from the database: 

    EXIT

  10. Download the database configuration file: 

    $ curl -o dbconfig.sql https://raw.githubusercontent.com/securesign/trillian/main/storage/mysql/schema/storage.sql

  11. Apply the database configuration to the new database: 

    mysql -h FQDN_or_SERVICE_ADDR -P 3306 -u USER_NAME -p PASSWORD -D DB_NAME < PATH_TO_CONFIG_FILE
    $ mysql -h rhtasdb.example.com -P 3306 -u trillian -p mypassword123 -D trillian < dbconfig.sql

  12. Open a terminal on your workstation, and log in to OpenShift: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note

    You can find your login token and URL for use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

  13. Create a new Secret containing the credentials for the Trillian database within the MariaDB instance which was created previously: 

    oc create secret generic OBJECT_NAME \
--from-literal=mysql-database=trillian \
--from-literal=mysql-host=FQDN_or_SERVICE_ADDR \
--from-literal=mysql-password=PASSWORD \
--from-literal=mysql-port=3306 \
--from-literal=mysql-root-password=PASSWORD \
--from-literal=mysql-user=USER_NAME
    $ oc create secret generic trillian-mysql \
--from-literal=mysql-database=trillian \
--from-literal=mysql-host=mariadb.trusted-artifact-signer.svc.cluster.local \
--from-literal=mysql-password=mypassword123 \
--from-literal=mysql-port=3306 \
--from-literal=mysql-root-password=myrootpassword123 \
--from-literal=mysql-user=trillian

    You can use an OpenShift internal service name for the MariaDB instance.

  14. You can now deploy the Trusted Artifact Signer service to use this database. If you were following the Trusted Artifact Signer installation procedure, then you can proceed to the next step.

Additional resources

1.6. Configuring OpenShift service serving certificates to generate TLS certificates for Keycloak

OpenShift’s service serving certificate can automate the generation and management of Transport Layer Security (TLS) certificates for use by Keycloak. Infrastructure components, such as the Ingress Controller, within an OpenShift cluster will trust these TLS certificates.

Prerequisites

  • Red Hat OpenShift Container Platform 4.16 or later.
  • Installation of the Red Hat build of Keycloak (RHBK) Operator.
  • Access to the OpenShift web console with the cluster-admin role.

Procedure

  1. In OpenShift web console, from the Administrator perspective, expand Home from the navigation menu, and click Projects.
  2. Search for keycloak, and select the keycloak-system namespace.

  3. Create a new service.

    1. Click the + icon.

    2. In the Import YAML text box, copy the example, and paste it into the text box. 

      apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.openshift.io/serving-cert-secret-name: keycloak-tls
  labels:
    app: keycloak
    app.kubernetes.io/instance: keycloak
  name: keycloak-service-trusted
  namespace: keycloak-system
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
  - IPv4
  ipFamilyPolicy: SingleStack
  ports:
  - name: https
    port: 8443
  selector:
    app: keycloak
    app.kubernetes.io/instance: keycloak
    3. Click the Create button.
  4. Expand Operators from the navigation menu, click Installed Operators, and click the Red Hat build of Keycloak Operator tile.

  5. In the YAML view of the Keycloak resource, under the spec section, add the ingress property: 

    spec:
...
  ingress:
    annotations:
      route.openshift.io/destination-ca-certificate-secret: keycloak-tls
      route.openshift.io/termination: reencrypt
...

    By default, the Keycloak Operator creates Ingress resources instead of routes. OpenShift automatically creates a route based on the Ingress definition.

  6. Specify the name of the secret containing the TLS certificate, under the spec section: 

    spec:
...
  http:
    tlsSecret: keycloak-tls
...

    Once Keycloak starts, OpenShift’s service serving certificate starts generating TLS certificates for Keycloak.

Additional resources

1.7. Generating Keycloak host names automatically

OpenShift routes has support for automatically generating host names by using a set pattern. This feature can integrate with Red Hat’s build of Keycloak (RHBK) operator running on OpenShift.

Prerequisites

  • Red Hat OpenShift Container Platform 4.16 or later.
  • Installation of the RHBK operator.
  • Access to the OpenShift web console with the cluster-admin role.
  • A workstation with the oc binary installed.

Procedure

  1. Enable the automatically generated route hostname feature.

    1. Under the .spec section, remove the entire hostname section, and replace it with the ingress section and className property within the Keycloak resource: 

      spec:
...
  [.line-through]#hostname:#
    [.line-through]#hostname: example.com#
...
      spec:
...
  ingress:
    className: openshift-default
...
      Note

      To view all of the available Ingress classes, run the following command: 

      $ oc get ingressclass
    2. Click the Save button.

  2. Verify the automatically generated hostname by clicking the Reload button to view the latest configuration: 

    spec:
...
  hostname:
    hostname: example-keycloak-ingress-keycloak-system.apps.rhtas.example.com
...

Chapter 2. Red Hat Enterprise Linux

2.1. Installing Trusted Artifact Signer using Ansible

You can install the Red Hat Trusted Artifact Signer (RHTAS) on Red Hat Enterprise Linux by using a Red Hat provided Ansible Playbook. This deployment gives you a basic signing framework with Keycloak as the OpenID Connect (OIDC) provider.

Warning

Red Hat recommends not to use Ansible logging in verbose or debugging mode for production environments.

For more information, see the Ansible Content from docs.ansible.com is not included.documentation.

Prerequisites

  • Red Hat Enterprise Linux version 9.4 or later.
  • A Red Hat user account to access the Red Hat Hybrid Cloud Console.

Procedure

  1. Log in to the This content is not included.Red Hat Hybrid Cloud Console with your Red Hat credentials.
  2. From the home page, click the Services drop-down menu, and click Red Hat Ansible Automation Platform.
  3. From the navigational menu, expand Automation Hub, and click Collections.
  4. In the search field type rhtas and press enter.
  5. Click the artifact_signer link on the Red Hat Trusted Artifact Signer tile.

  6. Click the Documentation tab, and follow the steps there to complete the installation of RHTAS on Red Hat Enterprise Linux.

    Note

    For a detailed overview of all the configuration parameters, click the tas_single_node link under the Roles section.

Additional resources

2.2. Verify the Trusted Artifact Signer installation

As as systems administrator, you can verify if the deployment of Red Hat Trusted Artifact Signer (RHTAS) running on Red Hat Enterprise Linux was successful.

You can sign a test container image, and verify the authenticity of that signature to validate the deployment of RHTAS in your environment.

There are two ways to sign and three ways to verify build artifacts from your code pipeline. You can sign and verify with cosign and gitsign, but can only verify with Enterprise Contract.

2.2.1. Signing and verifying containers by using Cosign from the command-line interface

The cosign tool gives you the capability to sign and verify Open Container Initiative (OCI) container images, along with other build artifacts by using Red Hat’s Trusted Artifact Signer (RHTAS) service.

Important

For RHTAS, you must use cosign version 2.2 or later.

Prerequisites

  • Installation of RHTAS running on Red Hat Enterprise Linux 9.4 or later managed by Ansible.
  • A workstation with the podman binary installed.

Procedure

  1. Download the cosign binary from the local command-line interface (CLI) tool download page to your workstation.

    Note

    The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, Content from cli-server.example.com is not included.https://cli-server.example.com, given the tas_single_node_base_hostname value as example.com.

    1. From the download page, go to the cosign download section, and click the link for your platform.

    2. Open a terminal on your workstation, decompress the binary .gz file, and set the execution bit: 

      $ gunzip cosign-amd64.gz
$ chmod +x cosign-amd64

    3. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv cosign-amd64 /usr/local/bin/cosign

  2. Configure your shell environment for doing container image signing and verifying. 

    $ export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
$ export TUF_URL="https://tuf-${BASE_HOSTNAME}"
$ export OIDC_ISSUER_URL=OIDC_ISSUER_URL
$ export COSIGN_FULCIO_URL="https://fulcio.${BASE_HOSTNAME}"
$ export COSIGN_REKOR_URL="https://rekor.${BASE_HOSTNAME}"
$ 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

    Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname variable, and replace OIDC_ISSUER_URL with your OpenID Connect (OIDC) provider’s URL string.

  3. Initialize The Update Framework (TUF) system: 

    $ cosign initialize

  4. Sign a test container image.

    1. Create an empty container image: 

      $ echo "FROM scratch" > ./tmp.Dockerfile
$ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

    2. Push the empty container image to the ttl.sh ephemeral registry: 

      $ podman push ttl.sh/rhtas/test-image:1h

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      $ cosign sign -y ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile

  5. Verify a signed container image by using a certificate identity and issuer: 

    cosign verify --certificate-identity=SIGNING_EMAIL_ADDR IMAGE_NAME:TAG
    $ cosign verify --certificate-identity=jdoe@redhat.com ttl.sh/rhtas/test-image:1h
    Note

    You can also use regular expressions for the certificate identity and issuer by using the following options to the cosign command, --certificate-identity-regexp and --certificate-oidc-issuer-regexp.

  6. Download the rekor-cli binary from the local command-line interface (CLI) tool download page to your workstation.

    1. Open a web browser, and go to the CLI server web page.

      Note

      The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, Content from cli-server.example.com is not included.https://cli-server.example.com, given that the value of tas_single_node_base_hostname is example.com.

    2. From the download page, go to the rekor-cli download section, and click the link for your platform.

    3. Open a terminal on your workstation, decompress the binary .gz file, and set the execution bit: 

      $ gunzip rekor-cli-amd64.gz
$ chmod +x rekor-cli-amd64

    4. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv rekor-cli-amd64 /usr/local/bin/rekor-cli

  7. Query the transparency log by using the Rekor command-line interface.

    1. Search based on the log index: 

      $ rekor-cli get --log-index 0 --rekor_server $COSIGN_REKOR_URL --format json | jq

    2. Search for an email address to get the universal unique identifier (UUID): 

      rekor-cli search --email SIGNING_EMAIL_ADDR --rekor_server $COSIGN_REKOR_URL --format json | jq
      $ rekor-cli search --email jdoe@redhat.com --rekor_server $COSIGN_REKOR_URL --format json | jq

      This command returns the UUID for use with the next step.

    3. Use the UUID to get the transaction details: 

      rekor-cli get --uuid UUID --rekor_server $COSIGN_REKOR_URL --format json | jq
      $ rekor-cli get --uuid 24296fb24b8ad77a71b9c1374e207537bafdd75b4f591dcee10f3f697f150d7cc5d0b725eea641e7 --rekor_server $COSIGN_REKOR_URL --format json | jq

Additional resources

2.2.2. Signing and verifying commits by using Gitsign from the command-line interface

The gitsign tool gives you the ability to sign and verify Git repository commits by using Red Hat’s Trusted Artifact Signer (RHTAS) service.

Prerequisites

  • Installation of RHTAS running on Red Hat Enterprise Linux 9.4 or later managed by Ansible.

  • A workstation with the git, and cosign binaries installed.

    • You must use cosign version 2.2 or later.
  • A locally cloned Git repository.

Procedure

  1. Download the gitsign binary from the local command-line interface (CLI) tool download page to your workstation.

    Note

    The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, Content from cli-server.example.com is not included.https://cli-server.example.com, given the tas_single_node_base_hostname value as example.com.

    1. From the download page, go to the gitsign download section, and click the link for your platform.

    2. Open a terminal on your workstation, decompress the .gz file, and set the execution bit: 

      $ gunzip gitsign-amd64.gz
$ chmod +x gitsign-amd64

    3. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv gitsign-amd64 /usr/local/bin/gitsign

  2. Configure your shell environment for doing commit signing and verifying. 

    $ export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
$ export TUF_URL="https://tuf.${BASE_HOSTNAME}"
$ export OIDC_ISSUER_URL=OIDC_ISSUER_URL
$ export COSIGN_FULCIO_URL="https://fulcio.${BASE_HOSTNAME}"
$ export COSIGN_REKOR_URL="https://rekor.${BASE_HOSTNAME}"
$ 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

    Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname` variable, and replace OIDC_ISSUER_URL with your OpenID Connect (OIDC) provider’s URL string.

  3. Change directory (cd) to the local Git repository directory.

  4. Configure the local repository configuration to sign your 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

  5. Make a commit to the local repository: 

    $ git commit --allow-empty -S -m "Test of a signed commit"

    A web browser opens allowing you to sign the commit with an email address.

  6. Initialize The Update Framework (TUF) system: 

    $ cosign initialize

  7. Verify the commit: 

    gitsign verify --certificate-identity=SIGNING_EMAIL --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD
    $ gitsign verify --certificate-identity=jdoe@redhat.com --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD

Additional resources

2.2.3. Verifying signatures on container images with Conforma

Conforma, formally known as Enterprise Contract (EC), is a tool for maintaining the security of software supply chains, and you can use it to define and enforce policies for container images. You can use the ec binary to verify the attestation and signature of container images that use Red Hat’s Trusted Artifact Signer (RHTAS) signing framework.

Prerequisites

  • Installation of RHTAS running on Red Hat Enterprise Linux 9.4 or later managed by Ansible.

  • A workstation with the cosign, and podman binaries installed.

    • You must use cosign version 2.2 or later.

Procedure

  1. Download the ec binary from the local command-line interface (CLI) tool download page to your workstation.

    Note

    The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, Content from cli-server.example.com is not included.https://cli-server.example.com, given the tas_single_node_base_hostname value as example.com.

    1. From the download page, go to the ec download section, and click the link for your platform.

    2. Open a terminal on your workstation, decompress the binary .gz file, and set the execution bit: 

      $ gunzip ec-amd64.gz
$ chmod +x ec-amd64

    3. Move and rename the binary to a location within your $PATH environment: 

      $ sudo mv ec-amd64 /usr/local/bin/ec

  2. Configure your shell environment for doing container image signing and verifying. 

    $ export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
$ export TUF_URL="https://tuf.${BASE_HOSTNAME}"
$ export OIDC_ISSUER_URL=OIDC_ISSUER_URL
$ export COSIGN_FULCIO_URL="https://fulcio.${BASE_HOSTNAME}"
$ export COSIGN_REKOR_URL="https://rekor.${BASE_HOSTNAME}"
$ 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

    Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname` variable, and replace OIDC_ISSUER_URL with your OpenID Connect (OIDC) provider’s URL string.

  3. Initialize The Update Framework (TUF) system: 

    $ cosign initialize

  4. Sign a test container image.

    1. Create an empty container image: 

      $ echo "FROM scratch" > ./tmp.Dockerfile
$ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

    2. Push the empty container image to the ttl.sh ephemeral registry: 

      $ podman push ttl.sh/rhtas/test-image:1h

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      $ cosign sign -y ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile

  5. Create a predicate.json file: 

    {
  "builder": {
    "id": "https://localhost/dummy-id"
  },
  "buildType": "https://example.com/tekton-pipeline",
  "invocation": {},
  "buildConfig": {},
  "metadata": {
    "completeness": {
      "parameters": false,
      "environment": false,
      "materials": false
    },
    "reproducible": false
  },
  "materials": []
}

    Refer to the Content from slsa.dev is not included.SLSA provenance predicate specifications for more information about the schema layout.

  6. Associate the predicate.json file with the container image: 

    cosign attest -y --predicate ./predicate.json --type slsaprovenance IMAGE_NAME:TAG
    $ cosign attest -y --predicate ./predicate.json --type slsaprovenance ttl.sh/rhtas/test-image:1h

  7. Verify that the container image has at least one attestation and signature: 

    cosign tree IMAGE_NAME:TAG
    $ cosign tree ttl.sh/rhtas/test-image:1h

📦 Supply Chain Security Related artifacts for an image: ttl.sh/rhtas/test-image@sha256:7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35
└── 💾 Attestations for an image tag: ttl.sh/rhtas/test-image:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.att
   └── 🍒 sha256:40d94d96a6d3ab3d94b429881e1b470ae9a3cac55a3ec874051bdecd9da06c2e
└── 🔐 Signatures for an image tag: ttl.sh/rhtas/test-image:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.sig
   └── 🍒 sha256:f32171250715d4538aec33adc40fac2343f5092631d4fc2457e2116a489387b7

  8. Verify the container image by using Conforma: 

    ec validate image --image IMAGE_NAME:TAG --certificate-identity-regexp 'SIGNER_EMAIL_ADDR' --certificate-oidc-issuer-regexp 'keycloak-system' --output yaml --show-successes
    $ ec validate image --image ttl.sh/rhtas/test-image:1h --certificate-identity-regexp 'jdoe@example.com' --certificate-oidc-issuer-regexp 'keycloak-system' --output yaml --show-successes

success: true
successes:
  - metadata:
      code: builtin.attestation.signature_check
    msg: Pass
  - metadata:
      code: builtin.attestation.syntax_check
    msg: Pass
  - metadata:
      code: builtin.image.signature_check
    msg: Pass
ec-version: v0.1.2427-499ef12
effective-time: "2024-01-21T19:57:51.338191Z"
key: ""
policy: {}
success: true

    Enterprise Contract generates a pass-fail report with details on any security violations. When you add the --info flag, the report includes more details and possible solutions for any violations found.

Additional resources

Appendix A. Service and StatefulSet YAML configuration for Red Hat build of Keycloak

The Service and StatefulSet YAML resource configuration used when configuring Red Hat’s build of Keycloak (RHBK) for Red Hat’s Trusted Artifact Signer (RHTAS) service. 

apiVersion: v1
kind: Service
metadata:
  name: postgresql-db
  namespace: keycloak-system
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
  - IPv4
  ipFamilyPolicy: SingleStack
  ports:
  - port: 5432
  selector:
    app: postgresql-db
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgresql-db
  namespace: keycloak-system
spec:
  persistentVolumeClaimRetentionPolicy:
    whenDeleted: Retain
    whenScaled: Retain
  podManagementPolicy: OrderedReady
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: postgresql-db
  serviceName: postgresql-db
  template:
    metadata:
      labels:
        app: postgresql-db
    spec:
      containers:
      - env:
        - name: POSTGRESQL_USER
          valueFrom:
            secretKeyRef:
              key: username
              name: postgresql-db
        - name: POSTGRESQL_PASSWORD
          valueFrom:
            secretKeyRef:
              key: password
              name: postgresql-db
        - name: POSTGRESQL_DATABASE
          valueFrom:
            secretKeyRef:
              key: database
              name: postgresql-db
        image: registry.redhat.io/rhel9/postgresql-15:latest
        imagePullPolicy: IfNotPresent
        livenessProbe:
          exec:
            command:
            - /usr/libexec/check-container
            - --live
          failureThreshold: 3
          initialDelaySeconds: 120
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 10
        name: postgresql-db
        readinessProbe:
          exec:
            command:
            - /usr/libexec/check-container
          failureThreshold: 3
          initialDelaySeconds: 5
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 1
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
        volumeMounts:
        - mountPath: /var/lib/pgsql/data
          name: data
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      terminationGracePeriodSeconds: 30
  updateStrategy:
    rollingUpdate:
      partition: 0
    type: RollingUpdate
  volumeClaimTemplates:
  - apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: data
    spec:
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 1Gi
      volumeMode: Filesystem

Return to configuring RHBK procedure.

Appendix B. Trusted Artifact Signer components and version numbers

The following tables list Red Hat’s Trusted Artifact Signer (RHTAS) software components and their corresponding version numbers for the 1.3.2 release.

Table B.1. Binaries

BinaryVersion

cosign

2.5.0

gitsign

0.13.0

rekor-cli

1.3.10

ec

0.7

createtree

1.7.2

updatetree

1.7.2

tuftool

0.12.0

tuffer

0.19.0

fetch-tsa-certs

1.2.8

Table B.2. Trillian

ComponentVersion

logserver

1.7.2

logsigner

1.7.2

database

1.7.2

redis

1.7.2

Table B.3. Rekor

ComponentVersion

rekor-server

1.3.10

backfill-redis

1.3.10

rekor-search-ui

Unversioned

rekor-monitor

Unversioned

Table B.4. Fulcio

ComponentVersion

fulcio-server

1.8.4

Table B.5. Certificate Transparency

ComponentVersion

certificate-transparency-go

1.3.1

Table B.6. Timestamp Authority

ComponentVersion

timestamp-authority

1.2.8

Table B.7. Policy Controller

ComponentVersion

policy-controller

0.12.0

policy-controller-operator

0.12.0

policy-controller-operator-bundle

0.12.0

Table B.8. Model Transparency

ComponentVersion

model-transparency

1.0.1

model-validation-operator

1.0.1

model-validation-operator-bundle

1.0.1

Additional resources

Legal Notice

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.