Deployment Guide

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. 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 Google OAuth, Amazon STS, Red Hat’s SSO, or GitHub OAuth as the initial OIDC provider during this deployment. Under the spec.fulcio.config.OIDCIssuers section, edit the following three lines with the OIDC provider URL, and set the ClientID appropriately.

      Example

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

      Important

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

      Note

      If Red Hat’s SSO is already implemented as your OIDC provider, then run the following command to find the issuer URL:

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

      Set the ClientID to trusted-artifact-signer.

   7. Optional. If using 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.

      Example

      ...
      trillian:
        database:
          create: false
          databaseSecretRef:
            name: trillian-mysql
      ...

   8. Click the Create button.

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

   Note

   The Securesign instance does not give a status.

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

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.

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 execute bit:

      Example

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

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

      Example

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

2. Log in to the OpenShift cluster:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

3. Switch to the RHTAS project:

   Syntax

   oc project PROJECT_NAME

   Example

   $ oc project trusted-artifact-signer

   Note

   Use the project name for the RHTAS installation.

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

   Example

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

5. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

6. Sign a test container image.

   1. Create an empty container image:

      Example

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

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

      Example

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

   3. Sign the container image:

      Syntax

      cosign sign -y IMAGE_NAME:TAG

      Example

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

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

   4. Remove the temporary Docker file:

      Example

      $ rm ./tmp.Dockerfile

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

   Syntax

   cosign verify --certificate-identity=SIGNING_EMAIL_ADDR IMAGE_NAME:TAG

   Example

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

   Note

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

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

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

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

      Example

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

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

      Example

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

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

   1. Search based on the log index:

      Example

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

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

      Syntax

      rekor-cli search --email SIGNING_EMAIL_ADDR --rekor_server $COSIGN_REKOR_URL --format json | jq

      Example

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

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

   3. Use the UUID to get the transaction details:

      Syntax

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

      Example

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

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 execute bit:

      Example

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

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

      Example

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

2. Log in to the OpenShift cluster:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

3. Switch to the RHTAS project:

   Syntax

   oc project PROJECT_NAME

   Example

   $ oc project trusted-artifact-signer

   Note

   Use the project name for the RHTAS installation.

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

   Example

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

5. Configure the local repository configuration to sign your commits by using the RHTAS service:

   Example

   $ 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

6. Make a commit to the local repository:

   Example

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

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

7. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

8. Verify the commit:

   Syntax

   gitsign verify --certificate-identity=SIGNING_EMAIL --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD

   Example

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

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 execute bit:

      Example

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

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

      Example

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

2. Log in to the OpenShift cluster:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

3. Switch to the RHTAS project:

   Syntax

   oc project PROJECT_NAME

   Example

   $ oc project trusted-artifact-signer

   Note

   Use the project name for the RHTAS installation.

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

   Example

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

5. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

6. Sign a test container image.

   1. Create an empty container image:

      Example

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

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

      Example

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

   3. Sign the container image:

      Syntax

      cosign sign -y IMAGE_NAME:TAG

      Example

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

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

   4. Remove the temporary Docker file:

      Example

      $ rm ./tmp.Dockerfile

7. Create a predicate.json file:

   Example

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

   Refer to the SLSA provenance predicate specifications for more information about the schema layout.

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

   Syntax

   cosign attest -y --predicate ./predicate.json --type slsaprovenance IMAGE_NAME:TAG

   Example

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

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

   Syntax

   cosign tree IMAGE_NAME:TAG

   Example

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

10. Verify the container image by using Enterprise Contact:

    Syntax

    ec validate image --image IMAGE_NAME:TAG --certificate-identity-regexp 'SIGNER_EMAIL_ADDR' --certificate-oidc-issuer-regexp 'keycloak-keycloak-system' --output yaml --show-successes

    Example

    $ ec validate image --image ttl.sh/rhtas/test-image:1h --certificate-identity-regexp 'jdoe@example.com' --certificate-oidc-issuer-regexp 'keycloak-keycloak-system' --output yaml --show-successes
    
    success: true
    successes:
      - metadata:
          code: builtin.attestation.signature_check
        msg: Pass
      - metadata:
          code: builtin.attestation.syntax_check
        msg: Pass
      - metadata:
          code: builtin.image.signature_check
        msg: Pass
    ec-version: v0.1.2427-499ef12
    effective-time: "2024-01-21T19:57:51.338191Z"
    key: ""
    policy: {}
    success: true

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

Procedure

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

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

2. Update the RHTAS configuration.

   1. Open for editing the Securesign resource:

      Syntax

      oc edit Securesign NAME -n NAMESPACE

      Example

      $ oc edit Securesign securesign-sample -n trusted-artifact-signer

      Note

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

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

      Syntax

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

      Add you Google client identifier to the ClientID field.

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

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

   Example

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

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

   Syntax

   echo SECRET > my-google-client-secret

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

   1. Create an empty container image:

      Example

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

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

      Example

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

   3. Remove the temporary Docker file:

      Example

      $ rm ./tmp.Dockerfile

   4. Sign the container image:

      Syntax

      cosign sign -y --oidc-client-secret-file=SECRET_FILE IMAGE_NAME:TAG

      Example

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

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

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:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

10. Switch to the Keycloak project:

    Example

    $ oc project keycloak-system

11. Create a Keycloak instance:

    Example

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

12. Create a Keycloak realm:

    Example

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

13. Create a Keycloak client:

    Example

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

14. Create a Keycloak user:

    Example

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

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

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

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 Value field. 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 Value field. 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 Value field. 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. Open a terminal from your workstation, and log in to the OpenShift cluster:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

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

   Syntax

   oc create secret tls SECRET_NAME -n NAMESPACE --cert CERTIFICATE_FILE_NAME --key PRIVATE_KEY_FILE_NAME

   Example

   $ oc create secret tls keycloak-tls -n keycloak-system --cert certificate.pem --key key.pem

   Note

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

6. In OpenShift web console, expand Operators from the navigation menu, and click OperatorHub.
7. In the search field, type keycloak, and click the Keycloak Operator tile from the certified Red Hat catalog.
8. Click the Install button to show the operator details.
9. 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.
10. 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 host name 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 host name.

       Note

       See the appendix for the steps necessary to have OpenShift generate the host name for the Keycloak instance.

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

       Example

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

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

       Example

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

    5. Click the Create button.
13. Expand the Networking navigation menu, and click Routes.
14. To open the Keycloak Administration Console, click the link to the route associated with the Keycloak instance.
15. The default credentials for the admin user are stored in a Secret called keycloak-initial-admin. To locate the password, expand the Workloads navigation menu, and click Secrets.
16. Select the keycloak-initial-admin Secret.
17. Under the Data section, locate the password key, and click the icon.
18. On the Keycloak Administration Console log in page, enter 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 User. The new user can log in to the Keycloak Administration Console, and can also sign containers and commits using RHTAS.

    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:

    Syntax

    spec:
    ...
      fulcio:
        config:
          OIDCIssuers:
            - ClientID: CLIENT_ID
              Issuer: 'RHBK_REALM_ISSUER_URL'
              IssuerURL: 'RHBK_REALM_ISSUER_URL'
              Type: email
    ...

    Example

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

Procedure

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

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

2. Find the AWS OIDC provider URL:

   Example

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

3. Update RHTAS the configuration.

   1. Open for editing the Securesign resource:

      Syntax

      oc edit Securesign NAME -n NAMESPACE

      Example

      $ oc edit Securesign securesign-sample -n trusted-artifact-signer

      Note

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

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

      Example

      ...
      OIDCIssuers:
        - Issuer: "https://example.s3.us-east-1.aws.com/47bd6cg0vs5nn01mue83fbof94dj4m9c"
          IssuerURL: "https://example.s3.us-east-1.aws.com/47bd6cg0vs5nn01mue83fbof94dj4m9c"
          ClientID: "trusted-artifact-signer"
          Type: kubernetes
      ...

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

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

   Example

   $ aws configure

5. Set the following environment variables:

   Example

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

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

   Example

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

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

   Example

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

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

   Syntax

   oc new-project NAMESPACE

   Example

   $ oc new-project rhtas-sts

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

   1. Create the service account manifest:

      Example

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

   2. Apply the service account manifest to OpenShift:

      Example

      $ oc apply -f service_account.yaml

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

    1. Create the deployment manifest:

       Example

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

    2. Apply the deployment manifest to OpenShift:

       Example

       $ oc apply -f deployment.yaml

11. Create a test container image to sign.

    1. Create an empty container image:

       Example

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

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

       Example

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

    3. Remove the temporary Docker file:

       Example

       $ rm ./tmp.Dockerfile

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

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

       Syntax

       oc rsh -n NAMESPACE deployment/cosign-sts env IMAGE=IMAGE_NAME:TAG /bin/sh

       Example

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

    2. Sign the container image:

       Example

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

    3. Verify the signed container image:

       Example

       $ 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

Procedure

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

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

2. Log in to the Red Hat SSO console.

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

      Example

      $ oc get routes -n keycloak-system keycloak -o jsonpath='https://{.spec.host}'

   2. Copy and paste the Red Hat SSO console URL into your web browser.
   3. Click Administration Console.

   4. Retrieve the admin password from the command line:

      Example

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

      Copy the output from this command.

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

4. Add the GitHub identity provider.

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

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

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

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:

   Syntax

   mysql -h REGIONAL_ENDPOINT -P 3306 -u USER_NAME -p

   Example

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

3. Create a new database named trillian:

   Example

   create database trillian;

4. Switch to the newly created database:

   Example

   use trillian;

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

   Syntax

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

6. Disconnect from the database:

   Example

   EXIT

7. Download the database configuration file:

   Example

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

8. Apply the database configuration to the new database:

   Syntax

   mysql -h FQDN_or_SERVICE_ADDR -P 3306 -u USER_NAME -p PASSWORD -D DB_NAME < PATH_TO_CONFIG_FILE

   Example

   $ mysql -h rhtasdb.example.com -P 3306 -u trillian -p mypassword123 -D trillian < dbconfig.sql

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

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

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

   Note

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

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

    Syntax

    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

    Example

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

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

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

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:

   Example

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

   Note

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

9. Disconnect from the database:

   Example

   EXIT

10. Download the database configuration file:

    Example

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

11. Apply the database configuration to the new database:

    Syntax

    mysql -h FQDN_or_SERVICE_ADDR -P 3306 -u USER_NAME -p PASSWORD -D DB_NAME < PATH_TO_CONFIG_FILE

    Example

    $ mysql -h rhtasdb.example.com -P 3306 -u trillian -p mypassword123 -D trillian < dbconfig.sql

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

    Syntax

    oc login --token=TOKEN --server=SERVER_URL_AND_PORT

    Example

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

    Note

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

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

    Syntax

    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

    Example

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

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

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