Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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
Copy link

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
Copy link

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

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.15 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
...
      Copy to Clipboard Toggle word wrap
      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
...
      Copy to Clipboard Toggle word wrap
    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.

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.

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.15 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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv cosign-amd64 /usr/local/bin/cosign
      Copy to Clipboard Toggle word wrap

  2. Log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap 
    $ oc project trusted-artifact-signer
    Copy to Clipboard Toggle word wrap
    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}')/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
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

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

      $ podman push ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      Copy to Clipboard Toggle word wrap 
      $ cosign sign -y ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

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

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile
      Copy to Clipboard Toggle word wrap

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

    cosign verify --certificate-identity=SIGNING_EMAIL_ADDR IMAGE_NAME:TAG
    Copy to Clipboard Toggle word wrap 
    $ cosign verify --certificate-identity=jdoe@redhat.com ttl.sh/rhtas/test-image:1h
    Copy to Clipboard Toggle word wrap
    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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv rekor-cli-amd64 /usr/local/bin/rekor-cli
      Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap 
      $ rekor-cli search --email jdoe@redhat.com --rekor_server $COSIGN_REKOR_URL --format json | jq
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap 
      $ rekor-cli get --uuid 24296fb24b8ad77a71b9c1374e207537bafdd75b4f591dcee10f3f697f150d7cc5d0b725eea641e7 --rekor_server $COSIGN_REKOR_URL --format json | jq
      Copy to Clipboard Toggle word wrap

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.15 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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv gitsign-amd64 /usr/local/bin/gitsign
      Copy to Clipboard Toggle word wrap

  2. Log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap 
    $ oc project trusted-artifact-signer
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap

  7. Make a commit to the local repository: 

    $ git commit --allow-empty -S -m "Test of a signed commit"
    Copy to Clipboard Toggle word wrap

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

  8. Initialize The Update Framework (TUF) system: 

    $ cosign initialize
    Copy to Clipboard Toggle word wrap

  9. Verify the commit: 

    gitsign verify --certificate-identity=SIGNING_EMAIL --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD
    Copy to Clipboard Toggle word wrap 
    $ gitsign verify --certificate-identity=jdoe@redhat.com --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD
    Copy to Clipboard Toggle word wrap

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.15 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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv ec-amd64 /usr/local/bin/ec
      Copy to Clipboard Toggle word wrap

  2. Log in to the OpenShift cluster: 

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap 
    $ oc project trusted-artifact-signer
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

  5. Initialize The Update Framework (TUF) system: 

    $ cosign initialize
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

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

      $ podman push ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      Copy to Clipboard Toggle word wrap 
      $ cosign sign -y ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

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

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile
      Copy to Clipboard Toggle word wrap

  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": []
}
    Copy to Clipboard Toggle word wrap

    Refer to the 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
    Copy to Clipboard Toggle word wrap 
    $ cosign attest -y --predicate ./predicate.json --type slsaprovenance ttl.sh/rhtas/test-image:1h
    Copy to Clipboard Toggle word wrap

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

    cosign tree IMAGE_NAME:TAG
    Copy to Clipboard Toggle word wrap 
    $ 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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap 
    $ 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
    Copy to Clipboard Toggle word wrap

    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.

1.4. Configure additional OpenID Connect providers
Copy link

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

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

  • Red Hat OpenShift Container Platform 4.15 or later.
  • Access to the OpenShift web console with the cluster-admin role.
  • A workstation with the oc, and podman binaries installed.

  • From the Google Cloud Console, create an OAuth client ID with the following settings:

Procedure

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

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
      Copy to Clipboard Toggle word wrap 
      $ oc edit Securesign securesign-sample -n trusted-artifact-signer
      Copy to Clipboard Toggle word wrap
      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
...
      Copy to Clipboard Toggle word wrap

      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"
    Copy to Clipboard Toggle word wrap

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

    echo SECRET > my-google-client-secret
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

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

      $ podman push ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    3. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile
      Copy to Clipboard Toggle word wrap

    4. Sign the container image: 

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

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

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.15 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
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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.

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.15 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
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap 
    $ oc create secret tls keycloak-tls -n keycloak-system --cert certificate.pem --key key.pem
    Copy to Clipboard Toggle word wrap
    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
...
      Copy to Clipboard Toggle word wrap

    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
...
      Copy to Clipboard Toggle word wrap
    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
...
    Copy to Clipboard Toggle word wrap 
    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
...
    Copy to Clipboard Toggle word wrap

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

  • Red Hat OpenShift Container Platform 4.15 or later.
  • Access to the OpenShift web console with the cluster-admin role.
  • A workstation with the oc, podman, and aws binaries installed.
  • Enable managed Amazon Web Service (AWS) Resources for OpenShift environments.

  • A created Amazon Identity and Access Management (IAM) user with full permissions. This allows access to run IAM operations.

    • Created access keys for this user.

Procedure

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

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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}'
    Copy to Clipboard Toggle word wrap

  3. Update RHTAS the configuration.

    1. Open for editing the Securesign resource: 

      oc edit Securesign NAME -n NAMESPACE
      Copy to Clipboard Toggle word wrap 
      $ oc edit Securesign securesign-sample -n trusted-artifact-signer
      Copy to Clipboard Toggle word wrap
      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
...
      Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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"
    Copy to Clipboard Toggle word wrap

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

    oc new-project NAMESPACE
    Copy to Clipboard Toggle word wrap 
    $ oc new-project rhtas-sts
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    2. Apply the service account manifest to OpenShift: 

      $ oc apply -f service_account.yaml
      Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    2. Apply the deployment manifest to OpenShift: 

      $ oc apply -f deployment.yaml
      Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

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

      $ podman push ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    3. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile
      Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap 
      $ oc rsh -n rhtas-sts deployment/cosign-sts env IMAGE=ttl.sh/rhtas/test-image:1h /bin/sh
      Copy to Clipboard Toggle word wrap

    2. Sign the container image: 

      $ cosign sign -y --identity-token=$(cat $AWS_WEB_IDENTITY_TOKEN_FILE) ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

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

  • Red Hat OpenShift Container Platform 4.15 or later.
  • A running Red Hat SSO instance.
  • A workstation with the oc binary installed.

  • Create a GitHub OAuth app, and after registering the application, make note of the client identifier and secret values.

    Important

    When registering your new GitHub OAuth app, you must specify the Homepage URL, and the Authorization callback URL. Enter placeholder values for both of these fields, for example, https://localhost:8080. Later in this procedure you will modify your GitHub OAuth app with the intended values for these fields.

Procedure

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

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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}'
      Copy to Clipboard Toggle word wrap
    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 to Clipboard Toggle word wrap

      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.

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.15 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)
    Copy to Clipboard Toggle word wrap

  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')
    Copy to Clipboard Toggle word wrap
    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"}'
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

  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}}"
    Copy to Clipboard Toggle word wrap

  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')
    Copy to Clipboard Toggle word wrap

  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")
    Copy to Clipboard Toggle word wrap

  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}\"}"
    Copy to Clipboard Toggle word wrap

  10. Get the tenant identifier: 

    $ export TENANT_ID=$(az account show -o tsv --query tenantId)
    Copy to Clipboard Toggle word wrap

  11. Get OIDC endpoint: 

    $ export ENTRA_ID_OIDC_ENDPOINT=$(echo https://login.microsoftonline.com/${TENANT_ID}/v2.0)
    Copy to Clipboard Toggle word wrap

  12. Update the RHTAS configuration.

    1. Open for editing the Securesign resource: 

      oc edit Securesign NAME -n NAMESPACE
      Copy to Clipboard Toggle word wrap 
      $ oc edit Securesign securesign-sample -n trusted-artifact-signer
      Copy to Clipboard Toggle word wrap
      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
...
      Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  15. Initialize the local machine for signing: 

    $ cosign initialize
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

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

      $ podman push ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    3. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile
      Copy to Clipboard Toggle word wrap

    4. Sign the container image: 

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

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

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
Copy link

  • Red Hat OpenShift Container Platform version 4.13, 4.14, or 4.15.

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 Amazon RDS console, and 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
    Copy to Clipboard Toggle word wrap 
    $ mysql -h exampledb.1234.us-east-1.rds.amazonaws.com -P 3306 -u admin -p
    Copy to Clipboard Toggle word wrap

  3. Create a new database named trillian: 

    create database trillian;
    Copy to Clipboard Toggle word wrap

  4. Switch to the newly created database: 

    use trillian;
    Copy to Clipboard Toggle word wrap

  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;
    Copy to Clipboard Toggle word wrap

  6. Disconnect from the database: 

    EXIT
    Copy to Clipboard Toggle word wrap

  7. Download the database configuration file: 

    $ curl -o dbconfig.sql https://raw.githubusercontent.com/securesign/trillian/main/storage/mysql/schema/storage.sql
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap 
    $ mysql -h rhtasdb.example.com -P 3306 -u trillian -p mypassword123 -D trillian < dbconfig.sql
    Copy to Clipboard Toggle word wrap

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

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap 
    $ 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
    Copy to Clipboard Toggle word wrap

    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.

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
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap

  10. Download the database configuration file: 

    $ curl -o dbconfig.sql https://raw.githubusercontent.com/securesign/trillian/main/storage/mysql/schema/storage.sql
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap 
    $ mysql -h rhtasdb.example.com -P 3306 -u trillian -p mypassword123 -D trillian < dbconfig.sql
    Copy to Clipboard Toggle word wrap

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

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
    Copy to Clipboard Toggle word wrap 
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Copy to Clipboard Toggle word wrap
    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
    Copy to Clipboard Toggle word wrap 
    $ 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
    Copy to Clipboard Toggle word wrap

    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.

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.15 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
      Copy to Clipboard Toggle word wrap
    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
...
    Copy to Clipboard Toggle word wrap

    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
...
    Copy to Clipboard Toggle word wrap

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

1.7. Generating Keycloak host names automatically
Copy link

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.15 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#
...
      Copy to Clipboard Toggle word wrap 
      spec:
...
  ingress:
    className: openshift-default
...
      Copy to Clipboard Toggle word wrap
      Note

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

      $ oc get ingressclass
      Copy to Clipboard Toggle word wrap
    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
...
    Copy to Clipboard Toggle word wrap

Chapter 2. Red Hat Enterprise Linux
Copy link

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 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 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.

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.

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, 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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv cosign-amd64 /usr/local/bin/cosign
      Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

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

      $ podman push ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      Copy to Clipboard Toggle word wrap 
      $ cosign sign -y ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

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

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile
      Copy to Clipboard Toggle word wrap

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

    cosign verify --certificate-identity=SIGNING_EMAIL_ADDR IMAGE_NAME:TAG
    Copy to Clipboard Toggle word wrap 
    $ cosign verify --certificate-identity=jdoe@redhat.com ttl.sh/rhtas/test-image:1h
    Copy to Clipboard Toggle word wrap
    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, 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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv rekor-cli-amd64 /usr/local/bin/rekor-cli
      Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap 
      $ rekor-cli search --email jdoe@redhat.com --rekor_server $COSIGN_REKOR_URL --format json | jq
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap 
      $ rekor-cli get --uuid 24296fb24b8ad77a71b9c1374e207537bafdd75b4f591dcee10f3f697f150d7cc5d0b725eea641e7 --rekor_server $COSIGN_REKOR_URL --format json | jq
      Copy to Clipboard Toggle word wrap

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, 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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv gitsign-amd64 /usr/local/bin/gitsign
      Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  5. Make a commit to the local repository: 

    $ git commit --allow-empty -S -m "Test of a signed commit"
    Copy to Clipboard Toggle word wrap

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

  6. Initialize The Update Framework (TUF) system: 

    $ cosign initialize
    Copy to Clipboard Toggle word wrap

  7. Verify the commit: 

    gitsign verify --certificate-identity=SIGNING_EMAIL --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD
    Copy to Clipboard Toggle word wrap 
    $ gitsign verify --certificate-identity=jdoe@redhat.com --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD
    Copy to Clipboard Toggle word wrap

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, 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
      Copy to Clipboard Toggle word wrap

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

      $ sudo mv ec-amd64 /usr/local/bin/ec
      Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

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

      $ podman push ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

    3. Sign the container image: 

      cosign sign -y IMAGE_NAME:TAG
      Copy to Clipboard Toggle word wrap 
      $ cosign sign -y ttl.sh/rhtas/test-image:1h
      Copy to Clipboard Toggle word wrap

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

    4. Remove the temporary Docker file: 

      $ rm ./tmp.Dockerfile
      Copy to Clipboard Toggle word wrap

  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": []
}
    Copy to Clipboard Toggle word wrap

    Refer to the 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
    Copy to Clipboard Toggle word wrap 
    $ cosign attest -y --predicate ./predicate.json --type slsaprovenance ttl.sh/rhtas/test-image:1h
    Copy to Clipboard Toggle word wrap

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

    cosign tree IMAGE_NAME:TAG
    Copy to Clipboard Toggle word wrap 
    $ 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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap 
    $ 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
    Copy to Clipboard Toggle word wrap

    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.

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
Copy to Clipboard Toggle word wrap 
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
Copy to Clipboard Toggle word wrap

Return to configuring RHBK procedure.

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

Expand
Table B.1. Binaries
BinaryVersion

cosign

2.4.3

gitsign

0.12.0

rekor-cli

1.3.9

ec

0.6

createtree

1.7.1

updatetree

1.7.1

tuftool

0.12.0

tuffer

0.17.1

fetch-tsa-certs

1.2.4

Expand
Table B.2. Trillian
ComponentVersion

logserver

1.7.1

logsigner

1.7.1

database

1.7.1

redis

1.7.1

Expand
Table B.3. Rekor
ComponentVersion

rekor-server

1.3.9

backfill-redis

1.3.9

rekor-search-ui

1.3.9

Expand
Table B.4. Fulcio
ComponentVersion

fulcio-server

1.6.6

Expand
Table B.5. Certificate Transparency
ComponentVersion

certificate-transparency-go

1.3.1

Expand
Table B.6. Timestamp Authority
ComponentVersion

timestamp-authority

1.2.4

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, 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, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat